> For the complete documentation index, see [llms.txt](https://mole-resource.gitbook.io/mole-resource-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mole-resource.gitbook.io/mole-resource-docs/scripts/4-in-line/housing.md).

# Housing

Boards are **instance-aware**: a board is only visible to and interactable by players who share its instance. This lets boards placed inside an apartment or instanced property stay private to that property.

## How instances work

* Every player has an **instance** value (a string, or `nil` for the default world).
* A board stores the instance of the player who placed it.
* A player only sees boards whose instance matches their own.

By default everyone is in the `nil` (default) instance, so without any integration boards behave like normal world objects.

## Integrating with a housing system

Call the exports when a player **enters** or **leaves** an instanced area (apartment, motel room, MLO shell, etc.). Use a unique, stable ID per property.

```lua
-- Player enters apartment 152
exports['mr_4inline']:SetPlayerInstance(source, PropertyId)

-- Player leaves — back to the default world
exports['mr_4inline']:SetPlayerInstance(source, nil)
```

When the instance changes, the script automatically:

* removes the player from any board they were seated at (and ends solo sessions),
* re-syncs the boards visible in their new instance.

> The export is looked up by **resource name**. If you renamed the resource folder, use the new name here — a call to a resource that isn't running throws an error on every property entry.

## Placing boards inside instances

To place a board while inside an instance, the player must have an instance set. If a player is in a non-default routing bucket **without** an instance set, placement is blocked with the *housing system integration required* message — this prevents "ghost" boards ending up in the wrong shell.

## Reference

| Export                             | Returns         | Description                                          |
| ---------------------------------- | --------------- | ---------------------------------------------------- |
| `SetPlayerInstance(src, instance)` | —               | Assigns the player to an instance (`nil` = default). |
| `GetPlayerInstance(src)`           | `string \| nil` | Returns the player's current instance.               |

Instance strings are sanitised server-side (trimmed, capped at 64 characters).