Zum Inhalt springen
ATY ScriptsDokuHousingEconomy

Economy

aty_housing: Economy, upgrades and the player market

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

Ownership limits

Server owners can cap how many properties one character may own and rent (Config.Limits). The limit is checked on the server on every way to get a property: buying, renting, loans, realtor sales, auction wins, transfers and gifts, rent-to-own buyouts, the admin Transfer tool and importers. Nothing is taken away from a player when you lower a limit; they simply cannot get another one. The tablet shows chips such as Owned 2 / 3 at the top of My properties, and a full chip says so.

Option Type Default Description
enabled boolean true Limits on or off
owned / rented number or false 3 / 2 Most owned and most rented properties per character. 0 = not allowed at all, false = no limit
total number or false false Owned and rented together
kinds table {} Limits per interior kind (ipl, shell, mlo), for example { mlo = { owned = 1, rented = 1 } }
jobs table {} Per job: { realestate = { minGrade = 2, owned = 6 } }
groups table {} Per group, matched by ACE (ace) or framework permission (framework, a level or a list): { vip = { ace = 'aty_housing.limits.vip', owned = 5, rented = 3 } }. Give the ACE with add_ace group.vip aty_housing.limits.vip allow
adminBypass boolean true Admins (Admin permission) are never limited
adminTools string 'enforce' 'enforce' = the admin Transfer tool refuses a target who is at the limit, 'bypass' = it ignores limits
importMode string 'enforce' 'enforce' or 'bypass' for importers and for CanAcquireProperty(..., { import = true })
reserveSeconds number 30 A property being bought counts for the buyer for this long, so two purchases at once cannot both pass the limit

A value set by a matching job or group replaces the base value; when several match, the most generous wins. jobs and groups entries may hold their own kinds.

Exports (server): GetOwnershipLimits(charId) returns { enabled, bypass, owned = { count, max }, rented, total?, kinds } (max = nil means no limit, { enabled = false } when limits are off). CanAcquireProperty(charId, propertyId, tenure?, opts?) returns true, or false, message; tenure is 'owned' (default) or 'rented'; pass opts.import = true or opts.admin = true to apply importMode or adminTools. Limits also run as an internal canBuy check, so every purchase path is covered.

Home insurance

Owners can insure a property against robberies (Config.Insurance). It needs Config.Finance.enabled. The owner buys a policy in My properties > Finance; the first premium is paid at once and then a premium bill (Home insurance) arrives every periodDays together with the other bills, so autopay pays it. A premium bill is due dueDays after it is issued; if it is still unpaid lapseGraceHours after its due date, the policy lapses. Cover starts waitingHours after buying, so nobody can insure a house that is being robbed right now. Premiums are not refunded when a policy is cancelled, and a policy ends when the owner changes. Tenants can insure a rental only with allowTenants = true.

Option Type Default Description
enabled boolean true Insurance on or off
periodDays number 30 Premium period in days
dueDays number 3 A premium bill is due this many days after it is issued
lapseGraceHours number 72 An unpaid premium lapses the policy this long after its due date
waitingHours number 24 Cover starts this long after buying
allowTenants boolean false Tenants may insure their rental
tiers table basic, premium Plans, each { ratePct, minPremium, coveragePct, deductible, maxPayout, flatPayout, windowCap, label? }. windowCap = the most one policy pays out in any claims.capDays days (0 = no cap; defaults basic 20,000, premium 60,000). Premium = property value x ratePct % (the purchase price, else the sale price), at least minPremium; the payout is (loss - deductible) x coveragePct %, at most maxPayout (0 = no cap); in 'flat' and 'both' mode a robbery that took anything pays flatPayout minus deductible instead (no cover share). Defaults: basic 0.3 % / 60 % cover / 500 deductible / 15,000 cap, premium 0.6 % / 90 % / 200 / 50,000
payout.mode string 'items' 'items' = the value of what the robber took (itemValues, a value in Config.Robbery.loot, else defaultItemValue) plus cash when coverCash; 'flat' = the plan's flatPayout (less the deductible) for every robbery that took anything; 'both' = the larger of the two. Items taken from the stash cannot be priced, so only 'flat' and 'both' cover them
payout.coverCash / defaultItemValue / itemValues boolean / number / table true / 50 / item table Cash cover, fallback item value, and a value per item name
payout.account string 'bank' Where payouts go ('bank' or 'cash'); an offline holder is paid at login
claims.auto boolean true The claim is decided right after the robbery. false = the owner files it from the tablet within windowHours
claims.cooldownHours / windowHours number 72 / 72 One paid claim per property in this time / how long a manual claim can be filed
claims.excludeKeyHolders boolean true No payout when the robber holds a key to the property
claims.capDays number 30 Length of the rolling window of the plans' windowCap (1 to 90)
claims.premiumMultiple number 10 All payouts to one owner on one property together stay at or below the premiums that owner actually paid on it x this (0 = off). Stops "insure it, let a friend without a key rob it, cash in" from paying more than the premiums ever covered
historyShown number 10 Claims listed in the tablet

