İçeriğe geç
ATY ScriptsDokümanlarHousingExports and events

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_housing is 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 with SetEntityCoords(ped, x, y, z - 1.0).
  • A character id is the framework character id as a string (QBCore citizenid, ESX identifier). Functions that take srcOrCharId accept a server id (number) or a character id (string).
  • The permission names are enter, lock, stash, decor, manageKeys, garage, payBills, security, upgrades and exterior (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_housing locale 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_housing re-checks its state afterwards.
  • Hooks are removed when the registering resource stops. When aty_housing restarts 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