Room dressing

Once a room's furniture stands, the game puts small things on it: papers and a mug on a desk, a lamp and a book on a bedside table, a kettle and a chopping board on the kitchen worktop, beer mats and glasses on a bar, a card terminal on a shop counter. Which objects go on which surfaces is mod data, in .uldressing files.

#How it works

1. Every generated piece in the room that has a surface is a possible host: its catalog entry has levels (the surfaces something can stand on, see Rooms) or at least a surface height.
2. For each host, the most specific rule whose ON matches it is used. A rule takes the levels it names (LEVEL), and a later rule can still use the host's other levels.
3. The rule rolls how many things go on each level (COUNT, capped by DENSITY, both scaled by the room's personality), draws each one from PROPS, and looks for a free spot on that level, away from the edge and from anything already standing there.
4. Each object is a separate piece in the room, like any other node of a set, so a hand can pick it up (Actor:PickUp("Mug")) when the catalog marks it handheld.

What is placed depends only on the building's seed, the furniture group and the rule. Moving a desk in build mode re-dresses that desk alone.

Objects come from the room's own sets first, so they match its style, then from the sets in PROP_SETS. A piece is a possible object when it is a generated piece, not wall-hung, and no larger than 90 cm.

#A dressing file

lua-- Rooms/Dressing/police.uldressing
return {
	NAME = "police",
	VENUES = { "police" },             -- venue tags; or GRAMMARS = { "cid_office", ... }
	BASE = "office",                   -- take the office rules first
	RULES = {
		{ ID = "desk", ON = { "Desk" }, LEVEL = "top", EDGE = "any",
		  COUNT = { 2, 5 }, CHANCE = 0.95, DENSITY = 6,
		  PROPS = {
			{ LEAD = "Product/Radio", MATCH = { "Transistor", "DAB" }, WEIGHT = 0.6, MAX = 1 },
			{ LEAD = "Product/Folder", WEIGHT = 3, MAX = 3 },
			{ LEAD = "Product/Mug", WEIGHT = 2, MAX = 2 },
			{ LEAD = "Product/EvidenceBag", WEIGHT = 1.5, MAX = 2 },
		  } },
		{ ID = "custody_desk", ON = { "Counter/CustodyDesk" }, LEVEL = "all",
		  PROPS = {
			{ LEAD = "Product/CardTerminal", MAX = 1, REQUIRED = true },
			{ LEAD = "Product/Clipboard", MAX = 1 },
		  } },
	},
}

The files live in Rooms/Dressing/*.uldressing in any mod. They are Lua tables, like grammars.

#File fields

Which rule wins. The rules of every file that applies are gathered: files for every room first, then the files that name the venue or the grammar. A rule ID seen again replaces the earlier rule, so a venue file can redefine the generic desk rule for its own desks. On each host, the rules are tried from the most specific (the last gathered) to the most generic. A rule with OFF = true switches an inherited rule off.

#Rule fields

COUNT and DENSITY grow with the room's PERSONALITY.CLUTTER and shrink with its CLEANLINESS (from the .ulroom): a squat's desk is fuller than a bank's.

#Prop fields

An object is only placed where it fits: lower than the free height above the level (a shelf under another shelf), inside the level, and not over anything already there.

#Shop stock

A rule with STOCK = "shop" fills its hosts with the goods of the venue's shops: every item of the venue's .ulshop files whose .ulitem has a Piece: that matches a piece of the room's sets or PROP_SETS. On each level, COUNT runs of one item stand side by side along the front edge (2 to 6 of the same, like a faced-up shelf; a double-sided gondola's far half faces the other aisle), the item drawn with cheap things more often than dear ones. Each object is the shop's stock: buying one takes one off, a limited line shows no more than the shop has left, and they come back when the shop restocks (see Stock on the shelves).

lua{ ID = "shop_stock", ON = { "Display/Gondola", "Display/Shelf", "Storage/Shelf", "Display/Showcase" },
  NOT_MATCH = { "Stocked", "Bottles", "Full" }, LEVEL = "all", STOCK = "shop", COUNT = { 2, 5 }, FILL = 0.85 },

#What the game leaves alone

• A level that already carries products from its group (the laid café tables, a counter with its till) is not dressed again.
• Objects are never tinted: the furniture materials are shared by every room.
• Furniture from the old packs (not generated) has no measured surfaces and is not dressed.

#Shipped files

To check your files, run python Tools/RoomKitExport/check_dressing.py from the game's folder: it lists the PROPS that name no piece and the rules whose ON matches no piece with a surface.

#The objects are real

Every object the dressing places can be clicked: taken into the inventory, picked up in a hand, put down elsewhere (see Things in rooms). The dressing comes out the same on every visit, so the game only saves what the player changed, per building and room, and applies it right after the dressing. Which item an object is comes from an .ulitem's Piece: or from Items/room_objects.json.

In a shop, the objects of a STOCK rule are what the shop sells: buying takes them off the shelves (see Stock on the shelves).