A claim is denied, with the reason shown in the tablet, when the property was not covered at the time, the robber had access, a claim was paid recently, the loss is below the deductible, an integration vetoed it, it was not filed in time, or no room is left under the payout caps.

Payout caps. Two limits protect against owners who let a friend rob their insured home. (1) A rolling window: one policy pays at most the plan's windowCap in any claims.capDays days. (2) Premium backing: everything paid to one owner on one property stays within the premiums that owner actually paid on it (the first premium plus premium bills that were paid; unpaid or written-off bills do not count) times claims.premiumMultiple. The sums are kept per property and owner in aty_housing_insurance_ledger and survive a cancelled and renewed policy. A claim above the room left is paid in part (the tablet shows Reduced from ... with the reason, the owner gets a notification with both amounts); with no room left it is denied with that reason. My properties > Finance > Home insurance shows the room left under both caps and when the window frees up; with manual claims a waiting claim shows what filing it now would pay. Policies bought before this version start with their current premium counted once.

Integration (server): exports GetInsurance(propertyId) ({ propertyId, holder, tier, nextTier, status, premium, startedAt, coveredFrom, nextBillAt, lastClaimAt, premiumsPaid, paidOut, windowLeft?, premiumLeft? } or nil; a missing windowLeft / premiumLeft means that cap is off) and GetInsuranceClaims(propertyId, limit?) (newest first, at most 50). Events: aty_housing:insuranceChanged (propertyId, status, tier, holderCharId, why) with status active, lapsed, cancelled or ended, and aty_housing:insuranceClaim (propertyId, claimId, status, payout, reason, loss) with status pending, paid, denied or expired. Hook canInsuranceClaim ({ propertyId, claimId, charId, robber, loss, payout }): return false, message to deny a claim as vetoed, for example when an MDT wants a police report first.

Property upgrades

Owners can buy permanent improvements for a property in My properties > Upgrades (Config.Upgrades). Upgrades stay with the property when it is sold or transferred (set resetOnOwnerChange = true to reset them to level 0 on every owner change) and are never refunded. A player needs the new key permission upgrades (the owner always has it; it is in no role preset, so tick it for a key holder in the access matrix). Tenants can buy upgrades only with allowRenters = true. A police seal locks upgrades.

Option Type Default Description
enabled boolean true false = no Upgrades tab and no bonuses (the alarm keeps working)
allowRenters boolean false A tenant may buy upgrades too
resetOnOwnerChange boolean false Every upgrade goes back to level 0 when the owner changes
priceMultiplier number 1.0 Every price is multiplied by this (0 to 100)
tierPriceMultiplier table { 1.0, 1.25, 1.5 } Extra multiplier for low, mid and high tier properties
notify boolean true The owner and members with upgrades get a notification of a purchase
historyKeep number 100 History rows kept per property
adminCommand string 'housingupgrade' Admin and console command ('' = none)
catalog table 8 upgrades The upgrades in tablet order, see below

Catalog. Each entry has an id (stash, stashExtra, garage, decor, yard, alarm, cameras or efficiency; each id has its effect in the code and other ids are skipped), an optional icon, enabled, kinds (property kinds it is offered for, default all), minTier / maxTier (1 to 3), requires ({ [upgrade id] = level } needed before level 1) and 1 to 10 levels. Each level has a price and the effect values as totals at that level (not added to the level before), and may have its own requires:

id Level values Effect
stash slots, weight (grams) Bigger main stash
stashExtra slots, weight Bigger extra stashes of the interior (default: needs stash level 1)
garage slots More vehicles in the property garage (aty_garage_v2 reads it through GetGarages)
decor objects Added to Config.Decor.maxObjects in the Decor Studio
yard objects Added to Config.Exterior.maxObjects in the yard Studio; offered only to a property that has a yard (default levels: +15, +30, +60 pieces for 6,000 / 12,000 / 24,000). See Garden and exterior decor
alarm one level, no price Unlocks the alarm; no price = Config.Security.alarm.price (never multiplied)
cameras studio, exterior Added to the camera limits of Config.Security.cameras
efficiency power, water (percent, 0 to 90) Less power and water use and lower bills

Admin command: /housingupgrade <property id> prints every upgrade level; /housingupgrade <property id> <upgrade> <level> sets one (level 0 removes it); /housingupgrade <property id> reset resets all of them. These need no money.

