Furniture, lighting and yards
aty_housing: Furniture, lighting and yards
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
Furniture store
Furniture can be bought at physical stores or from an optional online catalog (Config.FurnitureStore). Bought pieces go to the character's My furniture (a list in the database, not inventory items) and are placed from the Decor Studio's My furniture source. Removing a placed piece and saving puts it back into My furniture (removeTo = 'storage'; 'refund' pays money back at Config.Decor.refundRatio as before). While no store exists and the online catalog is off, the Decor Studio keeps buying directly, so an unconfigured server behaves as before.
Placing a store. No store ships; add your own in Config.FurnitureStore.stores. Stand where the counter should be and run /housingfstore here <id> <label>: the server console prints the config line to paste. /housingfstore add <id> <label> adds the store for the current session only. A store entry is { id, label, point = { x, y, z, w }, pickup?, blip?, categories?, priceMultiplier?, modes?, showroom? }: pickup is a separate collection point, blip = { sprite, color } (or false), categories limits what it sells (default all), priceMultiplier scales its prices, modes lists its delivery modes and showroom is a list of { model, x, y, z, h } display pieces that spawn within showroomRange.
Delivery modes (set per store with modes, switched on or off with delivery.<mode>.enabled):
| Mode | What happens | Default fee |
|---|---|---|
instant |
The pieces go straight to My furniture | 0 |
scheduled |
Delivered after minutes (default 10) to a property you own, rent or may decorate; the player gets a notification. With courier.required = true a courier script must deliver (exports below); fallbackMinutes after the due time it arrives anyway (0 = never) |
250 + 25 per piece |
pickup |
Waits at the store's pick-up point until the player collects it | 0 |
Players. Walk to a store (target or E within interactRange) and open the shop: browse the catalog, filter, sort, compare up to 3 pieces, fill a cart and check out with the bank or cash (accounts). My furniture lists what you own and lets you sell pieces back at a store for sellBackRatio of the price paid (paid out to payoutAccount; the online catalog sells back only with sellBackOnline = true). The Orders tab shows open orders; an open order can be cancelled (until a courier has taken it) for delivery.cancelRefundRatio of its price. With online.enabled = true, /furniture (online.command) opens the catalog anywhere with its own priceMultiplier and modes.
| Option | Default | Description |
|---|---|---|
enabled |
true |
false = no store, the Studio buys directly |
studioDirectBuy |
true |
The Studio catalog keeps try and buy; false = the Studio only places owned pieces |
removeTo |
'storage' |
'storage' (back to My furniture) or 'refund' (money) when a placed piece is removed |
presetPickup |
false |
Pieces of a furnish preset may go to My furniture too |
sellBackRatio / sellBackOnline / payoutAccount |
0.5 / false / 'bank' |
Sell-back share, online sell-back, and the account that gets the money |
accounts |
{ 'bank', 'cash' } |
Accounts a checkout may use |
maxPiecesPerOrder / maxStock / maxOpenOrders / ordersShown |
25 / 200 / 5 / 20 |
Pieces per checkout, pieces one character may own and not have placed (0 = no limit), open delivery and pick-up orders per character (0 = no limit), orders listed in the Orders tab |
adminCommand |
'housingfstore' |
Admin command (see Commands) |
interactRange / showroomRange |
3.0 / 60.0 |
Metres for using a store point / for spawning showroom pieces |
online |
off, 'furniture', x1.15, { 'scheduled' } |
{ enabled, command, priceMultiplier, modes } |
delivery |
see above | instant, scheduled, pickup (enabled, fee, minutes, perPiece), cancelRefundRatio (1.0), courier (required = false, fallbackMinutes = 30) |
item |
{ enabled = false, name = 'furniture_box', unpackAtHome = true } |
When enabled, collecting a pick-up order gives one inventory item per piece (add the item name to your item list first); using it unpacks the piece into My furniture, with unpackAtHome only inside a property you may decorate |
blip |
{ sprite = false } |
Default blip of every store (sprite = false = none; { sprite, color, scale }) |
stores |
{} |
Your stores |
Integration (server): exports GetFurnitureStock(charId) ({ [model] = n }), GiveFurniture(charId, model, count?, paid?), TakeFurniture(charId, model, count?), GetFurnitureStores(), and for courier jobs GetFurnitureDeliveries(filter?) (open scheduled orders; 'all' adds pick-up orders), ClaimFurnitureDelivery(orderId, src), ReleaseFurnitureDelivery(orderId) and CompleteFurnitureDelivery(orderId, src?). Events: aty_housing:furnitureDeliveryCreated (order) and aty_housing:furnitureDeliveryCompleted (order, courierCharId). Hook canBuyFurniture ({ source, charId, store, mode, propertyId, items = { { model, n, price } }, total }): return false, message to refuse a checkout.
Lighting and colours
Lamps placed in the Decor Studio can have a light scene: a white temperature or a colour, a brightness and an optional party colour cycle. Owners can also change the details of an IPL interior (clothes, bottles, ashtrays and smoke) and tint furniture that has colour variants. The settings live in their own file, shared/config_colours.lua (Config.Colours), which is read when the resource starts. Everything is checked on the server: a client can only name a saved lamp or switch of the property it stands in, and every scene value is read and clamped. Config.Colours.enabled = false switches the whole feature off: lamps keep one fixed warm light and the Style tab has no controls.
Light scenes
A scene holds these fields:
| Field | Values | Meaning |
|---|---|---|
preset |
a key of Config.Colours.presets, or custom |
A named preset takes its mode, colour and effect from the config; brightness, speed and spread can still be set |
mode |
temp or rgb |
White light by temperature, or a colour |
kelvin |
1500 to 10000 | Temperature of a temp scene |
color |
#rrggbb |
Colour of an rgb scene |
intensity |
0 to 100 | Brightness in percent |
fx |
static or party |
party cycles through the colour wheel |
speed / spread |
1 to 10 / boolean | Party cycle speed (one turn of the wheel takes 22 minus twice the speed in seconds: 20 s at speed 1, 2 s at speed 10); with spread every lamp sits at its own point of the wheel |
Scope. A lamp uses the first scene it finds in this order: the lamp's own scene, the scene of the light switch it is wired to, the home scene, Config.Colours.default. So Whole home styles every lamp that has nothing more specific, Switch styles every lamp wired to that switch, and This lamp styles one lamp. Removing a scene (Reset) hands the lamps back to the next scope. A property can hold maxLampOverrides switch scenes and the same number of lamp scenes. A scene for a lamp or switch needs a saved piece, so save the layout first; scenes of pieces that are later removed are dropped on their own.
Where players change it
- Decor Studio, Style tab and the lamp inspector: pick a scope, a preset chip or your own white temperature / colour, brightness, and for a party scene the speed and the spread. Changes apply and save at once for everyone inside the property; they are not part of Save or Undo. You must be inside the property (not in a preview), hold the
decorpermission, and not be a read-only viewer. A police seal takesdecorfrom everyone. - Light switch prompt, second key (
Gby default, a FiveM key mapping): the label reads Scene: and every press moves the lamps of that switch to the next preset ofcyclePresets, keeping their brightness. Use it from the switch itself (the server checks you are near it). It needs the owner, a tenant or a key holder, unlessguestsCycle = true, when anyone inside may. It does not needdecor. - Both ways are rate limited and both ask the
canChangeColourshook (Hooks).
Power. Light scenes follow the power supply. With the power cut (an unpaid bill, Config.Utilities.cutoff) lamps stay dark, the switch prompt shows No power, the cycle key is refused and the Style tab says so. A lamp that is on counts on the power meter with its brightness divided by 50, times Config.Utilities.power.lightWatts: a lamp at the default 50 % uses exactly lightWatts, a lamp at 100 % twice that, and a party lamp is multiplied by partyWattsFactor.
Light. Each lit lamp is drawn as a game light of range metres with a strength of maxIntensity times its brightness. With objectLightColor the prop's own light is tinted too (best effort, not for party scenes). The glow baked into a lamp model stays as it is when the switch is off.
Presets. The shipped presets (a Config.Colours.presets entry per name):
| Preset | Scene |
|---|---|
warm |
White 2700 K, brightness 50 |
neutral |
White 4000 K, brightness 55 |
cool |
White 6500 K, brightness 60 |
candle |
White 1900 K, brightness 35 |
daylight |
White 5500 K, brightness 75 |
party |
Colour #ff3df2, colour cycle at speed 5 spread over the lamps, brightness 60 |
Add your own entry to presets (and to cyclePresets if the switch key should reach it). Its label comes from the text col_preset_<name> in locales/colours/<lang>.lua, so add that text in every language you use.
Furniture colour variants
Catalog items with "tintable": true in data/props.json offer colour variants in the Decor Studio inspector (a swatch row; the number of variants is the item's tints, and tintColors can hold measured swatch colours #rrggbb). A variant is saved with the layout and can be undone, like a move. 18 shipped items have variants: three mansion sofas, three lanterns, flower vases and pots, gallery art, a designer phone, a patio lounger and an exercise ball (3 to 12 variants each). To give another item variants, add "tintable": true, "tints": <count> (2 to 16) and optionally "tintColors": [...] to its entry. See Furniture catalog.
Interior details (IPL)
For an IPL property the Style tab lists the detail groups of its interior, taken from data/ipl_styles.json (the entity sets bob74_ipl exposes). All 17 catalog interiors have three groups: Clothes left around (strip), Bottles (booze) and Ashtrays and smoke (smoke), each with three sets; a group is either multi-choice or one set at a time (the smoke group of the mid-range apartment and the low-end studio). The choice is stored per property and applied for everyone inside it; a choice not in the file is refused. Config.Colours.details = false removes the groups.
| Kind of property | What the Style tab offers |
|---|---|
IPL with an entry in data/ipl_styles.json |
The detail groups above, plus light scenes |
Built shell (aty_shellcreator) |
A note: paint and materials are edited in the Shell Creator (/<shellCreatorCommand>, Paint tool); light scenes work |
| Other shell | No colour options; light scenes work |
| MLO | No interior style; light scenes work for placed lamps |
data/ipl_styles.json is keyed by the bob74_ipl export name of the interior (ipl.export in data/interiors.json) and holds interiorId (the game interior id) and groups, each with mode (multi or one) and sets (entity set names, letters, digits and _ only). It is plain data you can extend.
Colour configuration (Config.Colours)
| Option | Type | Default | Description |
|---|---|---|---|
enabled |
boolean | true |
false = lamps keep one fixed warm light, no Style tab controls, no colour calls |
default |
table | { preset = 'warm' } |
Scene of a home nobody has styled yet |
presets |
table | warm, neutral, cool, candle, daylight, party |
Named scenes (see above). mode = 'temp' uses kelvin (1500 to 10000), mode = 'rgb' uses color; fx = 'party' takes speed (1 to 10) and spread; intensity is 0 to 100 |
cyclePresets |
table | { 'warm', 'neutral', 'cool', 'candle', 'party' } |
Order of the switch prompt's Scene key |
maxIntensity |
number | 5.0 |
Light strength at 100 % brightness |
range |
number | 6.0 |
Light radius in metres |
saveDelayMs |
number | 1500 |
A burst of changes is written once, this long after the last (milliseconds). Players see changes at once |
guestsCycle |
boolean | false |
true = anyone inside, also a visitor without a key, may cycle a switch's scene |
partyWattsFactor |
number | 1.0 |
Power draw of a lamp in a party scene, times its brightness factor |
objectLightColor |
boolean | true |
Also tint the prop's own light (best effort) |
details |
boolean | true |
false = no interior details in the Style tab |
shellCreatorCommand |
string | 'shellcreator' |
Command named in the Style tab of built shells |
maxLampOverrides |
number | 150 |
Scenes per property for single lamps and, separately, for switches |
Scenes are stored in the table aty_housing_colours (one row per property); a row is removed when its property is deleted. With Config.Lifecycle.furnitureOnLeave = 'refund', the lamp and switch scenes of the removed furniture go with it; the home scene and the interior details stay with the property.
Colour integration
Server exports (propertyId = the property's numeric id):
| Export | Returns |
|---|---|
GetLightScene(propertyId) |
{ home, groups, lamps, details, now }: the home scene (or nil), the scenes by switch id and by lamp id (the placed furniture ids as text), the chosen detail sets per group, and the server time. nil for an unknown property |
SetLightScene(propertyId, scope, id, scene) |
true, or false, reason. scope is 'home', 'group' (a switch id) or 'lamp' (a lamp id); scene is a table of the fields above (read and clamped), or nil to reset that scope. No permission check and no hook; reasons: not_ready, not_found, invalid_input, col_too_many |
SetInteriorDetails(propertyId, group, sets) |
true, or false, reason: choose the entity sets of one detail group (sets = names listed for the interior, an empty list clears the group). No permission check and no hook |
Event (server-local, listen with AddEventHandler only): aty_housing:coloursChanged (propertyId, data, source) after a change; data has the shape of GetLightScene and source is the player's server id, or nil when a script made the change.
Hook canChangeColours (RegisterHook): { src, charId, propertyId, scope, id, scene } for a Style tab change (scene = nil when resetting), { src, charId, propertyId, details = { group, sets } } for interior details, and { src, charId, propertyId, scope = 'group', id, cycle = true } for the switch key. Return false, message to refuse. The exports above are not asked.
Garden and exterior decor
Every property can have a yard: an area on the ground outside, where owners place outdoor furniture (plants, benches, loungers, barbecues, a hot tub, garden lanterns) with the same Decor Studio they use indoors. Yard pieces stand in the shared world, so every passer-by sees them. The settings live in their own file, shared/config_exterior.lua (Config.Exterior), which is read when the resource starts. Config.Exterior.enabled = false switches the feature off: no yards, no yard Studio and no yard pieces.
Yards
A yard is a polygon on the ground plus a height band. It comes from one of two places:
- Automatic yard. An IPL or shell house without a drawn yard gets a circle of
autoYard.radiusmetres (12 m, a 12-sided shape) around its entrance; the circle shrinks to about half the distance to the nearest other entrance so that neighbouring yards never meet. Nothing has to be set up: the 24 Vinewood Hills houses get one from the first start (their entrances are far apart). There is none when the interior is an apartment indata/interiors.json(type = "apartment"), when another property's entrance is closer thanautoYard.minEntranceGap(14 m, which covers the units of an apartment building), when the circle would overlap another yard, or for an MLO property unlessautoYard.mlo = true. The yard follows the entrance when an admin moves it. - Drawn yard. An admin draws any shape with
/housingyardand the property keeps it until an admin resets it.
Drawing a yard (housing admin, see Admin permission). Stand near the property and run /housingyard, or /housingyard <property id>. Walk to each corner of the yard and use the keys shown on screen:
| Key | Action |
|---|---|
E |
Add a corner where you stand (the ground under your feet) |
X |
Remove the last corner |
H |
Go back to the automatic yard (removes a drawn yard) |
G |
Save |
Backspace |
Cancel (running /housingyard again also cancels) |
The editor draws your yard live, grey outlines for neighbouring yards and a blue outline for the automatic yard, and tells you the area against the limit. The server checks the result again: 3 to maxPoints corners, every side at least minEdge metres, no crossing sides, an area within maxArea for the property's tier (low, mid, high), the centre within maxEntranceDistance of the entrance and no overlap with another yard (minYardGap). With roadCheck the editor also refuses a yard that touches a road (checked on the admin's client, with roadMargin metres around each corner). Without an id the command picks the property whose entrance is nearest, within 60 m. Changing a yard closes an open yard Studio of that property. Pieces left outside a new, smaller yard stay where they are; the admin is told how many, and the owner must move them in or remove them.
Decorating the yard
- Open it. Stand in the yard (inside its outline or within
marginmetres of it, outside any interior) and run/housingdecor; inside a property the same command opens the interior Studio./housingdecor yard(orexterior) and/housingdecor interiorpick the mode when both would fit. - Who. The key permission
exterior("Yard" in the tablet's access matrix). The owner and a tenant always have it, the co-owner preset has it, roommate and guest do not (tick it per key). A key saved before this permission existed follows itsdecorsetting. One editor at a time per yard; others see a read-only view. - What. Only catalog items marked
"exterior": trueindata/props.jsoncan stand in a yard: 112 shipped items (60 plants, 49 outdoor pieces and 3 garden lanterns). Storage furniture, light switches and cameras never go outside. The Studio refuses an indoor piece, a spot outside the polygon or its height band (zBelowmetres under the lowest corner tozAboveabove the highest) and, withroadCheck, a spot on a road. - How many.
maxObjectspieces per yard plus theyardproperty upgrade (+15, +30, +60 pieces for 6,000 / 12,000 / 24,000, offered only to a property that has a yard; see Property upgrades). - Prices. Exactly as indoors: catalog price with
Config.Decor.priceMultiplierand the category multipliers, My furniture stock, removal refunds. The Studio camera stays near the yard and there is no Style tab outdoors. - Garden living. Garden pieces with a use work from the yard: benches and chairs (sit), loungers (lie down), barbecue grills (cook, station
bbq) and the hot tub (bath). The user must stand in the yard and the property must not be sealed; they need theenterpermission, or anybody may use them withlivingPublic = true(use by someone without a key is not charged to the owner). The power supply never darkens a yard. - Night lights. With
nightLights, garden lanterns glow between 19:00 and 06:00 (game clock) for players within 60 m, up to 16 at a time. They have a fixed warm colour, need no switch and do not use power, and light scenes do not apply to them.
Visibility and streaming
Yard pieces are not world objects on the server. Each client spawns them as frozen local objects for the yards it is near: a yard loads when its edge is within streamRadius metres, at most maxLoadedYards (nearest first) at once, spawnPerTick pieces per tickMs milliseconds, with the draw distance lodDistance. Yards farther than streamRadius plus 25 m are removed again. Nothing is spawned while a player is inside an interior. Saved changes reach everyone near the yard live. Passers-by see only the piece, never its price or name.
What happens when a property changes
Yard pieces are stored with the property's furniture (table aty_housing_furniture, world coordinates), the drawn yards in aty_housing_yards.
| Event | Yard |
|---|---|
Owner changes (sale, rental ended, transfer) with Config.Lifecycle.furnitureOnLeave = 'keep' |
The yard and its pieces stay for the next owner; an open yard Studio closes |
furnitureOnLeave = 'refund' |
Every yard piece is removed and refunded with the interior furniture |
Transfer with the furniture cleared, repossession with Config.Finance.repossession.furniture = 'clear', admin Reset |
The yard pieces are removed with the furniture; the drawn yard stays |
| Admin deletes the property | The drawn yard and every yard piece are deleted |
An admin resets a drawn yard (H) |
The automatic yard applies again (if the property gets one); pieces outside it stay |
| An admin moves the entrance | An automatic yard moves with it |
Yard configuration (Config.Exterior)
| Option | Type | Default | Description |
|---|---|---|---|
enabled |
boolean | true |
false = no yards, no yard Studio, no yard pieces |
adminCommand |
string | 'housingyard' |
Admin command that draws or resets a yard ('' = none) |
maxObjects |
number | 40 |
Pieces per yard, plus the yard upgrade |
maxArea |
table | { 250, 450, 800 } |
Largest drawn yard in square metres for a low, mid and high tier property (the creator and realtor tier). Does not apply to automatic yards |
maxPoints |
number | 24 |
Most corners of a drawn yard |
minEdge |
number | 0.75 |
Shortest side of a drawn yard, metres |
zBelow / zAbove |
number | 3.0 / 12.0 |
Height band of a yard: from the lowest corner minus zBelow to the highest corner plus zAbove, metres |
margin |
number | 2.0 |
How far outside the outline a player still counts as in the yard (opening the Studio, garden seats), metres |
maxEntranceDistance |
number | 60.0 |
The centre of a drawn yard must be this close to the entrance, metres |
minYardGap |
number | 0.5 |
Two yards must stay this far apart, metres |
autoYard |
table | { enabled = true, radius = 12.0, mlo = false, minEntranceGap = 14.0 } |
Automatic yards: on or off, circle radius in metres, also for MLO properties, and the distance another entrance must keep (apartment blocks get none) |
streamRadius |
number | 120.0 |
A yard's pieces spawn for players this close to it, metres |
maxLoadedYards |
number | 10 |
Most yards spawned at once per player |
spawnPerTick |
number | 6 |
Pieces spawned per tick while a yard loads |
tickMs |
number | 1000 |
Streaming tick in milliseconds |
lodDistance |
number | 150 |
Draw distance of yard pieces, metres |
nightLights |
boolean | true |
Garden lanterns glow from 19:00 to 06:00 |
roadCheck |
boolean | true |
The yard editor and the yard Studio refuse spots on a road |
roadMargin |
number | 1.0 |
Metres around each corner that are also checked for a road |
livingPublic |
boolean | false |
true = anybody in the yard may use garden seats, loungers and the grill; false = only players with enter (a key) |
Yard integration
Yards have no exports, events or hooks of their own. The exterior permission is part of the access API (HasAccess(srcOrCharId, propertyId, 'exterior'), see Exports), the upgrade is read with GetUpgradeBonus(propertyId, 'exteriorObjects'), and aty_housing:propertyChanged fires when a property's entrance moves, which recomputes its automatic yard.