> For the complete documentation index, see [llms.txt](https://code-after-sex.gitbook.io/script-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://code-after-sex.gitbook.io/script-documentation/cas-housing/developers.md).

# For developers

CAS Housing for developers. Server and client exports, server events, key roles, knocking, the home stable, spawning at home and the lockpick hook.

The resource name is `cas-housing`. A property is known by its number (`id`). A character is known by the framework's own id with a prefix: `vorp:<charIdentifier>`, `rsg:<citizenid>`, or the licence on a standalone server.

## Server exports

```lua
local housing = exports["cas-housing"]
```

| Export                                         | Answer                                                                                                                                                                            |
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GetProperty(id)`                              | the property (below), or `nil`                                                                                                                                                    |
| `GetProperties()`                              | every property                                                                                                                                                                    |
| `GetOwnedBy(src)`                              | the properties that player's character holds (bought or rented)                                                                                                                   |
| `GetPropertyByDoor(doorHash)`                  | the id of the property that door belongs to, or `nil`                                                                                                                             |
| `GetPropertyAt(x, y, z)`                       | the id of the property whose zone holds that spot, or `nil`                                                                                                                       |
| `IsInside(src, id)`                            | `true` when the player is inside the property's zone                                                                                                                              |
| `HasKey(src, id)`                              | `true` for the owner and for key holders, whatever the role of their key                                                                                                          |
| `GetKeyRole(id, character)`                    | `"owner"`, `"coowner"`, `"roommate"`, `"guest"`, or `nil` without a key. `character` is `"vorp:12"` or the framework's own id (`12`, an RSG citizenid)                            |
| `GetSpawn(src)`                                | `{ x, y, z, heading, propertyId }` of the bed the character chose ("Wake up here"), or `nil`                                                                                      |
| `AddFurniture(id, model, x, y, z, rx, ry, rz)` | `true` when accepted: a catalogue model where a player could place it (inside the zone; an outdoor piece only on a plot or in a home's yard). No money, no limit. For admin tools |
| `RemoveFurniture(pieceId)`                     | `true` when that piece existed                                                                                                                                                    |
| `BreachDoor(id, seconds, src)`                 | opens the property's doors for everyone for 5 to 3600 seconds without turning the lock. `src` (optional) is who did it. `true` when the property exists                           |

A property:

```lua
{
  id = 3, name = "Valentine Cottage", kind = "home",        -- or "plot"
  price = 500, rent = 25,                                   -- rent a week, nil when it cannot be rented
  limit = 120, storage = 50,                                -- furniture limit, storage slots
  yard = 10,                                                -- a home's yard: metres around its zone for outdoor pieces (0: none)
  entrance = { x, y, z, heading }, spawn = { x, y, z, heading },   -- spawn may be nil
  zone = { shape = "poly", points = { { x, y }, ... }, minZ = , maxZ = },  -- or "circle" (center, radius), "box"
  doors = { { doorHash, modelHash, x, y, z }, ... },
  owned = true, owner = "vorp:12", ownerName = "Sadie Adler", tenure = "owned",   -- or "rented"; nil when for sale
  locked = true, paidUntil = 1765000000000, pieces = 64,    -- paidUntil: ms, for rented (or taxed) homes
}
```

`entrance`, `spawn`, zone points and doors are plain lists: `entrance[1]` is x, `entrance[4]` the heading; `doors[1][1]` is the first door's hash.

`AddFurniture` and `RemoveFurniture` answer at once and write in the background; the clients near the property see the change a moment later.

## Server events

Listen with `AddEventHandler`. They are local server events: a client cannot fire them.

| Event                            | Arguments                                                                                                                                                      |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cas-housing:server:bought`      | `src, propertyId, mode ("buy" or "rent"), paid`                                                                                                                |
| `cas-housing:server:sold`        | `src, propertyId, refund`                                                                                                                                      |
| `cas-housing:server:transferred` | `fromSrc, toSrc, propertyId, price`: the deed went to another player. `price` is 0 for a hand-over, what the buyer paid for a sale to a player (`Config.Sale`) |
| `cas-housing:server:keyGiven`    | `bySrc, targetSrc, propertyId, role`: the owner, or a co-owner, gave a key                                                                                     |
| `cas-housing:server:keyTaken`    | `bySrc, holderCharacter, propertyId`                                                                                                                           |
| `cas-housing:server:keyRole`     | `ownerSrc, holderCharacter, propertyId, role`: the owner changed the role of a key                                                                             |
| `cas-housing:server:lockChanged` | `propertyId, locked, bySrc`                                                                                                                                    |
| `cas-housing:server:entered`     | `src, propertyId`                                                                                                                                              |
| `cas-housing:server:left`        | `src, propertyId`                                                                                                                                              |
| `cas-housing:server:repossessed` | `propertyId, ownerCharacter, reason ("rent", "tax" or "admin")`                                                                                                |
| `cas-housing:server:doorTry`     | `src, propertyId, doorHash, locked`: someone without a key tried a door                                                                                        |
| `cas-housing:server:breached`    | `propertyId, seconds, bySrc`: the doors were opened for a while (a warrant, your script)                                                                       |
| `cas-housing:server:knocked`     | `knockerSrc, propertyId`: someone without a key knocked at the door                                                                                            |
| `cas-housing:server:letIn`       | `holderSrc, knockerSrc, propertyId`: a holder inside let the knocker in (the doors open for them alone for `Config.Knock.OpenSeconds`)                         |

And one you may fire yourself, the same as the `BreachDoor` export:

```lua
TriggerEvent("cas-housing:server:breach", propertyId, 60, src)
```

## Client exports and events

```lua
exports["cas-housing"]:CurrentProperty()   -- the property the player stands in, or nil
exports["cas-housing"]:GetProperty(id)     -- a property as this player sees it (mine, key, role, perms, locked, open)
exports["cas-housing"]:HomeSpawn()         -- { x, y, z, heading, propertyId } of the chosen bed, or nil
```

| Event                     | Arguments                                                                   |
| ------------------------- | --------------------------------------------------------------------------- |
| `cas-housing:bought`      | `propertyId, mode, paid`                                                    |
| `cas-housing:sold`        | `propertyId, refund`                                                        |
| `cas-housing:entered`     | `propertyId`                                                                |
| `cas-housing:left`        | `propertyId`                                                                |
| `cas-housing:lockChanged` | `propertyId, locked`                                                        |
| `cas-housing:doorLocked`  | `propertyId, doorHash`: this player pressed "Try the door" at a locked door |

## Key roles

Every key is a co-owner's, a roommate's or a guest's; `Config.KeyRoles` says what each may do (lock, storage, wardrobe, spawn, build, buildAll, keys, pay, letIn, stable) and the owner may do everything. On the client, `GetProperty(id)` carries `role` (this player's: `"owner"`, `"coowner"`, `"roommate"`, `"guest"`, or `nil`) and `perms` (a table of those ten names, `true` or `false`; `nil` without a key):