Integration (server): exports GetUpgrades(propertyId) ({ [upgrade] = { level, max, paid } }), GetUpgradeLevel(propertyId, upgrade), GetUpgradeBonus(propertyId, key) (keys stashSlots, stashWeight, extraSlots, extraWeight, garageSlots, decorObjects, exteriorObjects, studioCams, exteriorCams, powerPct, waterPct) and SetUpgradeLevel(propertyId, upgrade, level) (true, or false, reason; any level from 0 to the maximum, no money and no permission check, recorded with the source api). Event aty_housing:upgradeChanged (propertyId, upgrade, level, oldLevel, source). Hooks: canUpgrade and onUpgrade, both with { propertyId, upgrade, level, oldLevel, price, charId, source } (source is tablet, admin or api); canUpgrade returns false, message to refuse.

Player marketplace and contracts

Owners can sell or lease their own properties to other players without a realtor, in the tablet's Market tab (Config.Marketplace). Everything is decided on the server: the listing, the offers, the contract terms, the escrow, the two signatures and the change of owner. The sale uses the same transfer code as a face-to-face transfer, so loans, bills, keys, stash, furniture, upgrades, the resale lock and the ownership limits behave the same way. It needs Config.Finance.enabled (the escrow and the payment history live there). A new server needs nothing to be set: it is on by default, and four tables are created on start. Set enabled = false to hide the tab.

Listing. An owner opens Market > My listings > List a property, picks a property they own (a rental cannot be listed), chooses for sale or for lease, and sets the price or rent, a title, a description, up to photosMax of that property's catalog pictures, open-house times and the clauses. For a sale they also choose what is handed over (furniture stays or is removed, the stash stays or is emptied, existing keys stay or are removed). A listing is refused while the property is sealed by police, being robbed, at auction, has a pending transfer, is already listed, is leased out (for a sale) or is inside its resale lock (for a sale). It runs listing.days days, can be paused, edited, renewed or withdrawn, and costs listing.fee (0 by default).

Offers and counters. A buyer makes an offer (a price, or for a lease a rent plus the number of periods and a start date) with a short message, or asks for a contract at the asking price (contracts.instantAtAsking). The owner accepts, declines or counters; the buyer can counter or withdraw. Each side answers the newest row only, a negotiation is limited to offers.maxRounds rounds, every offer lapses after offers.hours hours, and with offers.requireFunds the buyer must have the money on the account. Accepting an offer draws up the contract and puts the listing under contract; the other negotiations of that listing are closed and their buyers are told.

Contract and signing. The contract is an unchangeable summary of the terms: both parties, the broker and commission, the property, the price or rent, the term, the deposit, the fees, the clauses and the loan or bills that come out of the price. Each party opens it in the tablet, types the character name exactly as it is (contracts.nameMatch), draws a signature (contracts.requireDrawing; optional otherwise) and confirms. Both sides have contracts.signHours hours to sign; otherwise the contract expires and the listing goes back on the market.

Escrow. When the buyer (or tenant) signs, the total is taken from their account and held in escrow: for a sale the price plus the buyer tax, for a lease the first rent plus the deposit. The money is released only when the second signature completes the deal. If the contract is cancelled, expires or fails, it is refunded in full (at the next login if the player is offline). If the price does not cover the loan payoff and the open bills, the seller must be online at the final signature to pay the difference.

Sales. The second signature moves the property to the buyer in one step. The seller receives the price minus the seller fee (fees.salePct; by default the face-to-face transfer fee Config.Finance.transfer.feePct), the loan payoff, the open bills and the broker commission. Upgrades stay with the property.

Leases. The owner keeps the property. The tenant gets a key with the role lease.role (tenant by default) when the lease starts, and the landlord receives the first rent minus the lease fee (fees.leasePct) and the commission; the deposit stays in escrow. Rent is due at the start of every period and is charged automatically from an online tenant (lease.autopay); the tenant can also pay ahead from the tablet. Rent that stays unpaid for lease.graceHours hours terminates the lease: the debt is taken from the deposit, the rest is refunded and the key is removed. At the end of the term the deposit is refunded and the key is removed. The clause auto renew extends the lease for the same term unless the tenant gives notice, and the clause early exit fee gives the deposit to the landlord when the tenant gives notice. A tenant can give notice (the lease ends with the paid period), or either side can ask for an early end that the other confirms. A leased property cannot be sold to anyone else while lease.blockSale is on, and a change of owner by any other route ends the lease.

Cancellation, expiry and disputes. Either party (or the broker) can cancel a contract before the second signature; the escrow is refunded. With contracts.cancelPenaltyPct above 0, cancelling after the other side has signed costs that share of the price, paid to the other side. A contract nobody signs within signHours expires. A party can open one dispute (with a written reason) within disputes.windowDays days of the last change. Staff see open disputes and flagged contracts in Market > Disputes (admin only) and resolve them: dismiss, cancel a pending contract (escrow refunded), or end a lease with the deposit going to the tenant or to the landlord. Both parties are notified and the decision is audited.

