Installation
aty_housing: Installation
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
Dependencies
| Dependency | Required | Notes |
|---|---|---|
aty_lib |
Yes (declared in fxmanifest.lua) |
Framework, money, inventory, database, notification, item and target bridge. Must start first. Restarting aty_lib restarts every dependent resource, aty_housing included |
es_extended or qb-core |
One of them | Detected by aty_lib. Qbox works through the qb-core compatibility of qbx_core |
oxmysql (or mysql-async / ghmattimysql) |
One of them | Whatever aty_lib detects. Live-tested with oxmysql only |
| Inventory | Yes | Supported: every inventory the aty_lib bridge supports: aty_inventory, ox_inventory, qb-inventory, qs-inventory, ps-inventory, codem-inventory, tgiann-inventory, origen_inventory, gfx-inventory, esx_inventoryhud, ak47_inventory and ak47_qb_inventory. Live testing was done on aty_inventory. Items (tablet item, cooking, robbery loot) go through aty_lib's item functions. Property stashes, storage furniture and storage units open through aty_inventory, qb-inventory, ox_inventory or qs-inventory; with the other inventories they answer stash_unavailable. Clearing stashes and reading how full a stash is work with aty_inventory (and ox_inventory for fill level) only |
ox_target, qb-target or aty_interactions |
Optional | Used through aty_lib for target-eye interaction. Not needed when Config.InteractMode = 'marker' |
bob74_ipl |
Only for IPL properties | Loads the GTA Online apartment and house interiors, and its entity sets are what the Style tab's interior details switch (see Lighting and colours). Not shipped with aty_housing |
aty_garage_v2 |
Optional | House garages are picked up automatically (Config.Housing.script = 'auto' on the garage side). Needs an aty_garage_v2 build with aty_housing support (see that resource's release notes) |
aty_shellcreator (+ aty_shellcreator_kit) |
Optional | Interiors built in the in-game Shell Creator become shell interiors for properties (see Built shells) |
aty_multicharv2 |
Optional | "Wake up at home" cards in the spawn selector (Config.HousingSpawn on the multichar side, default on) |
ps-dispatch, cd_dispatch, qs-dispatch, core_dispatch, aty_dispatchv2, qb-policejob |
Optional | Police alert adapters for house robbery (Config.Robbery.dispatch). The built-in alert needs nothing |
| Shell pack or MLO resource | Optional | Your own licensed interiors, installed as separate resources. aty_housing never ships interior assets |
Required versions of other ATY resources
aty_housing 1.0.0 needs the builds of these ATY resources that were released together with it. Older builds still start, but the features in the last column are missing (the console says which one to update).
| Resource | Minimum | What aty_housing uses | With an older build |
|---|---|---|---|
aty_lib |
1.3.9 or newer (the release that adds GetPlayerJob, HasPermission, GetPlayerNeeds / AddPlayerNeeds and RegisterStashAccess) |
Server GetPlayerJob (realtor and police roles), HasPermission (framework admins), AddPlayerNeeds (hunger, thirst and stress from living actions), RegisterStashAccess (property stashes cannot be opened by name from a client), ExecuteSqlBatch (Decor Studio saves) |
No realtor or police roles (the Admin tab diagnostics warns), admins only through the ACE, living actions do not change needs, property stashes are not protected against opening by name. A very old aty_lib without ExecuteSqlBatch cannot save Decor Studio changes |
aty_inventory |
1.11.0 or newer (the release that adds RegisterStashAccess) |
RegisterStashAccess (stash guard), GetSlotUsage (stash fill level in the tablet), RegisterStash, OpenInventory, ClearInventory |
Property stashes are not protected against opening by name. The console command invstashaccess (aty_inventory) runs a self test of the guard, including the aty_housing check |
aty_garage_v2 |
1.8.0 or newer (the release with Config.Housing.script = 'auto' and GetHouseGarageVehicles) |
Reads exports.aty_housing:GetGarages(), listens to aty_housing:garageChanged; housing reads GetHouseGarageVehicles |
No house garages; the tablet's garage list stays empty |
aty_multicharv2 |
The build with Config.HousingSpawn and RegisterSpawnProvider |
Reads exports.aty_housing:GetSpawnPoints() |
No "wake up at home" cards |
aty_shellcreator and aty_shellcreator_kit 1.0.0 are released together with aty_housing 1.0.0.
Installation
- Copy the
aty_housingfolder into your resources (for example[aty]/aty_housing). - No SQL import. On start the resource creates every table it needs (
CREATE TABLE IF NOT EXISTS) and adds missing columns itself. It never touches your framework's tables. If the database is unreachable the migration is retried three times, then the console prints an error and the resource stays idle until you restart it. See Database for the table list. - Add it to
server.cfgafteraty_liband your inventory (see below). - Check who counts as a housing admin: framework admins work out of the box, the ACE permission is the fallback (see below).
- Check the job names and grades for realtors and police (see below).
- Add the items you want to use (see below).
- Edit
shared/config.lua, and if you want to change light colours or yards alsoshared/config_colours.luaandshared/config_exterior.lua(see Configuration), and restart the resource. - Start the server once. On the first start the resource creates 24 ready-made luxury houses in Vinewood Hills (no owner, for sale and rent; they use IPL interiors, so start
bob74_iplbeforeaty_housing). The console prints one summary line, for exampleseed: data/seed/vinewood_hills_lux.json: created 24, adopted 0, skipped 0, plus one line for every house it skipped because something of yours already stands at that spot. This happens once; setConfig.SeedProperties.enabled = falsebefore the first start if you do not want them. See Ready-made properties. - In game, type
/housingadminand create your own properties. - With
aty_shellcreator, seven sample interiors are published on its first start (two furnished houses, five empty homes; seeConfig.SampleShellsinaty_shellcreator). They appear in the creator's Built shells tab, and the two furnished houses come with the furniture sets of Furniture sets. - Optional: add apartment buildings or motels with
/housingbuilding(Apartments, buildings and motels), and draw a yard with/housingyardwhere the automatic yard does not fit (Garden and exterior decor).
server.cfg
ensure oxmysql
ensure qb-core # or es_extended
ensure aty_lib # always before any aty_* resource
ensure aty_inventory # or another inventory aty_lib supports (see Dependencies)
ensure bob74_ipl # only when you use IPL properties
ensure aty_garage_v2 # optional
ensure aty_multicharv2 # optional
ensure aty_shellcreator_kit # optional, with aty_shellcreator
ensure aty_shellcreator # optional: built shells
ensure aty_housing
aty_garage_v2 and aty_multicharv2 notice aty_housing starting or stopping at any time, so their position relative to aty_housing is not critical. aty_lib and your inventory must be running first.
Admin permission
The server checks two things, in this order, on every admin action. A player is a housing admin when either one says yes.
- The framework's own admin permission (
Config.AdminPermission). This is the same permission the framework's own commands use.- qb-core: the permission levels in
Config.AdminPermission.qb(default{ 'admin', 'god' }), checked withQBCore.Functions.HasPermission. A player gets a level fromadd_principal identifier.<id> qbcore.<level>inserver.cfgor from QBCore'sAddPermission. - ESX: the player's group (
xPlayer.getGroup()) is compared withConfig.AdminPermission.esx(default{ 'admin', 'superadmin' }). This has not been tested yet.
- qb-core: the permission levels in
- The ACE permission
Config.AdminAce(defaultaty_housing.admin). This is the last resort. It is also checked when the framework says the player is not an admin, so staff you manage through ACE keep their access:
add_ace group.admin aty_housing.admin allow
add_principal identifier.license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx group.admin
On qb-core, group.admin is not a permission level. If a player is in group.admin but not in qbcore.admin or qbcore.god, they need the ACE line above.
aty_housing reads the framework permission through aty_lib (HasPermission). With an older aty_lib that does not have it, only the ACE is checked. To use only ACE, set both lists in Config.AdminPermission to {}.
It gates:
/housingadmin(the property creator) and everything an admin may do in it: delete, duplicate, teleport to captured points.- The Admin tab of the tablet: property table, transfer, evict, reset, delete, bulk actions, diagnostics, audit log.
- Lifting a police seal without a case number, and the storage-unit command
/housingunits(the server console may usereload,listandfreeas well). - The yard editor
/housingyardand the building manager/housingbuilding(see Garden and exterior decor, Apartments, buildings and motels). - The admin tools in Commands:
/housingutil,housingbulkcreate,/housinghygiene,/housingcookxp,/housingnotifytestand/housingseatdebug.
Admins are never limited by realtor grade limits. The commands are registered for everyone; the permission is checked on the server before anything happens.
Jobs
Realtors (Config.RealtorJobs). The default entry is the job realestate with grades 0 to 3. Create that job (or rename the key to your own job) in your framework with matching grade numbers. Each grade lists what it may do (create listings, change prices, run auctions, commission, price bounds, stash limits ...); the full field list is in Realtors and auctions. A grade that is not listed uses the highest listed grade below it; a grade below the lowest listed one is not a realtor at all. Changes to Config.RealtorJobs need a resource restart. With Config.Realtor.requireDuty = true realtors must be on duty.
Police (Config.PoliceJobs, default { 'police' }). Police on duty see the Police tab and may seal, raid and search properties. The minimum job grade for each action is set in Config.Police.grades (QBCore compares against grade.level).
Items
| Item | Used for | Notes |
|---|---|---|
housing_tablet (Config.Tablet.item) |
Opens the tablet. /housing always works too |
Set Config.Tablet.item = false for command only. The item is registered as usable through aty_lib on qb-core and ESX; ox_inventory needs a small item entry. Item definitions for each inventory are in docs/INSTALL-tablet-item.md |
lockpick (Config.Robbery.item) |
Starts the lock game on a robbery | Must exist in your item list. Rename the option if your item has another name, or set Config.Robbery.enabled = false |
advancedlockpick (Config.Robbery.advancedItem) |
Gives extra allowed misses in the lock game | Same as above |
Loot items (Config.Robbery.loot) |
Given to a robber who searches a point | The default tables use qb-core item names (sandwich, water_bottle, bandage, painkillers, screwdriverset, samsungphone, iphone, tablet, laptop, whiskey, wine, vodka, goldchain, tenkgoldchain, rolex, diamond_ring, diamond, goldbar, cryptostick). Replace every entry that does not exist on your server |
furniture_box (Config.FurnitureStore.item.name) |
Only with Config.FurnitureStore.item.enabled = true: one item per piece of a collected pick-up order; using it unpacks the piece into My furniture |
Add the item to your item list first. The piece and a token are stored in the item metadata |
Motel room key (Config.Buildings.motel.keyItem) |
Optional: given at motel check-in, one item removed when the stay ends; with requireKeyItem = true the tenant needs it to go in |
Off by default (false). Add the item to your item list first, then set its name |
Config.Police.raid.item |
Optional tool an officer must carry to force a door (not used up) | false = none |
The tablet item on qb-core, for reference:
housing_tablet = {
name = 'housing_tablet',
label = 'Housing tablet',
weight = 500,
type = 'item',
image = 'housing_tablet.png',
unique = true,
useable = true,
shouldClose = true,
description = 'Browse listings and manage your properties',
},
Put an image named housing_tablet.png in your inventory's image folder (aty_inventory: ui/images/, and web/public/images/ too if you rebuild its UI; qb-inventory: html/images/).
Database
All 63 tables are created on start (aty_housing_imports on the first housingimport run). Nothing in the list below needs manual work; it is here so you know what is stored and what to include in backups.
| Area | Tables |
|---|---|
| Properties and keys | aty_housing_properties, aty_housing_keys, aty_housing_key_log, aty_housing_inside, aty_housing_meta, aty_housing_favourites, aty_housing_listing_stats, aty_housing_price_history, aty_housing_drafts |
| Decor Studio | aty_housing_furniture (also the yard pieces, zone = 1), aty_housing_decor_prefs, aty_housing_furnish_presets (furniture sets saved in game), aty_housing_furnish_applied (last set placed per property) |
| Finance | aty_housing_finance, aty_housing_loans, aty_housing_bills, aty_housing_payments, aty_housing_transfers |
| Storage units | aty_housing_units, aty_housing_unit_keys, aty_housing_unit_log, aty_housing_unit_payouts |
| Doorbell, police, robbery | aty_housing_doorbell_log, aty_housing_seals, aty_housing_police_log, aty_housing_robberies |
| Realtors, auctions, admin | aty_housing_leads, aty_housing_viewings, aty_housing_auctions, aty_housing_bids, aty_housing_payouts, aty_housing_admin_log |
| Notifications | aty_housing_notifications, aty_housing_notification_prefs, aty_housing_notification_once |
| Built shells and stashes | aty_housing_built_shells, aty_housing_stashes |
| Living and utilities | aty_housing_utility_meters, aty_housing_utility_readings, aty_housing_living_stats, aty_housing_cooking_skill |
| Player marketplace | aty_housing_market_listings, aty_housing_market_offers, aty_housing_contracts, aty_housing_contract_log |
| Light colours, yards, apartment buildings | aty_housing_colours, aty_housing_yards, aty_housing_buildings, aty_housing_building_units, aty_housing_building_starters |
| Security, upgrades, insurance, furniture store, MLO doors, imports | aty_housing_security, aty_housing_security_cams, aty_housing_security_camset, aty_housing_security_log, aty_housing_security_snaps, aty_housing_upgrades, aty_housing_upgrade_log, aty_housing_insurance, aty_housing_insurance_claims, aty_housing_insurance_ledger, aty_housing_furniture_stock, aty_housing_furniture_orders, aty_housing_door_states, aty_housing_door_log, aty_housing_imports |
Notes:
- The owner of a property is the framework character id (QBCore citizenid, ESX identifier).
- While the server or the resource is down, rent due dates, loan installments, bills, storage-unit rent and auction timers are moved forward by the downtime, so nobody is charged for time the service was offline.
- Retention is configurable: police log, robbery rows and the admin audit log are pruned after
logRetentionDays(90 by default), notifications afterConfig.Notifications.retentionDays(14).
Optional integrations
Inventories. The inventory is detected through aty_lib; aty_inventory wins when it runs, otherwise the most recently started name in aty_lib's list. A property stash gets a hidden key in its id (aty_housing_<property id>_<key>) that is renewed on every ownership change, so a new owner always starts with an empty stash. The old id is printed to the server console together with the message that its items stay behind, and an admin can recover them from there. Only aty_inventory can be told to clear old stashes (Config.EvictionClearStash, Config.Lifecycle.clearStashesOnDelete, Config.Finance.repossession.clearStash, Config.StorageUnits.evictionStash). qs-inventory opens stashes from the client, so server-side enforcement is weaker there.
Target scripts. Entrance, exit and stash points use target zones and/or the E-key marker according to Config.InteractMode. Zones go through aty_lib, which supports ox_target, qb-target and aty_interactions.
bob74_ipl. IPL properties need bob74_ipl running. The catalog in data/interiors.json points to its exports; aty_housing only refreshes the interior's entity sets on entry.
aty_garage_v2. exports.aty_housing:GetGarages() lists every owned or rented property with a garage point (Config.Garage). aty_garage_v2 reads it automatically and refreshes on aty_housing:garageChanged. The garage id of a property is 1000000 + property id. The tablet's My properties > Garage view lists the vehicles stored there.
Other garage scripts. aty_housing does not store vehicles; it tells garage scripts which properties have a garage and who may use it. Any garage script can be connected later, without editing aty_housing, by adding a small loader to the garage script (server side):
- When the garage script starts, and every time the server event
aty_housing:garageChangedfires, callexports.aty_housing:GetGarages().nilmeansaty_housingis not ready yet (try again on the nextgarageChanged, which also fires once when it becomes ready). - For every entry, create or update a private garage in your garage script: position
coords(x, y, z, headingw), sizecapacity, ownerownerCharId(the framework character id: QBCorecitizenid, ESXidentifier), extra usersmembers(character ids with thegaragepermission). Remove the garages whosepropertyIdis no longer in the list. - Optional: drop a member at
memberExpiry[charId](unix time) if you cache the list;garageChangedalso fires when such a key expires.
-- server side of YOUR garage script
local function syncHousingGarages()
if GetResourceState('aty_housing') ~= 'started' then return end
local list = exports.aty_housing:GetGarages()
if not list then return end -- aty_housing not ready yet
local seen = {}
for _, g in ipairs(list) do
seen[g.propertyId] = true
-- create or update the garage with your garage script's own API:
-- id: 'house_' .. g.propertyId, coords: g.coords, capacity: g.capacity,
-- owner: g.ownerCharId, extra users: g.members
end
-- remove the house garages whose propertyId is not in `seen`
end
AddEventHandler('aty_housing:garageChanged', syncHousingGarages)
AddEventHandler('onResourceStart', function(res)
if res == GetCurrentResourceName() or res == 'aty_housing' then syncHousingGarages() end
end)
aty_garage_v2 is the reference implementation of this (its server/main.lua, functions loadHouseGarages and applyHouseGarages). The tablet's My properties > Garage vehicle list reads aty_garage_v2 only; with another garage script that list stays empty, the garage itself works.
Clothing scripts (wardrobe and mirror). The wardrobe and mirror living points open the clothing script named in Config.Living.clothing.resource (default 'aty_clothing'): the wardrobe calls exports[resource]:OpenWardrobeMenu(title), the mirror exports[resource]:OpenCustomMenu(mirrorMenu, mirrorCategories, title, 'housing_mirror'). A clothing script with the same two exports only needs its name there.
For any other clothing script, set Config.Living.clothing.resource = '' and open its menus from your own client file (no aty_housing file changes). aty_housing triggers two client events with (propertyId, done); call done() after opening your menu so the "no clothing script" message is not shown:
-- client side of YOUR clothing script (or a small separate resource)
AddEventHandler('aty_housing:client:openWardrobe', function(propertyId, done)
-- open your clothing script's outfit / wardrobe menu here
done()
end)
AddEventHandler('aty_housing:client:openMirror', function(propertyId, done)
-- open your clothing script's hair / make-up menu here
done()
end)
aty_multicharv2. While aty_housing runs, every property a character may enter appears as a "wake up at home" card in the default spawn selector. The owner or tenant picks their home in the tablet (My properties > Settings). The choice is checked on the server again at spawn time. With Config.Buildings.starter.enabled, a new character gets its starter apartment at its first login, before the spawn selector lists its homes (see Starter apartments); asking for spawn points never changes anything. Turn it off with Config.HousingSpawn = false in aty_multicharv2.
Dispatch. Config.Robbery.dispatch picks the police alert target: 'builtin' (default: alert blip and notification for on-duty police plus the Police tab), 'none', 'ps-dispatch', 'cd_dispatch', 'qs-dispatch', 'core_dispatch', 'aty_dispatchv2', 'qb-policejob' or 'custom' (your function in Config.Robbery.customDispatch). A named resource that is not started falls back to 'builtin'.
Files that stay open for editing
When aty_housing is distributed as an escrowed asset, these stay readable and editable (upload-config.json):
| Path | Why |
|---|---|
fxmanifest.lua, shared/config.lua, shared/config_colours.lua, shared/config_exterior.lua |
Configuration (shared/config.lua also holds Config.Buildings; the other two hold Config.Colours and Config.Exterior) |
server/api.lua |
The open integration API (exports, events, hooks) |
locales/*.lua and locales/<feature>/*.lua (tablet, world, decor, finance, storage_units, realtor, world_access, creator, zones, notifications, living, built, hygiene, mlo_doors, security, importers, insurance, upgrades, furniture_store, marketplace, creator_home, colours, exterior, buildings) |
Translate or reword any text |
server/config_webhooks.lua |
Discord webhook settings (server only, see Discord webhooks) |
docs/*.md |
Documentation |
data/*.json |
Interior catalog, furniture catalog (with colour variants and the yard flag), storage facilities and the IPL interior details (data/ipl_styles.json) are plain data files that you edit directly (see Data files) |
All other Lua files are protected. The UI source code and the development tools are not part of the package; the pre-built panel is in ui/.