```lua
local p = exports["cas-housing"]:GetProperty(id)
if p and p.perms and p.perms.storage then --[[ this player may open the home's storage ]] end
```

On the server, `GetKeyRole(id, character)` answers by character, also for a holder who is offline:

```lua
if exports["cas-housing"]:GetKeyRole(propertyId, "vorp:" .. charIdentifier) == "coowner" then ... end
```

## Knocking

A player without a key knocks at the door of an owned home ("Knock"); the holders inside whose role has `letIn` are told and answer with "Let in" or "Ignore" (`Config.Knock`). Your script hears both sides:

```lua
AddEventHandler("cas-housing:server:knocked", function(knockerSrc, propertyId)
    -- a doorbell, a log line, a dog that barks
end)
AddEventHandler("cas-housing:server:letIn", function(holderSrc, knockerSrc, propertyId)
    -- the doors are open for knockerSrc alone for Config.Knock.OpenSeconds; the lock stays turned
end)
```

## The home stable (CAS Stables)

A hitching post placed at a home brings the player's own horse out of CAS Stables, a wagon spot their wagon (see [The yard and the home stable](/script-documentation/cas-housing/yard-and-stables.md)). CAS Housing calls CAS Stables' exports `HomeStableList`, `HomeTakeOut` and `HomePutAway` (resource `Config.Stables.Resource`, default `cas-stables`); a stable script of your own can stand in by running under that name with the same three exports and answers.

Nothing new for other scripts to call. Two local server events carry the calls between this resource's JavaScript and its Lua bridge (`cas-housing:stables:ask`, `cas-housing:stables:answer`): they are internal, and the bridge ignores an ask from another resource.

## Spawning at home

This resource never touches a spawn flow. A spawn script has two ways:

```lua
-- server: where does this character want to wake up?
local bed = exports["cas-housing"]:GetSpawn(source)
if bed then --[[ spawn them at bed.x, bed.y, bed.z, bed.heading ]] end

-- or client: put the player in their bed now (nothing happens when they chose no home)
TriggerEvent("cas-housing:spawnHome")           -- from a client script
TriggerClientEvent("cas-housing:spawnHome", src) -- from a server script
```

## Lockpicks and raids

CAS Housing has no lockpick of its own. A player without a key gets "Try the door" at a locked, owned home. That fires `cas-housing:doorLocked` on their client and `cas-housing:server:doorTry` on the server. Your script answers:

```lua
-- client: your minigame
AddEventHandler("cas-housing:doorLocked", function(propertyId, doorHash)
    if not HasLockpick() then return end
    StartMyMinigame(function(won)
        if won then TriggerServerEvent("my-lockpick:opened", propertyId) end
    end)
end)

-- server: open the doors for a minute, for everyone
RegisterNetEvent("my-lockpick:opened", function(propertyId)
    local src = source
    -- check the item, the distance and a cooldown here: never trust the client
    exports["cas-housing"]:BreachDoor(propertyId, 60, src)
end)
```

The lock itself stays turned: when the time is over the doors are shut again. `Config.Warrant` gives lawmen the same through "Force the door", and tells the owner.
