Zum Inhalt springen
ATY ScriptsDokuHousingWebhooks and migration

Webhooks and migration

aty_housing: Webhooks and migration

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

Discord webhooks

Housing events can be posted to Discord in ten categories (purchases, rentals, auctions, police, robberies, admin audit, finance, security, insurance and the player market). It is off by default. The settings live in the server-only file server/config_webhooks.lua, which is never sent to players. Never put a webhook URL in shared/config.lua: every client downloads that file.

A URL can also come from a convar in server.cfg, which wins over the file:

set aty_housing_webhook_default   "https://discord.com/api/webhooks/..."
set aty_housing_webhook_purchases "https://discord.com/api/webhooks/..."

default is used by every category without its own URL; the other names are the categories below. Then set Config.Webhooks.enabled = true in server/config_webhooks.lua and restart the resource.

Option Default Description
enabled false Master switch
username / avatar / footer 'Housing' / '' / 'aty_housing' Sender name, sender image URL ('' = the webhook's own), small text under every message
url '' Default URL for categories without their own
perMinute 25 Messages per minute per URL (Discord allows about 30)
batch 10 Embeds per message (1 to 10; events are grouped while waiting)
queueMax 500 Waiting embeds per URL; the oldest are dropped beyond it
retries / backoffSeconds 4 / { 5, 15, 45, 120 } New tries after a network or Discord error, and the wait before each
categories all on Per category: enabled, url ('' = default), colour (a number such as 0x2ECC71) and events (event = false mutes one)

Categories and events: purchases (bought, transferred, sold), rentals (rented, rent_ended, evicted), auctions (start, sold, ended, failed, cancel), police (raid, sealed, unsealed), robberies (started, ended), admin (create, delete, transfer, evict, reset, publish, hide, bulk, diagnostics; diagnostics is muted by default), finance (repossessed, lien), security (alarm), insurance (started, tier, cancelled, lapsed, ended, claim_paid, claim_denied, claim_pending) and market (created, completed, lease_started, lease_ended, lease_terminated, cancelled, expired, failed, dispute, resolved, flagged; see Player marketplace and contracts). Message texts come from locales/insurance/<lang>.lua (the wh_* keys; the market ones come from locales/marketplace/<lang>.lua), so they follow Config.Language.

Privacy. Only what the privacy table allows is sent; nothing else personal is ever included:

privacy option Default What it allows
characterNames false Character names (owner, buyer, robber, officer, admin)
characterIds false Character ids (citizenid or identifier)
propertyLabels true Property names
propertyIds true Property ids
amounts true Prices, premiums, payouts and cash
caseNumbers true Police case numbers
adminDetails false The detail text of admin audit rows (can contain character ids)

Migrating from qb-houses / ps-housing

/housingimport (Config.Importers.command) moves houses, owners, keys, furniture and stash items from another housing script into aty_housing. Supported sources: qb-houses (tables houselocations, player_houses) and ps-housing (table properties). NoLag Properties and BCS Housing publish no database layout and are not supported. The source tables are only read, never changed. Run it from the server console or in game as a housing admin.

  1. Map the interiors in Config.Importers.sources[<source>].shells: the key is the qb-houses tier number (as text) or the ps-housing shell name, the value is one of our interior ids (from data/interiors.json, or a built shell sc_<id>). The defaults map the common low and mid shells to gtao_house_low_1 and gtao_house_mid_1. An unmapped shell stops the import (or set fallbackInterior to an interior id to use for every unknown shell, with a warning per house).
  2. Run housingimport <source> dry first. It checks everything and writes nothing; read the report and fix what it names.
  3. Run housingimport <source> to import. housingimport without arguments lists the sources, whether their tables exist and how many records were imported earlier.

Rules: all or nothing per source; one record with an error and nothing is written, and the report says why. A record that was imported before is skipped, so the command can run again; a property is never created twice, and one you deleted after importing is not re-created. If a write fails half way the run stops, earlier records stay done and the next run continues. Only one batch (import, housingbulkcreate or seeding) can run at a time. Players keep their houses, keys (as role keyRole, default tenant) and, when keepPurchasePrice is on, their sell-back value (the source price; off = 0). Owner names appear when the owner is next seen.

Furniture. Furniture is imported only for shells that have an origin in the map, { interior = 'id', origin = { x, y, z } }: the point of our interior's stored frame (IPL = world, shell = offset from the shell origin) that matches the source shell's origin, which works when the room layout is the same (for example a shell you rebuilt in aty_shellcreator). Furniture models come from the models map (source model to catalog model); a model that already is in our catalog maps to itself. Pieces with an unknown model, outside the interior or without a frame are skipped and counted.

Stash items are moved with aty_inventory only (run its own import of the old inventory first); stashes = false turns it off. With another inventory the report lists the stash ids under stash.manual and nothing is moved. A stash that does not fit stays partly in the source and the next run moves the rest. The stash of an unowned property is not moved either.

Ownership limits. An owner who is already at their limit (Ownership limits) is not set: the property is imported unowned with a warning (owner_over_limit), the report lists it under ownerHeld, and the next run sets the owner once the limit allows it. Set Config.Importers.ignoreLimits = true (or Config.Limits.importMode = 'bypass') to import every owner regardless.

What is skipped. ps-housing apartments and MLO or zone rows (rows without door coordinates) are skipped with a reason, not an error; two new entrances closer than spacing are errors; keys of the owner, duplicates, invalid ids and keys over Config.MaxKeys are dropped with a reason in the report; keys on an unowned house are dropped. skip lists source ids to leave out (qb-houses name, ps-housing property_id as text).

Reports. Every run writes a JSON report to Config.Importers.reportDir (default data/import-reports, inside the resource) named <source>-<date>-<time>[-dry].json, with the summary, unmappedShells, unknownModels and per record the status, errors, warnings, keys, dropped keys, furniture and stash. The report holds character ids, so keep it on the server. The in-game admin gets a short result notification; the console has the details.

Option Default Description
enabled true false turns the command off
command 'housingimport' false = no command
reportDir 'data/import-reports' Report folder (relative, inside the resource)
keyRole 'tenant' Role of imported key holders: coowner, tenant or guest
keepPurchasePrice true The owner's purchase price is the source price
ignoreLimits false Import every owner even over the ownership limit
stashes / furniture true Steps you can switch off
fallbackInterior false Interior id for shells that are not mapped
spacing { entrance = 2.0, garage = 2.0 } Minimum metres between new entrances / garages in one batch
models {} Source furniture model to catalog model
sources qb-houses, ps-housing Table names, shells, skip and (qb-houses) shellZOffset = 30.0 per source

The import ledger is the table aty_housing_imports, created on the first housingimport call.