Realtor broker. An owner may invite a realtor (Config.RealtorJobs) who stands next to them to broker a listing (realtor.enabled). The broker can answer offers and draw up the contract for the owner, who still signs. The commission is the realtor grade's commission percent (see Realtors and auctions) of the sale price, or of one period's rent for a lease, and is paid out of the seller's or landlord's proceeds. A party of the deal cannot be its broker.

Anti-abuse. The account (license) of each party is stored only as a hash. With antiAbuse.sameLicense = 'block' (default) two characters of one account cannot deal with each other; 'log' lets the deal through but flags the contract for staff and the webhook; 'allow' ignores it. Two characters that just completed a contract cannot sign another within antiAbuse.pairCooldownHours (72). antiAbuse.minPriceRatio (0 = off) sets the lowest price as a share of the last paid price, and a sale below antiAbuse.flagBelowRatio (0.5) of it is flagged. Listing and contract creation have per-character waiting times, offers are rate limited and every decision is written to the contract history and the audit log.

Option Default Description
enabled true false = no Market tab and no listing
account 'bank' Reserved. Payments currently use the server's money account, Config.MoneyAccount
modes { sale = true, lease = true } Which listing types are allowed
listing see right days 14, maxPerChar 3, cooldownMinutes 10, fee 0, titleMax 48, descriptionMax 600, photosMax 6, openHouseMax 4, openHouseMinutes { 30, 60, 120 }, openHouseAheadDays 14, minPrice 1000, maxPrice 100000000, minRent 50, maxRent 1000000
offers see right hours 48, maxOpenPerBuyer 5, maxRounds 10, messageMax 140, minPct 50 (lowest offer as a share of the asking price), requireFunds true
contracts see right signHours 48, instantAtAsking true, nameMatch true, requireDrawing false, cancelPenaltyPct 0, archiveShown 50 (finished contracts shown in the archive)
fees { salePct = nil, leasePct = 0, buyerTaxPct = 0 } Seller fee in percent (nil = Config.Finance.transfer.feePct), landlord fee on every rent, and a tax on top of a sale price paid by the buyer
lease see right periods { 7, 14, 30 } days, maxPeriods 12, depositMaxPeriods 3 (deposit at most this many rents), startAheadDays 7, graceHours 48, role 'tenant' ('tenant', 'guest' or 'coowner'), autopay true, blockSale true
clauses see right Fixed clause ids per kind. Sale: as_is, vacant, inspected, no_liens. Lease: no_pets, no_parties, no_sublet, quiet_hours, furnished, auto_renew, early_exit_fee. Their texts are in locales/marketplace
realtor { enabled = true } Realtors may broker listings
antiAbuse see above sameLicense 'block', pairCooldownHours 72, minPriceRatio 0, flagBelowRatio 0.5
disputes { enabled = true, windowDays = 7, reasonMax = 300 } Dispute switch, how many days after the last change one can be opened, and the longest reason
tickSeconds 30 How often expiries and rents are checked

The tables aty_housing_market_listings, aty_housing_market_offers, aty_housing_contracts and aty_housing_contract_log are created automatically and have no foreign keys, so the audit trail stays when a property is deleted. Pending contracts, escrow and running leases survive a restart.

Integration (server): exports GetMarketListings(mode?) (open listings; mode 'sale' or 'lease'), GetMarketListing(listingId), GetContract(contractId) (with sellerId, buyerId and brokerId), GetContractsOf(charId, limit?), GetActiveLease(propertyId) ({ contractId, tenant, tenantName, landlord, rent, periodDays, startAt, endAt, paidThrough, status } or nil) and CancelContract(contractId, reason?) (pending contracts only, the escrow is refunded; true or false). Events (use AddEventHandler only): aty_housing:marketListed (listingId, propertyId, mode, price, ownerCharId), aty_housing:marketUnlisted (listingId, propertyId, reason), aty_housing:marketOffer (offerId, listingId, propertyId, byCharId, amount, 'offer' | 'counter'), aty_housing:contractCreated (id, propertyId, kind, sellerCharId, buyerCharId, price), aty_housing:contractSigned (id, propertyId, side), aty_housing:contractCompleted (id, propertyId, kind, price), aty_housing:contractClosed (id, propertyId, status, reason), aty_housing:contractDisputed (id, propertyId, side) and aty_housing:leaseRentPaid (id, propertyId, amount, paidCount). Hooks: canMarketList, canMarketOffer and canSignContract (each can return false, message to refuse; see Hooks) and onContractCompleted. A sale also runs canBuy and onPurchased (with via = 'marketplace').

Discord webhooks: the category market (created, completed, lease_started, lease_ended, lease_terminated, cancelled, expired, failed, dispute, resolved, flagged) is in server/config_webhooks.lua like the others. Its message titles come from locales/marketplace/<lang>.lua (the wh_market_* keys).