Exports and events
aty_housing: Exports and events
Overview · Installation · Configuration · Features and commands · Living · Home security · Economy, upgrades and the player market · Furniture, lighting and yards · Apartments, buildings and motels · Exports and events · Webhooks and migration · Troubleshooting
Exports
The open integration API lives in server/api.lua (and the storage-unit exports in server/storage_units_view.lua). The API file stays unencrypted so you can read exactly what is exposed.
- All exports are server-side except
useTablet. - They answer from memory and never yield. While
aty_housingis not ready (server start, database down) they return the "not ready" value shown in the tables. - Coordinates are
{ x, y, z, w }tables read from a standing ped. Place a ped there withSetEntityCoords(ped, x, y, z - 1.0). - A character id is the framework character id as a string (QBCore citizenid, ESX identifier). Functions that take
srcOrCharIdaccept a server id (number) or a character id (string). - The permission names are
enter,lock,stash,decor,manageKeys,garage,payBills,security,upgradesandexterior(lock= lock and unlock the door;security= cameras and alarm, see Home security;upgrades= buy property upgrades, see Property upgrades;exterior= decorate the yard, see Garden and exterior decor).
Server exports
| Export | Returns | Not ready |
|---|---|---|
GetProperty(id) |
Public property table { id, label, kind ('ipl'/'shell'/'mlo'), interior, entrance, garage?, forSale, forRent, salePrice, rentPrice, owned, tenure ('owned'/'rented'/nil), locked }. No owner id, stash key or key list. nil for an unknown id |
nil |
GetPropertiesByCharacter(charId) |
Array of the same tables plus relation ('owner', 'tenant' or 'key') for every property the character owns, rents or holds a key to, sorted by id |
{} |
HasAccess(srcOrCharId, propertyId, perm) |
boolean: may this player do perm on this property? Rights only; the door lock state is not part of it. A police seal removes enter, stash, decor and garage from everyone |
false |
IsInside(src) |
propertyId, isPreview, or nil when the player is in no IPL or shell property (MLO properties have no inside record) |
nil |
GetGarages() |
Array of { propertyId, label, coords, capacity, ownerCharId, members, memberExpiry } for every owned or rented property with a garage point (see Config.Garage). members = character ids other than the owner with the garage permission; memberExpiry = { [charId] = unix time } for members whose key expires |
nil (tells "not yet" apart from "no garages") |
GetSpawnPoints(srcOrCharId) |
Array of { propertyId, label, coords, default } for the properties the character may enter; coords is the entrance outside. The owner's chosen "wake up here" property comes first with default = true |
{} |
IsSealed(propertyId) |
boolean |
false |
GetSeal(propertyId) |
{ caseNo, reason, sealedAt, expiresAt, officerName } (expiresAt = nil means until lifted), or nil when the property is not sealed |
nil |
RegisterHook(name, fn) |
Hook id, or nil for an unknown name or a non-function. See Hooks |
registration works before ready |
RegisterTabletSection(name, fn, opts?) |
true, or nil plus a console error. See Tablet extensions |
registration works before ready |
RegisterTabletAction(name, fn, opts?) |
true, or nil plus a console error |
registration works before ready |
PushNotification(target, category, text, vars?, opts?) |
true, or false, reason. See Notifications from other resources |
false, 'not_ready' |
GetStorageUnit(unitKey) |
{ key, facility, facilityLabel, code, tier, state, tenure, paidUntil, slots, weight, door }; no owner id or stash key. state is free, active, late, evicted or orphan |
nil |
GetStorageUnitsByCharacter(charId) |
Array of the same tables plus relation ('owner' or 'shared'), sorted by key |
{} |
HasStorageUnitAccess(srcOrCharId, unitKey) |
boolean: may the player open the unit right now (owner or share, not evicted, not late while lockWhenLate, not an orphan)? |
false |
RegisterUnitHook(name, fn) |
Hook registration for storage units. See Hooks | registration works before ready |
GetSecurityState(propertyId) |
{ installed, mode, cameras }: alarm installed, mode ('none', 'off', 'arming', 'armed', 'sounding') and the number of cameras. See Home security |
nil |
SetAlarmArmed(propertyId, armed) |
true, message or false, reason: arm or disarm without a permission or PIN check (logged as api) |
false, 'not_ready' |
TriggerAlarm(propertyId, reason?) |
true or false, reason: sound an armed alarm |
false, 'not_ready' |
GetSecurityCameras(propertyId) |
Array of { key, kind ('studio'/'exterior'), space ('world'/'instance'), label, x, y, z, heading } (position = the lens) |
nil |
HasSecurityUpgrade(propertyId, name?) |
Upgrade level (name defaults to 'alarm'), 0 = not installed |
0 |
GetUpgrades(propertyId) |
{ [upgrade] = { level, max, paid } } for every catalog upgrade. See Property upgrades |
nil |
GetUpgradeLevel(propertyId, upgrade) |
Level, 0 = none |
0 |
GetUpgradeBonus(propertyId, key) |
What the upgrades add now (stashSlots, stashWeight, extraSlots, extraWeight, garageSlots, decorObjects, exteriorObjects, studioCams, exteriorCams, powerPct, waterPct) |
0 |
SetUpgradeLevel(propertyId, upgrade, level) |
true, or false, reason: set a level without money or a permission check (logged as api) |
false, 'not_ready' |
GetLightScene(propertyId) |
{ home, groups, lamps, details, now }: the light scenes and interior detail choices of a property. See Lighting and colours |
nil |
SetLightScene(propertyId, scope, id, scene) |
true, or false, reason: set (or, with scene = nil, reset) the scene of 'home', a switch ('group') or a lamp ('lamp'); no permission check, no hook |
false, 'not_ready' |
SetInteriorDetails(propertyId, group, sets) |
true, or false, reason: choose the entity sets of one interior detail group |
false, 'not_ready' |
GetBuildings() |
Array of { id, label, mode, points, blip, floors, elevator } for every apartment building or motel. See Apartments, buildings and motels |
{} |
GetBuildingOfProperty(propertyId) |
{ id, label, mode, floor, number }, or nil when the property is no building unit |
nil |
EnsureStarterApartment(charId) |
Gives the starter unit a new character is still owed (its first login was seen while starter mode was on, no vacant unit at the time). The property id given now, or nil; never gives a unit to a character that existed before |
nil |
GetOwnershipLimits(charId) |
{ enabled, bypass, owned = { count, max }, rented, total?, kinds }. See Ownership limits |
{ enabled = false } |
CanAcquireProperty(charId, propertyId, tenure?, opts?) |
true, or false, message |
false, 'not_ready' |
GetInsurance(propertyId) |
Policy table or nil. See Home insurance |
nil |
GetInsuranceClaims(propertyId, limit?) |
Array of claims, newest first | {} |
GetFurnitureStock(charId) |
{ [model] = n }: the pieces of My furniture. See Furniture store |
{} |
GiveFurniture(charId, model, count?, paid?) / TakeFurniture(charId, model, count?) |
true, or false, reason |
false, 'fs_off' |
GetFurnitureStores() |
Public store list | {} |
GetFurnitureDeliveries(filter?) |
Open scheduled orders ('all' adds pick-up orders) |
{} |
ClaimFurnitureDelivery(orderId, src) / ReleaseFurnitureDelivery(orderId) / CompleteFurnitureDelivery(orderId, src?) |
true, or false, reason: courier script integration |
false, 'not_found' |
GetMarketListings(mode?) / GetMarketListing(listingId) |
Open player-market listings (mode 'sale' or 'lease'), or one listing. See Player marketplace and contracts |
nil |
GetContract(contractId) / GetContractsOf(charId, limit?) |
A contract (with sellerId, buyerId, brokerId), or a character's contracts, newest first |
nil |
GetActiveLease(propertyId) |
{ contractId, tenant, tenantName, landlord, rent, periodDays, startAt, endAt, paidThrough, status }, or nil when the property is not leased |
nil |
CancelContract(contractId, reason?) |
true: a pending contract was cancelled and its escrow refunded; false otherwise |
false |
Client export
| Export | Description |
|---|---|
exports.aty_housing:useTablet() |
Opens the housing tablet for the local player. Use it as the client.export of an ox_inventory item or from any inventory that can run a client export. It only opens the tablet; every action inside is checked on the server |
Examples
-- Server: may this player use the stash of property 12?
if exports.aty_housing:HasAccess(source, 12, 'stash') then
-- ...
end
-- Server: list every property a character owns, rents or holds a key to
local props = exports.aty_housing:GetPropertiesByCharacter(charId)
for _, p in ipairs(props) do
print(p.id, p.label, p.relation, p.locked)
end
-- Server: is the player inside a property, and is it only a preview?
local propertyId, isPreview = exports.aty_housing:IsInside(source)
-- Server: an MDT showing a seal
local seal = exports.aty_housing:GetSeal(propertyId)
if seal then
print(('Case %s, sealed by %s'):format(seal.caseNo, seal.officerName))
end
-- Client: an inventory item that opens the tablet
exports.aty_housing:useTablet()
Tablet extensions
Other resources can register their own tablet data and actions. The built-in tablet only shows its own tabs, so an extension is meant to be loaded by a NUI that knows its name.
-- Section: the NUI loads it with `tablet:load { section = 'my_resource:stats' }`
exports.aty_housing:RegisterTabletSection('my_resource:stats', function(src, ctx)
-- ctx = { charId, roles? }
return { visits = 12 } -- or: return nil, 'not_available'
end, { role = 'realtor' }) -- optional: 'realtor' | 'police' | 'admin'
-- Action: the NUI sends `action { name = 'my_resource:ping', propertyId, args }`
exports.aty_housing:RegisterTabletAction('my_resource:ping', function(src, propertyId, args)
if not exports.aty_housing:HasAccess(src, propertyId, 'enter') then
return { ok = false, message = 'no_permission' }
end
return { ok = true, message = 'Pong' }
end, { noProperty = false }) -- { noProperty = true }: propertyId may be nil
Rules: names are <your resource>:<name> (letters, digits, _ and -, at most 64 characters in total). A name of aty_housing or of another resource is refused; registering the same name again from the same resource replaces it. aty_housing checks the name, a per-player rate limit, the character and the role before it calls your function. For an action, the property may not exist: your function checks existence and rights itself (for example with HasAccess). Registrations are removed when your resource stops; when aty_housing itself restarts they are all gone, so register again when it starts (see the hook example).
Notifications from other resources
PushNotification sends a notification into the notification center of the tablet: a popup when the character is online, an entry in their tablet either way (offline characters get it in the summary at their next login).
exports.aty_housing:PushNotification(source, 'system', 'Your vehicle insurance ends tomorrow.', nil, {
priority = 'warning',
group = 'insurance',
})
| Parameter | Description |
|---|---|
target |
Server id (number) or character id (string) |
category |
finance, rent, bills, keys, access, storage, realtor, auctions, transfers, decor or system. Only resources listed in Config.Notifications.externalResources choose it; every other resource always posts under system |
text |
Plain text, 1 to 160 characters, no control characters and no < or >. Or an aty_housing locale key listed in Config.Notifications.externalKeys; any other key is shown as plain text, so a resource cannot send housing's own texts such as a repossession |
vars |
{name} values for an allowed locale key (scalars only) |
opts |
priority ('info', 'success', 'warning', 'critical'; critical only for externalResources, otherwise at most warning), toast = false (no popup), group = 'name' (repeats merge into one entry "x N"), link = { tab, property?, listing?, sub? } |
The entry shows the sending resource. Each resource has its own rate limit per character (Config.Notifications.externalPerMinute). Failure reasons: not_ready, invalid_target, invalid_text, no_character, invalid_key, not_allowed (see Integrations).
Events
Server events
Server-local events, triggered with TriggerEvent. Listen with AddEventHandler only, never RegisterNetEvent: a net registration would let any client fake them.
| Event | Arguments | Fired when |
|---|---|---|
aty_housing:propertyChanged |
(propertyId) |
A property was created, edited, deleted, bought, rented, vacated, locked or unlocked, or rent was paid |
aty_housing:ownerChanged |
(propertyId, oldCharId, newCharId) |
Bought or rented (nil to character); sold, rental ended, evicted, repossessed, transferred or an owned property deleted (character to nil, or to the new owner on a transfer). A tenant counts as the owner |
aty_housing:keysChanged |
(propertyId) |
A key was given or taken, or every key dropped (sale, end of rental, eviction, delete) |
aty_housing:garageChanged |
none | The GetGarages() list may have changed (ownership, keys, garage point, label, a seal). Coalesced within 500 ms; also fired once when aty_housing is ready |
aty_housing:doorbell |
(propertyId, visitorCharId, result) |
A ring ended. result: letin, ignored, missed or nobody |
aty_housing:sealChanged |
(propertyId, sealed, caseNo) |
A property was sealed (true) or a seal was lifted or expired (false) |
aty_housing:raid |
(propertyId, officerCharId, warrant) |
An officer forced entry |
aty_housing:robberyStarted |
(propertyId, robberCharId) |
A robber got inside |
aty_housing:robberyEnded |
(propertyId, robberCharId, outcome, loot) |
A robbery session ended. outcome: escaped, timeout, died, abandoned, fled or interrupted |
aty_housing:notification |
(charId, category, key, priority) |
A notification was pushed to a character (the variables are not included) |
aty_housing:unitChanged |
(unitKey, reason) |
A storage unit changed hands or state |
aty_housing:unitRaided |
(unitKey, facility, officerCharId, caseNo) |
Police opened a storage unit |
aty_housing:alarmTriggered |
(propertyId, reason, charId) |
A home alarm started to sound. reason: forced, police, entry, door, motion, tamper or the word given to TriggerAlarm; charId is the intruder when known, else nil |
aty_housing:alarmChanged |
(propertyId, state, charId) |
A home alarm changed state: off, arming, armed or sounding |
aty_housing:upgradeChanged |
(propertyId, upgrade, level, oldLevel, source) |
A property upgrade level changed |
aty_housing:coloursChanged |
(propertyId, data, source) |
Light scenes or interior details of a property changed (data as GetLightScene; source is the player, nil for a script) |
aty_housing:buildingChanged |
(buildingId, reason) |
A building or one of its units changed. reason: checkin, extend, checkout, starter, updated, lobby, landing, generating, generated, bulk, attach, detach, unit_removed or deleted |
aty_housing:insuranceChanged |
(propertyId, status, tier, holderCharId, why) |
A policy changed: status active, lapsed, cancelled or ended |
aty_housing:insuranceClaim |
(propertyId, claimId, status, payout, reason, loss) |
A claim was filed or decided: pending, paid, denied or expired |
aty_housing:furnitureDeliveryCreated |
(order) |
A scheduled or pick-up furniture order was placed |
aty_housing:furnitureDeliveryCompleted |
(order, courierCharId) |
A scheduled order was delivered (courierCharId is nil without a courier) |
aty_housing:marketListed |
(listingId, propertyId, mode, price, ownerCharId) |
A property was listed on the player market |
aty_housing:marketUnlisted |
(listingId, propertyId, reason) |
A listing was withdrawn, expired or closed |
aty_housing:marketOffer |
(offerId, listingId, propertyId, byCharId, amount, kind) |
An offer or counter-offer was made (kind 'offer' or 'counter') |
aty_housing:contractCreated |
(id, propertyId, kind, sellerCharId, buyerCharId, price) |
A contract was drawn up (kind 'sale' or 'lease') |
aty_housing:contractSigned |
(id, propertyId, side) |
A party signed (side 'seller' or 'buyer') |
aty_housing:contractCompleted |
(id, propertyId, kind, price) |
A sale was completed or a lease was signed |
aty_housing:contractClosed |
(id, propertyId, status, reason) |
A contract was cancelled, expired or failed, or a lease ended or was terminated |
aty_housing:contractDisputed |
(id, propertyId, side) |
A party opened a dispute |
aty_housing:leaseRentPaid |
(id, propertyId, amount, paidCount) |
A lease rent was paid |
AddEventHandler('aty_housing:ownerChanged', function(propertyId, oldCharId, newCharId)
print(('Property %d: %s -> %s'):format(propertyId, tostring(oldCharId), tostring(newCharId)))
end)
Hooks
Register with exports.aty_housing:RegisterHook(name, fn). fn receives a data table.
| Hook | data |
Behaviour |
|---|---|---|
canEnter |
{ source, propertyId, charId, preview } |
Runs after all built-in checks, before a player enters. Return false, message to refuse |
canBuy |
{ source, propertyId, charId, tenure, price } |
Runs before money is taken for a purchase ('owned') or a rental ('rented'). Return false, message to refuse. Purchases through a loan, a transfer, an accepted offer or an auction carry extra fields (loan, transfer, via); a motel check-in has via = 'motel' and a starter apartment via = 'starter' (price 0) |
onPurchased |
same as canBuy |
After a purchase or rental is committed, on its own thread. Cannot veto |
onVacated |
{ propertyId, charId, reason } |
After the owner or tenant left, on its own thread. reason: sold, rent_ended, evicted, repossessed, lien, transferred or admin |
canRaid |
{ source, propertyId, charId, caseNo, warrant } |
Before a police raid; an MDT can check the case or warrant. A storage unit raid asks it too with { source, unitKey, charId, caseNo, warrant = false } (no propertyId). Return false, message to refuse |
canArm |
{ source, propertyId, charId, armed } |
Before a player arms (armed = true) or disarms (false) a home alarm from the tablet or the keypad. Return false, message to refuse. Not asked for the SetAlarmArmed export |
onAlarm |
{ propertyId, reason, charId, source } |
After a home alarm started to sound, on its own thread. Cannot veto |
canUpgrade |
{ propertyId, upgrade, level, oldLevel, price, charId, source } |
Before a property upgrade is bought. Return false, message to refuse |
onUpgrade |
same as canUpgrade |
After an upgrade level changed, on its own thread. Cannot veto |
canChangeColours |
{ src, charId, propertyId, scope, id, scene } (Style tab), { ..., details = { group, sets } } (interior details), { ..., scope = 'group', id, cycle = true } (switch key) |
Before light scenes or interior details change. Return false, message to refuse. Not asked for the SetLightScene and SetInteriorDetails exports |
canInsuranceClaim |
{ propertyId, claimId, charId, robber, loss, payout } |
Before an insurance claim is paid. Return false, message to deny it |
canBuyFurniture |
{ source, charId, store, mode, propertyId, items, total } |
Before a furniture store checkout. Return false, message to refuse |
canMarketList |
{ source, propertyId, charId, mode, price } |
Before a property is listed on the player market. Return false, message to refuse |
canMarketOffer |
{ source, listingId, propertyId, charId, amount, instant? } |
Before an offer is made, or a contract is requested at the asking price (instant = true). Return false, message to refuse |
canSignContract |
{ source, contractId, propertyId, charId, side, kind } |
Before a party signs a market contract. Return false, message to refuse |
onContractCompleted |
{ contractId, propertyId, kind, seller, buyer, price } |
After a market sale or a lease signing is committed. Cannot veto |
Storage unit hooks (exports.aty_housing:RegisterUnitHook(name, fn)):
| Hook | data |
Behaviour |
|---|---|---|
canAcquireUnit |
{ source, unitKey, charId, tenure, price, via? } |
Before a unit is rented or bought, and when a transfer offer is accepted (tenure = 'owned', via = 'transfer'). Return false, message to refuse |
canRaidUnit |
{ source, unitKey, charId, caseNo } |
Before police open a unit. Return false, message to refuse |
onUnitChanged |
{ unitKey, facility, oldOwner, newOwner, reason } |
After a change. reason: rented, bought, rent_paid, reclaimed, resized, transferred, evicted, free, release, sell, admin_free, restored |
Rules:
- Hooks run in registration order until one refuses. The message (1 to 128 characters) is shown to the player; it may be an
aty_housinglocale key or plain text. Without a message the player sees a generic "action blocked" text. - A hook of another resource that errors is logged and skipped (fail open), so a broken integration never locks players out. A hook may yield (for example a cross-resource call);
aty_housingre-checks its state afterwards. - Hooks are removed when the registering resource stops. When
aty_housingrestarts they are all gone: register again when it starts.
local function register()
exports.aty_housing:RegisterHook('canBuy', function(data)
if data.price > 500000 and not exports['my_bank']:HasCreditScore(data.source) then
return false, 'You need a credit score to buy this property.'
end
end)
exports.aty_housing:RegisterHook('onPurchased', function(data)
print(('%s bought property %d for %d'):format(data.charId, data.propertyId, data.price))
end)
end
AddEventHandler('onResourceStart', function(resource)
if resource == 'aty_housing' then register() end
end)
if GetResourceState('aty_housing') == 'started' then register() end
Client event
| Event | Description |
|---|---|
aty_housing:client:useTablet |
Opens the housing tablet for the local player. For inventories that run a client event when an item is used. The other aty_housing:client:* events are internal and not part of the public API |