Zum Inhalt springen
ATY ScriptsDokuHousingInstallation

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

  1. Copy the aty_housing folder into your resources (for example [aty]/aty_housing).
  2. 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.
  3. Add it to server.cfg after aty_lib and your inventory (see below).
  4. Check who counts as a housing admin: framework admins work out of the box, the ACE permission is the fallback (see below).
  5. Check the job names and grades for realtors and police (see below).
  6. Add the items you want to use (see below).
  7. Edit shared/config.lua, and if you want to change light colours or yards also shared/config_colours.lua and shared/config_exterior.lua (see Configuration), and restart the resource.
  8. 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_ipl before aty_housing). The console prints one summary line, for example seed: 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; set Config.SeedProperties.enabled = false before the first start if you do not want them. See Ready-made properties.
  9. In game, type /housingadmin and create your own properties.
  10. With aty_shellcreator, seven sample interiors are published on its first start (two furnished houses, five empty homes; see Config.SampleShells in aty_shellcreator). They appear in the creator's Built shells tab, and the two furnished houses come with the furniture sets of Furniture sets.
  11. Optional: add apartment buildings or motels with /housingbuilding (Apartments, buildings and motels), and draw a yard with /housingyard where 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.

  1. 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 with QBCore.Functions.HasPermission. A player gets a level from add_principal identifier.<id> qbcore.<level> in server.cfg or from QBCore's AddPermission.
    • ESX: the player's group (xPlayer.getGroup()) is compared with Config.AdminPermission.esx (default { 'admin', 'superadmin' }). This has not been tested yet.
  2. The ACE permission Config.AdminAce (default aty_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 use reload, list and free as well).
  • The yard editor /housingyard and the building manager /housingbuilding (see Garden and exterior decor, Apartments, buildings and motels).
  • The admin tools in Commands: /housingutil, housingbulkcreate, /housinghygiene, /housingcookxp, /housingnotifytest and /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 after Config.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):

  1. When the garage script starts, and every time the server event aty_housing:garageChanged fires, call exports.aty_housing:GetGarages(). nil means aty_housing is not ready yet (try again on the next garageChanged, which also fires once when it becomes ready).
  2. For every entry, create or update a private garage in your garage script: position coords (x, y, z, heading w), size capacity, owner ownerCharId (the framework character id: QBCore citizenid, ESX identifier), extra users members (character ids with the garage permission). Remove the garages whose propertyId is no longer in the list.
  3. Optional: drop a member at memberExpiry[charId] (unix time) if you cache the list; garageChanged also 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/.