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.
- 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 (fromdata/interiors.json, or a built shellsc_<id>). The defaults map the common low and mid shells togtao_house_low_1andgtao_house_mid_1. An unmapped shell stops the import (or setfallbackInteriorto an interior id to use for every unknown shell, with a warning per house). - Run
housingimport <source> dryfirst. It checks everything and writes nothing; read the report and fix what it names. - Run
housingimport <source>to import.housingimportwithout 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.