# Area
A piece of a level that says which roles belong there: public street, work yard, staff only, guards only, inner court or forbidden ground (`kind`), or exactly the roles you list (`allow`, one setting: `"porter, cook"`, `"*"` or `"none"`). A box centred on the entity (turning with its yaw) or a circle (`radius`); where areas overlap the highest `priority` wins. Put it on any plain entity; it needs no sibling components. Standing in an area your disguise does not belong in is the `trespass` behaviour watchers notice.
# WorkSpot
Somewhere a disguised player can do a job (sweep, tend, fish, haggle, drawWater, kneel, pray) or pick up and put down goods (`pickup` hands the `cargo`, `dropoff` takes it). Press act (F, the pad's right bumper, Act on a phone) beside it. Working in clothes the job admits (`roles`, empty = anyone) blends the player in: watchers farther than the blend range stop noticing. Put it on a plain entity; it draws a mat (and a sack pile) unless `showMark` is off.
# Disguises
The kit's switch for a scene, and its settings: put one on a plain local entity and players get disguises in play. It spawns each player's Wearer, dresses every player and every Outfit NPC, judges this peer's own player against every Watcher, and draws this player's notice signs, badge, prompts and touch buttons. `signStyle` swaps every notice sign (inkBrush, paperLantern, woodPlaque, pixel, minimal, comic) with one change; `startRole` is what players arrive in; the keys, blend range, change time and how long it takes to lose pursuers are fields too.
# Wardrobe
A place to change clothes: a laundry line, a clothes chest or a robe rack (`kind`) holding one role's clothes (`role`, `variant`, or `random`). A player holds the interact button there (interactKit's prompt: E, the pad's west button, or Interact on a phone) for the quick change. `uses` limits the sets. Put it on a synced entity (`DK.wardrobe` does it and adds the `interactKit.Interactable` prompt beside it).
# Outfit
Dresses any character (an aiKit guard, a scripted figure) in a role's clothes, the same humanBodyKit body a disguised player gets, so the garrison and a player in a soldier's coat look alike. Every peer builds the body from the synced role, look and seed, hides the character's own mesh, and poses it from how the entity moves (walking, running on a chase, standing in `idlePose`, lying when knocked out). Needs no sibling components.
# Interactable
Makes any entity usable: a prompt when the local player is within `range` (trigger `proximity`) or also looking at it (`look`), a quick press or a `holdTime` hold with a fill-up, from E, the pad's west button or the touch Interact button. Alone it fires `use` on every peer and sends `action` to `targets`; beside a Door, Switch, Container or Barricade it overrides that device's prompt settings (`promptStyle`, `range`, `trigger`, ...).
# DockhandsGame
The rules of the Dockhands level on every peer for that peer's player: the opening card, the objective list (a porter's coat, a sack from the pier, inside the warehouse, the ledger desk), copying the ledger at the desk to win, being thrown back to the beach when a soldier catches you after you were called out, harbour ranks kept across runs with saveKit, and a shout to every player when someone wins. Put one on a plain entity in the level.
# Watcher
Someone who looks at players and can see through a disguise. `kind` picks who they are: guard (judges clothes, places and behaviour), foreman (knows porters, farmhands and fishers by face), captain (soldiers and retainers), headOfHouse (tea servants, cooks, entertainers), abbot (monks) or onlooker (a townsperson who reports you to the nearest guard). Put it on an aiKit guard (concealKit's `Hide.guard`), a townsfolkKit townsperson or any entity facing -Z. Each player's own machine judges that player against every watcher and draws the watcher's notice sign on that player's screen.
# Layout
Lays the Dockhands level out on the tropicalKit cove: the beach spawn, the stilted dock yard beside the pier, the salt warehouse with its ledger office, the guard hut and tea stall, the townsfolk (an indigo porter gang, fishers, a tea seller, a cook, a monk, a trader who reports you), the soldiers and the foreman, and every disguiseKit area, wardrobe and work spot. Called once from `scenes/dockhands.scene/build.luau`; level-only code, not part of disguiseKit.
# disguiseKit
**Social stealth disguises for any multiplayer Zero world.** Put on the clothes of a social role (a porter, a monk, a cook, a foot soldier) and you can walk where that role belongs without the guards caring, as long as you act the part. Wrong clothes in the wrong place, or acting out of character, and the watchers nearby start to notice you: a little notice sign over each one's head shows how close they are to calling you out. Some people see through a disguise up close: a foreman knows every porter on his crew, a captain knows his soldiers, a head of house knows the staff. Lose yourself in a knot of workers or at a job and the watchers further off stop noticing. Take clothes from a laundry line, a clothes chest, a robe rack or someone you knocked out, with a quick change.
Every player wears their own disguise and is judged by their own machine; everyone sees everyone else's clothes change, a player who joins late included. Keyboard, gamepad and touch.
Version **1.0.43** (`DK.VERSION`). Play it in the **Dockhands** level in this world.
## Quick start
This works as written in a brand-new world.
**1. Install** `disguiseKit.package` into `/source` (search ZeroMind for "disguiseKit" or "add disguises to my stealth game"). Its dependencies (townsfolkKit, humanBodyKit, aiKit, concealKit, interactKit and theirs) come with it.
**2. Add to `scenes/main.scene/build.luau`**, at the very end of `function content()`, just before its `end` (a new world's scene already has the ground, the light and the player):
```lua
local DK = require("disguiseKit.api")
local Hide = require("concealKit.api")
local NK = require("navKit.api")
-- the ground the foreman can chase you on (baked when play starts)
entity.spawn("NavMap").component.add(NK.MAP, { kind = "grid", size = { x = 40, y = 6, z = 40 } })
-- switch the kit on: everyone arrives dressed as a fisher
DK.setup({ startRole = "fisher", signStyle = "inkBrush" })
-- a staff-only store north of the spawn, and a foreman watching its door
DK.area({ 0, 0, 14 }, "staff", { size = { 12, 5, 10 }, label = "The Store" })
local foreman = Hide.guard({ 0, 0, 10 }, { name = "Foreman", yaw = 180 })
DK.watcher(foreman, "foreman")
foreman.component.add("disguiseKit.Outfit", { role = "porter", variant = "rust", prop = "none" })
-- a porter's coat on a laundry line, a sack pile and a place to drop the sack
DK.wardrobe({ 4, 0, 4 }, "laundryLine", "porter", { yaw = 90 })
DK.workSpot({ -4, 0, 4 }, "pickup", { cargo = "sack" })
DK.workSpot({ -2, 0, 14 }, "dropoff")
```
**3. Press play.** You stand in fisher's clothes; the badge top left says *Fisher · Public street · you belong*. Walk into the store: the badge turns *out of place*, and the foreman's ink-brush sign starts to close the longer he watches. Let it close and he calls you out and gives chase. Now walk to the laundry line and **hold E** to change into the porter's coat, **press F** at the sack pile to shoulder a sack, and walk in again: a porter with a sack belongs in a store. Get within 4 m of the foreman, though, and his sign starts closing anyway: he knows his crew, and you are not on it. Change `signStyle` to `"paperLantern"`, `"woodPlaque"`, `"pixel"`, `"minimal"` or `"comic"` and every sign changes.
The `main` scene of this world is that quick start pasted into a new world's scene.
## How it works
| piece | what it is |
|---|---|
| `Disguises` component | one per scene on a plain entity: switches the kit on and holds its settings (`signStyle`, `startRole`, keys, blend range...) |
| `Area` component | ground that says which roles belong: `kind` (public, workyard, staff, guards, innerCourt, forbidden) or `allow` |
| `Watcher` component | someone who notices: `kind` (guard, foreman, captain, headOfHouse, abbot, onlooker) |
| `Wardrobe` component | a laundry line, clothes chest or robe rack with one role's clothes |
| `WorkSpot` component | a job to blend in at (sweep, tend, fish, haggle, drawWater, kneel, pray) or goods to pick up and drop off |
| `Outfit` component | dress an NPC (an aiKit guard) in a role's clothes, the same body a disguised player gets |
| `Wearer` component | spawned for you: what each player wears, synced to everyone |
| `SharedRules` component | spawned by the host: who belongs where and which rules are on, the same for every player |
| `disguiseKit.api` | the one interface: `local DK = require("disguiseKit.api")` |
| two guides | the how-to and a worked example level (below) |
| `disguiseKitTests` test suite | 25 tests: a player judged by watchers, blending in crowds and at work spots, multiplayer clothes and shared rules, the catalogue and the rules (below) |
| `add-disguises-to-a-level` workflow | a guided run that adds disguises to a level step by step (below) |
**Judging.** Each player's own machine judges that player against every Watcher, every frame: can the watcher see them (range, view cone, walls, hidden in a concealKit spot), and if so, what is wrong. Each suspicious behaviour that applies adds its weight to that watcher's meter, faster up close; when nothing is wrong the meter drains after a moment. A full meter calls you out: your cover is blown, aiKit guards nearby are sent after you (`AI.alert`) and their own senses see you again. Nobody can catch you for the first `catchGrace` seconds (1.5) after you are called out, so a foreman who sees through you at arm's length gives you a moment to run (0 makes the catch immediate). Stay out of every watcher's sight for `loseSeconds` (7) or change clothes unseen and your cover comes back.
**Cover.** While your cover holds, the kit hides you from aiKit guards' own senses (`AI.setConcealed`) on every peer, so the disguise, not raw line of sight, decides whether guards care.
## Roles
Ten roles, each in three looks (a fixed livery: hat and cloth colours) so a disguised player can match the crew around them, plus the player's own clothes (`own`). Bodies come from humanBodyKit (1.1.0 added the soldier, retainer, cook and tea servant outfits, fixed liveries and the sword for this kit).
| id | label | looks | normal for the role | carries |
|---|---|---|---|---|
| `farmhand` | Farmhand | straw, ochre, olive | goods | |
| `porter` | Porter | indigo, rust, brown | goods | |
| `soldier` | Foot soldier | black, indigo, red | a drawn blade, running | spear |
| `samurai` | Retainer | charcoal, wine, olive | a drawn blade | |
| `monk` | Monk | saffron, grey, ochre | | |
| `teaServant` | Tea servant | rose, sea, plum | goods | tray |
| `merchant` | Merchant | teal, crimson, saffron | | |
| `entertainer` | Entertainer | magenta, turquoise, scarlet | climbing, running | |
| `cook` | Cook | white, indigo, ochre | goods | |
| `fisher` | Fisher | faded, sand, rust | goods | |
| `own` | Own clothes | travel, dark | | |
`DK.defineRole({ id, label, outfit, variants = { { id, label, hat, colors } }, normal, cargo, prop, townsfolk })` adds your own.
## Areas
| kind | who belongs | priority |
|---|---|---|
| `public` | everyone, own clothes too | 0 |
| `workyard` | farmhand, porter, fisher, cook, soldier, retainer, merchant | 10 |
| `staff` | porter, cook, tea servant, farmhand, soldier, retainer | 20 |
| `guards` | soldier, retainer | 30 |
| `innerCourt` | retainer, tea servant, monk | 40 |
| `forbidden` | nobody | 50 |
Change who belongs with **one setting**, and every player sees the change, late joiners included:
- one area: `DK.setAreaAllow("The Store", "porter, fisher, cook")`, or edit the Area's `allow` field in the inspector during play. Name the area the way the badge shows it (its `label`, here the quick start's "The Store"; in Dockhands, "Salt Warehouse"), by its entity name, or pass its entity; case and extra spaces do not matter, and a label several Areas share changes all of them. `"*"` lets everyone in, `"none"` nobody, `nil` goes back to what the Area says. A name no Area has is an error that lists the areas there are;
- every area of a kind: `DK.tuneArea("staff", { "porter" })`;
- read it back: `DK.areaAllow("The Store")`, `DK.sharedRules()` (whose `areas` are keyed by each Area's entity name).
These go onto the synced `SharedRules` record the host owns; a player who is not the host sends the change to the host. An Area's `allow` set while building the level is part of the scene, the same for everyone. Ground outside every Area counts as `defaultArea` (public).
## Suspicious behaviour
| id | what | weight |
|---|---|---|
| `trespass` | standing where the disguise does not belong | 0.32 |
| `run` | sprinting | 0.42 |
| `climb` | jumping, climbing, dropping | 0.55 |
| `sneak` | moving crouched in plain view (C / pad B / Sneak) | 0.38 |
| `carryBody` | carrying or dragging a knocked-out person (concealKit) | 1.4 |
| `bladeDrawn` | walking with a drawn blade (X / pad Y / Blade) | 0.9 |
| `oddCargo` | hauling goods in clothes that never carry anything | 0.25 |
Switch any rule per role: `DK.setRule("monk", "run", false)` (running monks are fine now), `DK.setRule("*", "climb", false)` for everyone, `nil` to go back to the role's default. `DK.tuneRule("run", { weight = 0.6 })` changes a weight; `DK.configure({ pace = 0.8 })` makes every watcher quicker.
## Watchers
| kind | range / cone | sees through (within) | when the sign fills |
|---|---|---|---|
| `guard` | 16 m / 120° | nobody | calls you out |
| `foreman` | 14 m / 130° | porter, farmhand, fisher (4 m) | calls you out |
| `captain` | 18 m / 120° | soldier, retainer (4 m) | calls you out |
| `headOfHouse` | 13 m / 140° | tea servant, cook, entertainer (4 m) | calls you out |
| `abbot` | 12 m / 140° | monk (4 m) | calls you out |
| `onlooker` | 11 m / 150° | nobody | runs to tell the nearest guard |
Seeing through a disguise only happens inside the recognise distance (4 m): further off, a foreman judges a porter like any guard would, by place and behaviour. A Watcher's own fields override its kind (`range`, `fov`, `recognise`, `knows`). `DK.defineWatcher` adds a kind.
## Blending in
- **A crowd:** walking inside a townsfolkKit `TownGroup` (`TF.isInGroup`), or in among two or more townsfolk of your disguise's trade within 3.2 m, or any three people.
- **Work:** working at a `WorkSpot` whose `roles` include your disguise.
Inside a crowd, watchers farther than `blendRange` (4.5 m) stop noticing you **even in clothes that do not belong there**: a monk in among the porters on a work yard goes unseen by a guard 8 m off. Acting out of character (running, climbing, sneaking, a drawn blade, carrying a body) still gives you away inside a crowd, and stepping out of it starts the meters again. Working at a `WorkSpot` whose `roles` take your disguise hides you the same way (a cook sweeping a yard cooks do not belong in), and a spot for another trade does not. Up close (inside `blendRange`) watchers judge you as usual, and someone who knows your role's faces catches you within 4 m.
## Getting clothes
- **Wardrobe** (`laundryLine`, `clothesChest`, `robeRack`, `coatStand`, `tailorsTable`; each drawn in the colours of the look it holds): hold E (interactKit prompt, pad X, Interact on touch), or hold Act (F, pad RB, the Act button on touch). Act is always on a phone screen, where the engine may fold its Interact button into the "..." menu.
- **A knocked-out person:** stand by a downed townsperson (townsfolkKit) or a knocked-out guard (concealKit) and hold F (pad RB, Act on touch). Their clothes are their townsfolk role, their `Outfit`, or what you set with `DK.setClothes(entity, role, variant)`.
- **From code:** `DK.dress("porter", "indigo")`.
A watcher who sees you change gains 0.6 on their meter; the others forget who they were watching.
## Notice signs
Eight styles, swapped for the whole game by the Disguises component's `signStyle` (or `DK.setSignStyle` on one peer):
| id | look | suits |
|---|---|---|
| `inkBrush` | a brush circle that closes; a red seal with an eye when it does | painted, ink, woodblock |
| `paperLantern` | a lantern filling with amber then red light | painted, realistic, night |
| `woodPlaque` | a hanging wooden tag whose carved eye opens | realistic, painted, low-poly |
| `pixel` | an 8-bit eye over a segmented bar | pixel, retro |
| `minimal` | a thin ring filling around a dot | minimal, sci-fi |
| `comic` | a wobbling burst whose squiggle becomes a stare | toon, comic |
| `hanko` | a square red seal that inks in from the bottom; a stamped eye when it closes | painted, woodblock, ink |
| `radar` | a sweep that widens as they notice you, pulsing red on a call-out | sci-fi, modern, minimal |
Each player sees only the signs about themselves. A sign sits just over its watcher's head and keeps a readable size at any distance (34 to 66 UI points). When signs would overlap (two soldiers side by side at a door), they share one row, side by side in the order their watchers stand across the screen, each with a thin leader line down to its own watcher's head, so no leader crosses another sign. The signs draw on a screen of their own (`disguiseKitSigns`) in the always-on-top UI band, layer 920 by default (the Disguises field `signLayer`): over HUD chrome such as saveKit's XP bar and level-up banner (layer 900), under modal panels (940 and up), and that screen never takes a click. Drawn over the banner is not drawn on it: saveKit (1.3.15 and later) states the banner's rect in `ui.safeArea().controls` while it shows (and 1.3.18 and later its "Saved" flash too), and the signs step clear of it like any other control; when the nearest step clear is taken, a sign tries the spots beside every obstacle and takes the nearest free one. A sign stays close to the person it belongs to: its box never stands further from its watcher's head than 30% of the screen's shorter side (180 UI points at most; 117 on a phone either way up), so it never steps round the HUD to the far edge of a narrow screen. A sign never covers a panel, a control or another sign, at any screen size: a shared row with no free place splits into single signs that each find a place of their own, a sign that still has none drops its name tag and shrinks to the smallest size, and one that finds no place even then is not drawn that frame (the badge and the call-out message still say who saw you). A leader line that would cross a panel or a control is left out. Signs and their name tags stay fully inside the screen (clear of the edges and the top band), and they step out from under the badge, the prompt, toasts, every on-screen control in `ui.safeArea().controls` and any panel a level names with `DK.hudKeepClear`. interactKit's take / hide prompts are kept clear the frame they appear: the kit reads the rects interactKit reports in `lastFrame().rects` (interactKit 1.6.6 and later; an older one is read from what it drew the frame before), and the HUD redraws at once when a prompt appears or goes, a message changes or the cover blows. The badge states its own rect as the control `disguiseKitBadge`, so other screens can keep clear of it. A watcher off the screen's edge has its sign wait at that edge. `DK.hideSigns(owner, true)` hides every sign while a level shows a result screen. Once a watcher is more than curious and within 22 m, a name tag (the Watcher's `label`, else the kind's) shows under the sign.
## Controls
| | keyboard | gamepad | touch |
|---|---|---|---|
| sneak (toggle) | C | B (east) | Sneak button |
| draw / sheathe blade | X | Y (north) | Blade button |
| act: change at a wardrobe, take clothes from a body, work, pick up / drop goods | F (hold to change or take clothes) | RB | Act button |
| change at a wardrobe, hide, carry bodies | E (interactKit / concealKit) | X (west) | Interact |
Keys are Disguises fields (`sneakKey`, `bladeKey`, `actKey`). The kit follows the device class the engine itself presents (the one its own Jump / Interact column follows). On a touch screen it shows Sneak, Blade and Act buttons in a column just left of the engine's bottom-right controls, sized to the screen (52 to 72 points), and the hint line names those buttons instead of keys. The hint line stands at the bottom middle when that is free; otherwise it takes the lowest free row the screen's stated rects leave (the badge, a level's panel, an XP bar, the engine's and the kit's touch controls), wrapping onto two lines when no row is wide enough, and the notice signs keep clear of it. It looks in the bottom half first and higher up only when the bottom half is full.
On a phone held upright (narrower than 600 points and taller than wide) the kit lays out for the space it has, in play and when you are called out:
- the badge stays left of the engine's Menu button and wraps its lines instead of growing under it (which used to push it, and the level's panel under it, down the screen);
- the kit states the player's head and coat (the middle of the picture, where the follow camera keeps the player: about 0.38 to 0.58 of the screen's height and its middle 36%) as a rect in `ui.safeArea().controls`, owner `disguiseKitPlayer`, so saveKit's XP bar (1.3.16 and later) steps up above it and the player's hat and coat stay in view; a level's own HUD can keep clear of it the same way;
- the hint line uses a short form ("Act: work · Sneak · Blade · drag to look"), wraps inside its box and keeps clear of the player, so it sits under the player beside the touch buttons;
- messages (the kit's call-out line and anything a level sends through it) wrap to the screen's width and take the first free place clear of the badge, the panels, the bar, the player and the buttons;
- notice signs draw a little smaller and without name tags, and never over a panel or a button: they stand clear of the player too, and only cover the player when no other place on screen is free.
Every button and panel has its own space and everything stays inside the screen's edges. Landscape phones, tablets and desktops lay out exactly as before. Checked at 844 x 390 and 390 x 844 (phone), 1180 x 820 and 820 x 1180 (tablet) and 1920 x 1080. Act is always there, dim when there is nothing to act on. The kit reads the engine's control rects from `ui.safeArea().controls`, and it states its own column there too (owner `disguiseKitTouch`, via `ui.setControlRegions`), so a level's HUD can keep clear of both. On touch, the act prompt sits in the free band along the top of the screen (right of the badge and objectives, left of the engine's Menu), so it never covers a wardrobe's own interactKit prompt and its "Hold to use" line in the middle of the screen.
The kit's own props (wardrobes and work spots, with everything under them) and the local player's body with whatever it carries (a sack on the shoulder, a tray, a blade) go on the local orbit camera's `cameraIgnore` list, so a washing line, a sack pile or the load you carry no longer pulls the camera into the player's head. A level can add its own see-through colliders (Dockhands adds the island's palm trunks); the kit keeps whatever is already on the list.
## Multiplayer
- Each peer spawns one synced `Wearer` for its own player and is its owner; other peers and late joiners receive it and dress that player's body from it (bodies are local: same outfit, look and seed on every peer). The host removes Wearers of players who left.
- Each player is judged on their own machine, so two players in different disguises are judged by their own clothes and behaviour; meters and signs are per player.
- Cover is a synced field; every peer hides covered players from its aiKit guards, so it is right on whichever peer runs the guards.
- Who belongs where and which rules are on live on one synced `SharedRules` record ("Disguise Rules") that the host spawns and owns. `DK.setAreaAllow`, `DK.tuneArea`, `DK.setRule` and an Area's `allow` edited during play all write it (a player who is not the host sends the change to the host), and every player, late joiners included, judges against it. Checked with two players: opening the warehouse to fishers on the host reached a player who joined afterwards, and closing it from that player reached the host.
- Wardrobes are synced entities (uses are counted by their owner); the Areas, Watchers and work spots themselves are scene content every peer loads from the same scene.
- A player who joins late is kept out of the floor. The engine puts a joining player where another player stands (engine issue #26431), often before the joining machine has built the ground there (a deck, a pier or a yard a scene script or a kit makes as it loads), so the newcomer would drop through it. From the moment this peer's player appears until it has stood on solid ground, clear of everyone, for 3 seconds (at most 60), the kit watches for a body inside another player, or stuck 1 to 4 m under a floor it stood on a moment before, and sets the player down on solid ground beside the others, never through a wall or a rail. A ceiling or a roof over a player set down indoors is never taken for that floor. While the floor is not solid on the newcomer's machine yet, the newcomer is held at the other player's floor height, about a metre in front of them, with gravity off, and is not counted as climbing while held; a newcomer with no ground at all under them yet is held where they appeared until there is. `require("disguiseKit.runtime").arrival.trace` lists its latest decisions; the event `arrivalFixed` fires on each set-down.
## Events (this peer's player)
`DK.on(name, fn)`: `dressed`, `noticing`, `suspicious`, `recognised`, `blown`, `coverRegained`, `caught` (the kit shows "*name* caught you!" on the message line first; a handler that posts its own message replaces it) (a watcher reached you after you were called out), `areaChanged`, `blended`, `unblended`, `workStarted`, `workStopped` (`delivered = true` at a drop-off), `reported`, `changing`. A `blown` event's `reason` is the first thing the watcher saw wrong, as `DK.meters()` words it (`"doesn't belong here"`, `"doesn't know your face"`...), or nil; the toast the player sees is a whole sentence, such as "Foreman Oka sees through your disguise!" or "Door Guard A calls you out: you have a blade out!" (`require("disguiseKit.runtime").shoutText(name, reason)`).
## API reference (`local DK = require("disguiseKit.api")`)
| call | what it does |
|---|---|
| `DK.setup(opts?)` | a Disguises component on a new entity; opts are its fields |
| `DK.area(pos, kind?, opts?)` | an Area (`size` {x,y,z} or {w,h,d}, `radius`, `allow`, `label`, `priority`, `yaw`) |
| `DK.watcher(entity, kind?, opts?)` | make an entity a Watcher |
| `DK.wardrobe(pos, kind?, role, opts?)` | a synced wardrobe with its interactKit prompt (`variant`, `uses`, `yaw`) |
| `DK.workSpot(pos, kind, opts?)` | a WorkSpot (`cargo`, `roles`, `label`, `yaw`) |
| `DK.setClothes(entity, role?, variant?)` | whose clothes a body wears, for taking them |
| `DK.dress(role, variant?)` | dress this peer's player now |
| `DK.status()` | `role, variant, cover, area, areaLabel, belongs, behaviours, blended, inGroup, working, cargo, blade, sneak, heat, watchers` |
| `DK.meters()` | this player's meter on every watcher: `level, state, sees, distance, reasons` |
| `DK.wearers()` | every player's clothes (any peer) |
| `DK.reset()` | clear meters and restore cover (a level restart) |
| `DK.areaAt(pos)`, `DK.belongs(role, pos)` | the ground at a point |
| `DK.setAreaAllow(area, allow)`, `DK.areaAllow(area)` | who belongs in one area, for every player (area = its entity or name) |
| `DK.tuneArea(kind, list?)` | who belongs in every area of a kind, for every player |
| `DK.setRule(role, rule, on?)`, `DK.ruleOn(role, rule)` | switch a suspicious behaviour per role (`"*"` = all), for every player |
| `DK.sharedRules()` | the shared overrides: `{ areas, kinds, rules }` |
| `DK.tuneRule`, `DK.tuneWatcher`, `DK.defineRole`, `DK.defineWatcher` | tune weights and watcher numbers or add roles and watcher kinds, on the calling peer (call them from code every peer runs) |
| `DK.setSignStyle`, `DK.signStyle`, `DK.signSvg(style, level, state?, t?)` (markup, width, height; `t` in seconds plays the sign's motion) | signs |
| `DK.hudKeepClear(owner, rects)`, `DK.hideSigns(owner, hidden?)` | rects (`{ x, y, width, height }` in `ui.screenSize()` points) the signs keep clear of, and hiding the signs while a result screen shows, on this peer |
| `DK.badgeRect() -> { x, y, w, h }?` | where this peer's badge stood on the last frame (nil while hidden), so a level can lay its own panel out under it instead of where the badge would have to step out of its way |
| `DK.configure(opts)`, `DK.settings()` | any setting, on this peer |
| `DK.roles()`, `DK.role(id)`, `DK.areas()`, `DK.rules()`, `DK.watcherKinds()`, `DK.signStyles()` | the catalogue |
| `DK.on(name, fn)`, `DK.eventCounts()` | events |
| `R.beginTrial(entity, wearerFields)`, `R.trialPlace(pos)`, `R.trialFrame(dt)`, `R.endTrial()` (`require("disguiseKit.runtime")`) | run the real judging for a stand-in player in any mode, for tests and tools |
## Guides
- **How to add disguises to my stealth game** (`disguiseKit.package/how-to-add-disguises-to-my-stealth-game`)
- **Build a disguise level like Dockhands from an empty world** (`disguiseKit.package/build-a-disguise-level-like-dockhands-from-an-empty-world`)
Open one with `zero guides read <path>`, the `guides` tool or the Docs panel.
## Tests
`disguiseKitTests` (in the package) holds 26 tests, and the ones that matter most exercise play itself: they run the kit's own per-frame judging (`R.beginTrial` / `R.trialFrame` / `R.endTrial` in `disguiseKit.runtime`) against a stand-in player.
- **Judging**: the right clothes in the right place pass a guard 6 m off; the wrong clothes are seen trespassing, the meter climbs and a full meter blows your cover; a drawn blade is noticed in the right clothes; a player behind the guard or past his range is not seen; a foreman lets his porters pass at 6 m and 4.5 m, sees through them at 3 m, and never sees through a soldier.
- **Blending**: a monk among three townsfolkKit porters goes unnoticed by a guard 8 m off, is noticed once he steps out of the crowd, and is noticed inside it with a drawn blade; a cook working a spot that takes cooks blends on ground cooks do not belong on, a spot for porters only does not hide him.
- **Multiplayer**: another player's synced `Wearer` dresses their body on this peer, the body follows each change of clothes, a peer that starts from nothing (a late joiner) builds the current clothes, and the body goes when the player does; a `SharedRules` record as it arrives from the host decides who belongs, and a change another peer sends is written into it by its owner. A suite runs in one engine, so these check this peer's side of the sync; the two-machine run (a second client joining late, rules changed from both sides) was done by hand.
- **Screen layout**: at a phone held sideways (844 x 390) and upright (390 x 844), a tablet both ways (1180 x 820, 820 x 1180) and a desktop window (1280 x 720), six watchers' signs placed among the badge, the objectives, the message line, the hint line, the XP bar and the touch buttons never cover any of them or each other.
- **Data and rules**: areas named by the label players see (any case) or their entity name, the catalogue (10 roles with two or more looks, 6 area kinds, 7 rules, 6 watcher kinds, 6 sign styles drawing every state), who an Area admits, the shared-rule calls, errors naming what is known, and box, round and overlapping areas.
Run it in edit mode:
```lua
tools.use("tests", "run", { suite = "disguiseKitTests" })
```
## Workflow
`add-disguises-to-a-level` walks a person or an agent through adding disguises to a level they already have, one phase at a time: switch the kit on, mark the areas and who belongs, place watchers (one who sees through a role), wardrobes and work spots, pick a sign style, play to check that the wrong clothes are noticed and the right ones are not, and run the test suite. Start it with `zero workflow start --name add-disguises-to-a-level` (optional args `level`, `theme`, `startRole`, `signStyle`).
## What it costs
Measured in Dockhands on the desktop engine (2026-11-15), with the profiler's per-component script times:
| | per frame |
|---|---|
| the whole kit with Dockhands' 5 watchers (judging, every player's and NPC's body, the HUD) | about 1.9 to 3.8 ms, depending on how much is on screen |
| each extra watcher, all of them looking at the player | about 0.034 ms (20 more watchers: 3.81 ms to 4.51 ms) |
| a body change (a quick change, a new player) | one spike of up to about 80 ms on the frame the new body is built, hidden under the change's bow |
Line-of-sight rays are cached per watcher for 0.15 s, the HUD redraws 30 times a second, and bodies drop detail beyond 25 m and 55 m from the camera. Each frame reads the camera and concealKit's body list once for all bodies, and it checks the avatar mesh a body hides once a second, not every frame. A sign's drawing steps a dozen times a second and with the meter in 1/24 steps, so a sign that has not changed rebuilds the same markup. Most of a Dockhands frame is the engine drawing the island and the ocean, not the kit.
### In a web browser
Played in a real browser tab on a normal machine (2026-11-15, disguiseKit 1.0.9): about **15 frames a second at the pier with the porter crowd** (about 67 ms a frame, with spikes) and about **20 at the beach spawn**. Profiling showed that most of that was not the kit but the island's ocean: tropicalKit made it at the engine's `high` tier, a 276,664-vertex surface sent to the renderer again every frame (about 10 ms of CPU even with nothing moving). Dockhands now makes its ocean at `medium` (9,089 vertices; it looks the same from the pier). In the desktop engine that took a frame at the pier from 58.6 ms to 22.0 ms and at the beach from 51.1 ms to 29.6 ms, measured with other clients sharing the machine.
The browser has **not been re-measured since that change**, so this README does not claim 30 frames a second there. Taking those 10 ms off the measured browser frame gives an estimate of about 50 to 55 ms (18 to 20 frames a second) at the pier, and more if the browser's script costs shrank by the same share as the desktop's. The kit's own share is 1 to 3 ms of the frame. If you build your own level on tropicalKit, pick a lighter ocean for the browser (tropicalKit 1.2.1 has an `oceanQuality` setting for this; its `auto` default already picks `medium` in the browser).
## Built on
townsfolkKit 1.1.0 and humanBodyKit 1.1.0 (Living Lanes), aiKit (guards' senses), concealKit (hiding, knock-outs, bodies), interactKit (prompts). Nothing in them is copied here.
## Version history
- **1.0.43**: no behaviour change. Built on townsfolkKit 1.2.7, which moved its own interactKit from 1.6.3 to 1.6.7. Until then a world installing disguiseKit (or stealthKit, which builds on it) got interactKit at two commits on one path, and the install dropped the files that differ between them (package.yaml, README, api, hud, prompts, gallery scene), so interactKit failed to load. Every kit in the closure now pins interactKit 1.6.7. Also humanBodyKit 1.2.2, concealKit 1.2.9, aiKit 1.3.20, controlsKit 1.4.7 and the current @builtin, so no engine module it places is older than what a world on the current engine holds.
- **1.0.42**: no behaviour change. Built against the current releases: interactKit 1.6.7 (the release this world holds; 1.0.41 recorded an older interactKit commit, so a world that also had concealKit's interactKit got two interactKit copies and a fresh install could land one without package.yaml or api), controlsKit 1.4.7 (1.0.41 pinned a second controlsKit at 1.4.3, and two controlsKit copies in one world fight over the keys), concealKit 1.2.9, aiKit 1.3.20, navKit 1.5.7 (built on the current engine, so no partial engine-module copies) and @builtin 1279747.
- **1.0.41**: `DK.signSvg(style, level, state?, t?)` takes an optional time in seconds that plays the sign's own motion, and returns the drawing's width and height. Three-argument calls draw exactly as before. Asked for by stealthKit, whose notice meters offer every disguiseKit sign as a meter look and animate it.
- **1.0.40**: Dockhands runs concealKit 1.2.7, released from Out of Sight's main line. 1.2.6 fixed guards walking past a body that was woken and knocked out again (a guard now forgets a body once it stands up, so the next knock-out is a new find); 1.2.7 changed documentation only. No disguiseKit changes beyond the version.
- **1.0.39**: Dockhands runs concealKit 1.2.5, released from Out of Sight's main line. Its thick-bush hiding spot uses a new model (`art/shrub.bundle` replaces `art/bush.bundle`; `Media.MODELS.bush` resolves the new one) and its docs are updated; no API change. Dockhands places no thick bush, so nothing in the level looks different. The reuse review names concealKit 1.2.5. The kit's `C.VERSION` says 1.0.39 to match package.yaml; no other change to the kit's own code.
- **1.0.38**: Dockhands runs concealKit 1.2.4, released from Out of Sight's main line. It is documentation only: the camp guide's little game now also ends with CAUGHT when a guard sees you in the open, not only when one drags you out of a hiding spot. The reuse review names concealKit 1.2.4. The kit's `C.VERSION` (in `core.module`, shown as `DK.VERSION`) still said 1.0.33; it now says 1.0.38, so the code, the README and package.yaml agree. No other change to the kit's own code, nor to concealKit's.
- **1.0.37**: Dockhands runs concealKit 1.2.3, released from Out of Sight's main line. It is documentation only: the camp guide lays a grass field under the whole level (a new world's starter ground ends at z = 25) and says to come up to the fallen log from its long side to stash a body. The reuse review names concealKit 1.2.3. No change to the kit's own code, nor to concealKit's.
- **1.0.36**: Dockhands runs concealKit 1.2.2, released from Out of Sight's main line: a new `hideDozer` guard preset (not used here), `Hide.alarms.level(nil)` returns nil instead of erroring, and concealKit's docs now set aiKit's `quietSpeed` to 3 so walking is quiet and running is heard (Dockhands keeps its own setting). The reuse review names concealKit 1.2.2. No change to the kit's own code.
- **1.0.35** (1.0.34 is the same without this entry): Dockhands runs concealKit 1.2.1, released from Out of Sight's main line (it ran 1.1.7 from a side line): every hiding and carrying action on keyboard, gamepad and touch, thrown bodies fly, carried and dragged bodies are held at the shoulder and the hands. The world is on @builtin 33551d3 and the reuse review names concealKit 1.2.1. No change to the kit's own code.
- **1.0.33**: a richer, steadier kit. A notice sign stays close to its own watcher: never further from the head than 30% of the screen's shorter side (180 points at most), so on a phone it no longer steps round the HUD to the far edge; a sign with no free spot within reach shrinks and, failing that, waits a frame. saveKit's "Saved" flash is kept clear like the rest of the HUD (saveKit 1.3.18 states it). Every role has three looks (new: soldier red, monk ochre, tea servant plum, merchant saffron, entertainer scarlet, cook ochre, fisher rust), two new wardrobes (`coatStand`, `tailorsTable`) and two new sign styles (`hanko`, `radar`), all swapping the same way as the others. A catch shows "*name* caught you!" on the message line even in a level that adds nothing for it. Dockhands' door guards face across the doorway, as the guide's do, so stepping into the warehouse is watched. The Dockhands guide is rewritten where its first builder stumbled: which way `yaw` points and how wide a guard sees, the ledger component made and added by its full name in order, telling the player on the message line, and what happens when a friend joins. Dockhands' camera trick that hides small props in the way of the view is its own package now, **viewClear**. Built against interactKit 1.6.7 and saveKit 1.3.18, both released from their own worlds, and the engine library b45137c.
- **1.0.32**: review fixes on top of 1.0.28 to 1.0.31 (pull request #11). The arrival safeguard only lifts a body through a floor it stood on a moment before, so a late joiner set down beside a player indoors is no longer lifted onto the ceiling or the roof of a room 1 to 4 m high; and a newcomer held at deck height is no longer counted as climbing (it was, after 0.3 s of the hold, so the guards could start to notice a player who had only just joined). The Dockhands guide says the door guards' signs close as you step through the doorway into the warehouse (the doorway itself is Dock Yard, where a fisher belongs), and step 7 reads in order again. Checked in Dockhands: one step inside the door a fisher was called out by guards facing across the doorway in 4.6 s and never noticed by guards at yaw 90; the step 7 Ledger posted both of its messages on a real catch and at the desk; two players, the first on the pier deck, as *Known limits* describes. 26/26 tests pass.
- **1.0.31**: a player who joins late never sees the inside of a deck. While the floor where the engine put them is not solid on their machine yet (their copy of the level is still building), the newcomer is held at the other player's floor height, 0.9 m in front of them, with gravity off, and set down on the floor beside them once it is solid; a newcomer with no ground at all under them yet is held where they appeared until there is. 1.0.30 let them sink under the deck until the floor appeared. The spot search no longer counts the newcomer's own body as an obstacle, and `runtime.arrival.trace` notes every 5 s while a hold lasts. Checked with two clients, the first player standing still on the pier: lowest point 1.36 m (the deck), set down 0.9 m beside them at 49 s, settled at 53 s; the first player alone is never moved. 26/26 tests pass.
- **1.0.30**: a player who joins late is kept out of the floor in every level, not only in Dockhands. The engine puts a joining player where another player stands (engine issue #26431), often before the joining machine has built the ground there; in a level built from the Dockhands guide the newcomer sank under the pier and kept falling under it for good. The runtime now watches this peer's player from the moment it appears until it has stood on solid ground, clear of everyone, for 3 seconds (at most 60): a body inside another player, or stuck 1 to 4 m under the floor above it, waits until that floor is solid on this machine and is set down on it beside the others, never through a wall or a rail (`runtime.arrival.trace`, event `arrivalFixed`). Checked with two clients, the first player standing on the pier: set down on the deck 0.9 m beside them 11.4 s after joining, once the joining machine had built the pier. The *Known limits* entry no longer says joining while nobody stands on the spawn point avoids the problem (it does not). 26/26 tests pass.
- **1.0.29**: guide fix only, no behaviour change. The Dockhands guide (step 7) adds the Ledger component by its registered name, `scenes.main.Ledger`: the bare `"Ledger"` ran in play, but `zm push` refused the world because that reference resolves to no asset it holds.
- **1.0.28**: guide fixes only, no behaviour change. In the Dockhands guide (step 5) the two door guards face each other across the doorway (yaw 180 and 0) instead of out of it (yaw 90): a `hideSentry` sweeps about 50 degrees either side of its yaw, so facing out neither sweep reached the doorway and a fisher standing in it was never seen, where the guide says their signs close. Step 7 shows the win and the catch on the kit's message line and hides the signs on a win, instead of a `print` the player never sees.
- **1.0.27**: no behaviour change. The reuse review now rates every installed package, the ones other kits pulled in included, at the version this release runs (saveKit 1.3.17 and interactKit 1.6.6 are this world's copies with their changes sent upstream as open pull requests), and the world moved to the engine library a85225d.
- **1.0.26**: nothing on screen covers anything else during a call-out, the touch buttons included, at every size. A stricter check (every panel, sign, message and button against every other, each frame from the call-out to six seconds after) found what the sign-only check missed, and each is fixed: the message line finds a free row around the badge on every screen (on a phone held sideways it ran over the badge's right edge); signs, the message line and the hint line keep off interactKit's prompts the frame they appear; the HUD redraws at once when a prompt, message or cover changes instead of at its next tick; a level panel laid out under the badge has its whole column kept clear while the badge grows its CALLED OUT line; and the badge only steps aside for things at the very top edge of the screen, so it and the panel under it no longer chase each other down the screen. In Dockhands the level runs after the kit each frame, and its "thrown off the dock" message goes through the kit's message line on every screen (the red box covered the objectives on a tablet). Checked by being called out for real twice at each of 844 x 390, 390 x 844, 1180 x 820, 820 x 1180 and a 1920 x 1080 desktop window: no overlap in any measured frame.
- **1.0.25**: a notice sign never covers anything else on screen, at any size. On a phone held sideways (844 x 390), a call-out by several watchers at once could settle a shared row of signs on the objectives panel or the Sneak / Blade / Act buttons, because only a phone held upright split a crowded row; now every screen does, a sign with no free place left drops its tag and shrinks, and one that still finds none is not drawn rather than drawn over a panel. Leader lines no longer cross panels or controls. The placement is `require("disguiseKit.hud").placeSigns`, and a new test checks it at five screen sizes. The badge carries the widget id `dkBadge`. Checked by being called out for real twice at each of 844 x 390, 390 x 844, 1180 x 820, 820 x 1180 and 1280 x 720: no sign on a panel, a control or another sign in any frame. The late-joiner limit now says what a second player joining beside a player on the pier sees.
- **1.0.24**: a phone held upright, called out by several watchers at once, keeps everything readable: the badge no longer grows under the Menu button and pushes everything down; the hint line wraps inside the screen (it ran off the left edge and under Menu as one long line; a label's wrap is a prop, which the kit's text helper had put in the style, so nothing wrapped); notice signs no longer settle on the level's objectives panel; and the player's hat and coat stay in view, because the kit states the player's place in the picture and saveKit's XP bar steps above it. Notice signs anchor through `ui.fromViewport`, as the engine's screen-coordinates guide says. The hint line and the message line carry widget ids `dkHint` and `dkToast`. In Dockhands: on a phone held upright the level's own red message ("thrown off the dock") goes through the kit's message line instead of sitting on the objectives. Landscape phones, tablets and desktops measure exactly as before.
- **1.0.23**: on a phone held upright nothing overlaps and nothing runs off screen. Built on saveKit 1.3.16 (released from Save Point for this): its XP bar used to run off the right edge and sit on the engine's Jump button and the kit's Act button; it now narrows to the screen and steps up above the touch buttons. The kit's hint line, which only looked in the bottom half of the screen and so vanished once the bar moved up, now looks higher when the bottom half is full and sits just above the bar. Landscape phones, tablets and desktops are unchanged (measured: same positions and sizes).
- **1.0.22**: built against the engine library @builtin 087ed85 (a world on an older one is hidden from players). The reuse review no longer names a library version that goes stale with every engine release. No behaviour change from 1.0.21.
- **1.0.21**: a work spot redraws its mat in edit mode too, so a level that turns `showMark` off (as `DK.workSpot` sets it after the add) no longer keeps the mark in the editor and in the saved scene. The Dockhands guide moves the starter scene's player template onto the beach with its spawn: a new player's body is made where the template stands and moved to the spawn a moment later, so a template left at the origin showed as a grey figure by the pier for the first moments of play. In Dockhands: the same template fix, and the sack pile on the pier is a pallet of the grain sacks the warehouse stacks hold instead of plain blocks on a mat.
- **1.0.20**: built against the engine library @builtin 6683159 (a world on an older one is hidden from players); the reuse review names it. No behaviour change from 1.0.19; tests 25/25 on it.
- **1.0.19**: the key hint line shows on phones and tablets, held either way: on touch it names the Sneak, Blade and Act buttons (it used to be switched off), and on every screen it finds the lowest free row clear of the badge, a level's panel, the XP bar and the touch controls instead of standing at a fixed spot that the touch buttons covered. Desktop is unchanged. A late joiner who lands inside another player is a known engine problem (see *Known limits*); the 1.0.18 note below promised more than Dockhands can do about it.
- **1.0.18**: on a small phone screen (844 x 390) the badge, a level's panel, the level-up banner and the kit's messages all read at once. A HUD piece that finds no free place below whatever is in its way stays where it was asked to stand instead of sliding to the bottom under the XP bar (the badge did, the whole game); the top-centre message steps down out from under a level-up banner; new `DK.badgeRect()` so a level can lay its own panel under the badge. In Dockhands: the phone objectives sit under the badge and no longer step under the banner (which had pushed them off the bottom of the screen); a player who arrives inside another one anywhere is moved apart, never through a rail, and a body that sank a short way under the pier or the deck is lifted back on top (this does not cover every late join: see *Known limits*); and the guards' and the foreman's bodies fade when they pass right in front of the camera, as the townsfolk already did.
- **1.0.17**: notice signs stay clear of saveKit's level-up banner (with saveKit 1.3.15, which states the banner's rect while it shows): a sign whose nearest step was taken now tries the spots beside every obstacle instead of settling on the banner. A watcher who calls you out walks to a spot 1.2 m short of you on his side (so do the guards he alerts), not onto you. In Dockhands: the objectives panel states its rect so the banner narrows beside it and every objective stays readable; the camera sits comfortably inside the warehouse; the sack stacks are real piles of grain sacks; unseen rails keep players on the pier, gangway and yard deck; and a friend who joins late is stood on solid ground. saveKit 1.3.15 and engine library brought up to date.
- **1.0.16**: the how-to guide and the Dockhands guide say in plain words that they cover guards that see through a disguise (the foreman, the captain, the abbot), so a search for that finds them. Engine library brought up to date.
- **1.0.15**: a notice sign pushed far from its watcher (round a toast or a panel) no longer draws a leader line across half the screen: leaders longer than 180 UI points are left out, and the sign keeps its name tag. In Dockhands: the player walks the dunes between the beach and the yard without stalling (the level gives its player's controller a 55 degree slope limit and a 0.45 m step), the island's signpost labels lie flat on their boards, and guards and porters steer round the player (navKit 1.5.1). On keyboard and gamepad the washing line shows one prompt, interactKit's own, instead of two naming different buttons (touch keeps the kit's Act prompt). Also in Dockhands: an unseen fill under the yard deck stops the player sinking through the boards, and the gangway barrel reads as wood at night (concealKit 1.1.5).
- **1.0.14**: the quick start (and the how-to guide's "Put people on watch" step) adds the NavMap the guards walk on. A fresh-world install test found that without it the foreman called you out and then stood still, where the README promised a chase. The world's own `main` scene matches.
- **1.0.13**: the notice signs draw on a screen of their own (`disguiseKitSigns`) at UI layer 920 (new Disguises field `signLayer`), so they always show over HUD chrome such as saveKit's XP bar and level-up banner (layer 900) and under modal panels; that screen takes no clicks. The badge and the key hint line step clear of every rect in `ui.safeArea().controls` and every `DK.hudKeepClear` panel. Sign widgets carry ids `dkSign1`, `dkSign2`, ... so a game can read where they are. Built on saveKit 1.3.14, which now states where its XP bar is. New setting `catchGrace` (1.5 s): nobody catches you in the same instant you are called out. Wardrobe prompts read "Hold to change into ...". On touch, the Act button lets go once an action finishes, so a wardrobe no longer starts by itself after you picked up a sack. In Dockhands: the warehouse crates are sack stacks, and nobody can slip under the yard deck or the gangway any more.
- **1.0.12**: notice signs that would overlap share one row ordered by their watchers' screen position, so a leader line never crosses another sign; rows stay inside the screen (nothing cut off at the top) and keep clear of the badge, prompts, toasts, on-screen controls and any panel a level names. New `DK.hideSigns(owner, hidden)` and `DK.hudKeepClear(owner, rects)` (Dockhands hides the signs on its win screen and keeps them off its objectives). Built on the published tropicalKit 1.2.1 and tropicalProps 1.0.4 (the ocean, hill-edge and pier-side fixes, released from Turquoise Cay), with no local edits to either. In Dockhands: intro and win text wraps inside its panels; the camera keeps the player in view in tight corners and against crates and rocks; the yard rail has an opening where the porters' gangway lands.
- **1.0.11**: built against the engine library @builtin e7497a7 (a world on an older one is hidden from players); the reuse review names it. No behaviour change from 1.0.10.
- **1.0.10**: a watcher's shout reads as a sentence (it said "Foreman Oka sees you doesn't know your face!"); `DK.wearers()` skips a remote player's record that is despawned while it is read instead of failing its caller (a late joiner hit this). The player's own body and whatever they carry no longer pull the camera in; on touch the Act prompt moves to the free band at the top so it never covers interactKit's "Hold to use" (interactKit 1.6.5 gives that line a dark chip). Browser speed written down as measured (see *In a web browser*). 25 tests.
- **1.0.9**: hold Act (F, pad RB, the touch Act button) at a laundry line, clothes chest or robe rack to change, the same quick change as its E prompt, so a phone player never needs the Interact button. Notice signs sit just over the head at a readable size at any distance, stack instead of overlapping, and the ink-brush sign has a dark rim for contrast on sand and sky. Touch buttons stand in their own column sized to the screen and report where they are, and tapping a button's word works as well as its ring. The camera ignores the kit's own props (no more diving into your head at the washing line). Bodies read the camera and concealKit once a frame, and signs redraw only when they change.
- **1.0.8**: an area can be named the way players see it: `DK.setAreaAllow("Salt Warehouse", ...)` and `DK.areaAllow("Salt Warehouse")` take the Area's label (any case, extra spaces ignored) as well as its entity name. A name no Area has is now an error listing the areas there are (setAreaAllow used to accept it and change nothing). README examples checked against what runs.
- **1.0.7**: tests that prove the play itself: a player judged by watchers (passed, noticed, called out, seen through within 4 m), blending in a crowd and at a work spot, and another player's clothes and the shared rules on this peer (23 tests, all passing). Working at a work spot that takes your trade now hides you from watchers further off even on ground your clothes do not belong on, as a crowd does (it used to change nothing). New: `R.beginTrial` / `trialPlace` / `trialFrame` / `endTrial` and `core.applyRuleMessage`. Leftover template comments removed from the scene scripts and the workflow, with no long dashes left.
- **1.0.6**: watchers who see through a disguise (foreman, captain, head of house, abbot) do it only within 4 m (it was 6 to 8 m). A crowd hides you from watchers further than the blend range even in clothes that do not belong there; acting out of character or stepping out of the crowd gives you away. Who belongs where and which rules are on are shared by every player through a synced `SharedRules` record (`DK.setAreaAllow`, `DK.areaAllow`, `DK.sharedRules` are new; `DK.tuneArea`, `DK.setRule` and an Area's `allow` edited in play now reach everyone). Touch is recognised from the engine's own device class, so the Sneak / Blade / Act buttons appear on phones and tablets and the keyboard hints do not. The player's own body (and NPCs dressed by the kit) hide while the camera is inside them; body detail now really follows the camera's distance. Laundry-line posts stand on stone footings. New: the `disguiseKitTests` suite and the `add-disguises-to-a-level` workflow.
- **1.0.5**: the HUD redraws 30 times a second instead of every frame (far less garbage per frame).
- **1.0.4**: sneaking while standing still kneels instead of cowering; the quick change bows in the old clothes and swaps at the bottom of the bow under a puff of dust; gamepad RB (act) works; touch buttons stand beside the engine's own column; the badge says "out of place" once.
- **1.0.3**: holding E at a wardrobe changes clothes in a fresh world (the prompt and the Wardrobe now use the same interactKit).
- **1.0.2**: installs in a fresh world (republished against aiKit 27aa838).
- **1.0.1**: first release on ZeroMind.
## Known limits
Each is an open issue on the tracker of this package's world (*Dockhands: Disguises and Social Stealth Kit*, `bca4ed8d-6b96-46b2-9537-553dfeb7834a`); read one with `zero zeromind viewIssue bca4ed8d-6b96-46b2-9537-553dfeb7834a <number>`.
- **Browser speed below 30 frames a second, as last measured.** A real browser tab ran Dockhands at about 15 frames a second at the pier and 20 at the beach (1.0.9). The main cost, the island's ocean, was fixed for 1.0.10 (see *In a web browser*), but the browser has not been measured again. The `oceanQuality` setting it uses is in tropicalKit 1.2.1, published from Turquoise Cay and installed here. Issue #1.
- **Touch tested with simulated input only.** The whole Dockhands level was played start to win with the engine's input simulator in touch mode, not on a physical phone. Issue #2.
- **Townsfolk bodies are not hidden when the camera passes through them.** The kit hides its own bodies (players, Outfit NPCs); townsfolkKit draws the townsfolk. Issue #3.
- **`DK.tuneRule`, `tuneWatcher`, `defineRole` and `defineWatcher` change only the calling peer.** Call them from code every peer runs (a component's `awake`, `build.luau`). Area and rule switches are shared. Issue #4.
- **Shared area overrides are keyed by the Area entity's name.** Give each Area a unique name without `|`, `=` or line breaks. Issue #5.
- **A script that teleports the player reads as running or climbing for a moment.** Call `DK.reset()` right after moving a player by script. Issue #6.
- **`component.add` drops a list in its init table (an engine bug).** Add the component with `{}` and set list fields after it, as Dockhands does for tropicalKit's `keepClear`. Issue #7.
- **A late joiner is put inside another player (engine issue #26431).** The engine places a joining player inside whoever stands where it puts them: on the beach spawn, or (seen in Dockhands) wherever the first player stands on the pier. Before 1.0.30 the two bodies pushed apart downward and the newcomer sank: tested 2026-11-16 at the beach spawn it once dropped 3.5 m under the sand and once fell through the island, and on the pier it sank through the deck into the water and was thrown about, ending on the deck about nine seconds after joining. With 1.0.32, tested 2026-11-16 in Dockhands with the first player standing still on the pier deck and a second player joining, twice: the newcomer was put inside the first player, and its own machine had not built the pier yet, so the kit held it at deck height about a metre in front of them. What the newcomer sees for that time is both players standing in mid-air over the shallows, their shadows on the sand below and no pier drawn on its screen; nothing is suspicious about it (no climbing, no guard's notice rising). Once its machine had built the pier, 54 s after joining both times, the pier appeared, the newcomer was set down on the deck about 1.5 m beside the first player and stayed there, never once lower than the deck. The first player never sank; in the run where its position was tracked it was nudged about 1 m along the pier. How long the hold lasts is how long the joining machine takes to build the ground. Joining while nobody stands on the pier does not avoid the engine problem: at the beach spawn the newcomer was put inside the first player there too, and the kit moved it 0.9 m aside on its first frame.
- Judging is per player on their own machine, which suits co-op; a competitive game would want the host to judge.
- Two engines signed in to one account are one player (engine issue OrigoZero/zero#14448), so a two-player test needs two accounts.
- The crowd blend reads townsfolkKit's people; a world without townsfolk blends only through work spots.
# interactKit
**Version 1.6.7.** Everything a player can walk up to and use, for any Zero game: seven doors, seven switches and levers, key, coloured keycard and combination locks, chests and other containers that hand out loot, a barricade and invisible trigger zones, with "Press E to open" and hold-to-use prompts on keyboard, gamepad and a phone's touch screen. Five prompt styles and six looks (old wood, sci-fi, cartoon, dungeon, neon, royal palace), each picked with one field, sounds for every door, switch, chest and lock, and multiplayer from the ground up: every player sees the same door, lever and chest. Ships with two guides, a how-to and a worked escape room example. To install, search ZeroMind for **interactKit**, or run `zero zeromind installAsset f7af5474-4cb3-48d3-96e6-15f897ccce4f` in the engine shell, then `local Interact = require("~interactKit.api")`.
- **Interactable**: put it on anything. A prompt appears when the player is close enough (`trigger = "proximity"`) or looking at it (`trigger = "look"`) within `range`. `holdTime = 0` is a quick press; above 0 the player holds while a fill-up runs. One interact button everywhere: **E**, the gamepad's **west** face button (X on Xbox, square on PlayStation, Y on Switch), or the on-screen **Interact** button on a phone.
- **TriggerVolume**: an invisible box or sphere that reports `enter`, `exit` and `stay` for every player, and can open, close or toggle what it is wired to.
- **7 doors, 7 switches, 3 locks, 4 containers, a barricade, 5 prompt styles, 6 looks**, listed below.
Everything works the same way: a **`kind`** field picks the variant, a **`look`** field picks the style, **`targets`** wires it to other things by name, and **one field** picks the prompt style. Swapping a sliding door for a portcullis is changing `kind = "sliding"` to `kind = "portcullis"`.
## Install
Search ZeroMind for **interactKit** and install `interactKit.package`, or in the engine shell:
```
zero zeromind installAsset f7af5474-4cb3-48d3-96e6-15f897ccce4f
```
It lands at `/source/interactKit.package` and brings its two dependencies with it, **controlsKit** and **juiceKit** (under `/source/deps/`). Keys, keycards, coins and gems are interactKit's own, so nothing else is needed.
Reach interactKit by its package name, `require("~interactKit.api")`, and its components with `Interact.component("Door")`: both work wherever the package is installed, at the top of `/source` or under `deps/` when another kit depends on it.
## Quick start
A new world's `scenes/main.scene/build.luau` already has a ground and a player. Add these lines at the end of its `content()` function:
```lua
-- ── interactKit quick start ─────────────────────────────────────────
local Interact = require("~interactKit.api")
-- a door in a short wall, and a lever beside it that opens it
Interact.spawn("door.hinged", { 0, 0, 6 }, { name = "FrontDoor", synced = true, yaw = 180,
look = "wood", fields = { wall = 1.5 } })
Interact.spawn("switch.lever", { 2.6, 0, 5 }, { synced = true, yaw = 180, look = "wood",
fields = { targets = { "FrontDoor" } } })
-- a locked chest, and the key that opens it (each player picks up their own)
Interact.spawn("container.chest", { -3, 0, 6 }, { synced = true, yaw = 180, look = "cartoon",
fields = { loot = "coin", lootCount = 8 }, lock = { kind = "key" } })
Interact.spawnKey({ -3, 0, 3.5 })
```
Press **Play**. Walk to the lever on your left and press **E**: the door swings open and you can walk through. The chest on your right says *Locked: Needs a key*; walk over the key, come back, and it says *Unlock*. Press E and coins spill out.
`synced = true` makes each thing one shared object, so every player sees the same door. Without it every player gets their own copy.
**Doors in your own walls.** Build your wall with a gap and put the door in it with a little wall of its own (`wall = 0.8` for a 1.4 m door in a 2.8 m gap). The door's wall pieces tuck into your wall and **take your wall's material and colour by themselves**, as do a portcullis's stone jambs and gatehouse: the door looks just beside its frame for the wall it sits in. Or leave `wall` at 0 and cut the gap to the frame. `wallMaterial` picks the stonework yourself; `matchWalls = false` keeps the look's own stone. More under *Doors* below.
**No code at all:** add `interactKit.Door` (or `Switch`, `Container`, `Barricade`, `TriggerVolume`, `Interactable`, `Lock`) to an entity in the editor and set `kind`, `look` and `targets` in the inspector. A device works on its own; add an Interactable beside it only to change its prompt (range, look-at, hold time, style).
The **gallery** scene (`interactKit.gallery`) has every kind, look and prompt style laid out, labelled and usable.
## Guides
Two guides ship in the package, in `interactKit.package/guides/`, and come with every install:
- `how-to-make-doors-switches-locks-and-chests`: every part of the kit, from a "Press E" prompt to keys in another inventory.
- `example-escape-room-puzzle-with-switches-and-locked-doors`: an empty world to a treasure vault puzzle with inventoryKit and dialogueKit.
Open one in the editor's **Docs** panel (search its name, or what you want to do, such as "lever opens door"), or in the engine shell with `zero guides read <name>` or `man <name>`. To read one before installing: `zm show @f7af5474-4cb3-48d3-96e6-15f897ccce4f:interactKit.package/guides/<name>.guide/guide.md`.
## The family
interactKit is the first kit of a family made to work together: **interactKit**, **inventoryKit** (the bag, items and loot, package `e5580df4-1900-4b90-a890-3f5a30501f2a`), **craftingKit** (stations, recipes and gathering on inventoryKit's items, package `db435e42-06aa-407e-8537-106d444d0a5c`) and **dialogueKit** (characters who talk, package `c4f39ad3-2a14-4f7d-b409-aed7fdbe8e77`), with **questKit** beside them (quests on all four, package `207320c0-8bf2-4175-ba37-fdcf2c915679`). questKit's guides: *How to add quests to my game* (`zm show @915ee882-7aef-4388-803f-cb96a4160fbe:guide.md`) and *Example: a quest chain from an empty world* (the mushroom quest chain, `zm show @f06a2f9d-29a2-41e5-b242-9e21043e5db1:guide.md`). inventoryKit, craftingKit and dialogueKit have no guides yet; their READMEs are the reference.
dialogueKit 1.0.2, craftingKit and questKit install interactKit themselves. dialogueKit 1.0.2 brings its own copy of interactKit 1.3.1 for its Talker's prompt; next to a newer interactKit at the top of a world that copy's prompts do not show, so start conversations from an interactKit Interactable instead, as the escape room example does.
## Styles
### Doors: `interactKit.Door`, `kind =`
| Kind | What it is |
|---|---|
| `hinged` | A single door swinging on side hinges. |
| `double` | Two leaves swinging apart from the middle. |
| `sliding` | A barn or shop door rolling sideways on a rail. |
| `garage` | Slats rolling up into a drum over a wide opening. |
| `portcullis` | An iron grid rising into a stone gatehouse. |
| `bookcase` | A full bookcase that swings away to reveal a passage. |
| `airlock` | Split halves sliding into the walls, with a red / green status light. |
Moving parts carry their colliders: an open door is a doorway you walk through, a closed one is a wall.
**Setting a door into your own walls.** Leave `wall` at 0 (the default) and the door brings only its frame: cut your doorway to the frame (the opening plus about 0.14 m a side for most kinds, 0.5 m a side for the portcullis). Give it `wall` metres to have it fill a wider gap with wall pieces of its own. Either way the door's stonework (its wall pieces, and a portcullis's stone jambs and gatehouse) takes the material and colour of the wall it sits in, found by looking just beside the frame through the wall's collider (`matchWalls`, on by default; it looks a few times while the level loads, and again whenever a wall moves in the editor). `wallMaterial` sets the stonework yourself and wins over the match: `Interact.spawn("door.portcullis", pos, { fields = { wall = 0.8, wallMaterial = myStone } })`. `matchWalls = false` keeps the look's plain stone colour. Things other interactKit objects build are never matched, so doors side by side do not copy each other.
### Switches: `interactKit.Switch`, `kind =`
| Kind | How it works | Tells its targets |
|---|---|---|
| `lever` | Press to throw on / off. | follow (open while on) |
| `button` | Press; it pops back up. | toggle on every press |
| `plate` | On while any player stands on it. No button. | follow |
| `keypad` | Press, type `code` on the pad. | follow |
| `valve` | Hold to spin the wheel a full turn; hold again to close. | follow |
| `crank` | Hold to wind; let go early and it unwinds. | follow |
| `chain` | Press to pull. | toggle on every pull |
### Locks: `interactKit.Lock`, `kind =`
| Kind | Opens for |
|---|---|
| `key` | The player holding a key (`Interact.spawnKey(pos)`). Drawn as a padlock. |
| `keycard` | The player holding a keycard of the lock's `color`: red, blue, green, yellow, purple or white (`Interact.spawnKey(pos, { kind = "keycard", color = "red" })`). A red card opens red locks and not blue ones. Drawn as a card reader in that colour. |
| `combination` | Whoever dials `code` (digits). Drawn as a dial. |
A Lock sits beside any Door, Container or Switch on the same entity.
### Containers: `interactKit.Container`, `kind =`
`chest` (lid swings up), `crate` (lid pops off), `locker` (door swings open), `barrel` (lid flips). The first open spills `lootCount` items of `loot` on the ground in front: `coin`, `gem`, `key` or `keycard`, with a colour as `gem:red` or `keycard:blue` (older pickupsKit look names such as `fantasy_ruby` are read as the nearest kind). Each piece goes to the first player to walk over it.
### Items: `interactKit.Item`, `kind =`
| Kind | Gives | |
|---|---|---|
| `key` | `keys` | Opens key locks for the player holding it. |
| `keycard` | `keycard_<color>` | Red, blue, green, yellow, purple or white; opens keycard locks of that colour. |
| `coin` | `coins` | What containers spill by default. |
| `gem` | `gems` | A cut gem in any key colour. |
Walk over one to pick it up. `perPlayer` (the default for keys) means every player takes their own copy, and each sees only their own disappear; shared items go to whoever is first. `item` gives a different item name, `amount` more than one, `respawn` brings it back. Every player's counts are kept in interactKit's own inventory, shared by the host, and shown in a small strip in the top-left corner of each player's screen once they carry something.
### Barricade: `interactKit.Barricade`
Hold to nail boards across an opening one at a time; once full, hold to tear them down. It blocks the way while any board is up.
### Prompt styles: `promptStyle =`
| Style | What it looks like |
|---|---|
| `glyph` (default) | The interact button as it looks on the device in hand (E keycap, Xbox X, PlayStation square, Switch Y, generic pad, or a TAP / HOLD badge on a phone) with the action beside it. |
| `ring` | A radial ring around the button that fills while holding. |
| `tooltip` | A small card floating over the object: its name, the button and the action. |
| `dot` | A small dot on every usable thing nearby that grows into the button when focused. |
| `pixel` | A chunky pixel-art box with a pixel glyph and a segmented hold bar. |
**The whole world, one field:** put `interactKit.InteractSettings` on any one entity and set its `promptStyle` (from code: `Interact.setPromptStyle("ring")`). **One object, one field:** `promptStyle` on its Interactable; `default` follows the world setting. Both apply at once, also while playing.
### Looks: `look =`
| Look | What it looks like |
|---|---|
| `wood` | Old wood and iron: dark planks, black straps, brass fittings. |
| `scifi` | Sci-fi metal: brushed steel panels with glowing cyan trim. |
| `cartoon` | Chunky bright plastic in candy colours. |
| `dungeon` | Dungeon stone and rust: weathered grey oak, rough stone frames, rusted iron, torch-orange lights. |
| `neon` | Neon: gloss black panels edged with hot magenta and cyan light. |
| `royal` | Royal palace: ivory panels, white marble and polished gold. |
Every door, switch, lock badge, container, item and the barricade comes in all six. A look belongs to each object; changing it rebuilds that object in place, also while playing.
## Wiring without code
Every Switch, Door, Container, Barricade, TriggerVolume and plain Interactable has `targets`: a list of entity names (or ids). What they are told:
| Source | Sends |
|---|---|
| Lever, plate, keypad, valve, crank | `follow` (open while on, close while off). Set `action` to `invert`, `toggle`, `open`, `close`, `unlock` or `lock` to change it. |
| Button, chain | `toggle` on every press / pull |
| TriggerVolume | `enterAction` when the first player enters, `exitAction` when the last leaves (`once` = only the first time) |
| Door, Container | `follow`: opens its targets with it |
| Barricade | `close` when the first board goes up, `open` when the last comes down |
| Interactable | its `action` when used |
Doors and containers take `open`, `close`, `toggle`; switches take `on` / `open`, `off` / `close`, `toggle`; anything with a Lock takes `unlock` and `lock`. `playerOperable = false` on a door means only wiring moves it (a portcullis behind a crank).
## API
`local Interact = require("~interactKit.api")` is the stable public surface, together with the components below. The other modules in the package are internal.
### Constants
| Name | Value |
|---|---|
| `Interact.VERSION` | `"1.6.7"` (matches `package.yaml` and this README) |
| `Interact.PROMPT_STYLES` | `{ "glyph", "ring", "tooltip", "dot", "pixel" }` |
| `Interact.LOOKS` | `{ "wood", "scifi", "cartoon", "dungeon", "neon", "royal" }` |
| `Interact.SOUNDS` | `{ "doorWood", "doorHeavy", "doorSlide", "lever", "button", "chest", "unlock", "locked", "collect", "hammer" }` |
| `Interact.ACTIONS` | `{ "toggle", "open", "close", "follow", "invert", "unlock", "lock" }` |
### Building
| Call | Does |
|---|---|
| `spawn(id, pos, opts?) -> entity` | Spawns any catalog kind (`"door.airlock"`, `"switch.valve"`, `"container.chest"`, `"barricade.boards"`, `"core.trigger"`...). `opts`: `name`, `synced` (true for shared state), `yaw` (degrees), `look`, `fields` (the component's fields), `lock` (Lock fields, adds a Lock), `interact` (Interactable fields, or `false` for none). Errors on an unknown id. |
| `spawnKey(pos, opts?) -> entity` | A key or keycard players pick up by walking over it (an `interactKit.Item`), counted per player. `opts`: `kind` (`"key"` / `"keycard"`), `color` (keycards), `look` (`wood`, `scifi`, `cartoon`), `perPlayer` (default true: every player picks up their own), `respawn`, `respawnTime`, `name`, `synced` (default true). Same as `spawn("item.key", pos, ...)`. |
| `catalog(filter?) -> { entry }` | Every kind: `{ id, family, kind, name, component, description, tags, looks, hold, wireable }`. Filters combine: `{ family = "door", tag = "scifi", look = "cartoon", hold = true, component = "Switch" }`. Copies. |
| `kinds(family) -> { string }` | The kinds of `"door"`, `"switch"`, `"lock"`, `"container"`, `"barricade"`, `"prompt"` or `"core"`. |
| `tags() -> { string }` | Every tag in use, sorted. |
### Using and wiring
| Call | Does |
|---|---|
| `use(target, args?, cb?)` | Uses `target` (entity, id or name) as the local player would. `args`: `code` (keypads, combinations), `expect` (the state you saw), `scripted = true` (skip the reach check, for cutscenes and scripts). `cb(ok, reason)` gets the owner's answer. Errors on an unknown target. |
| `signal(target, action, cb?)` | Sends a wiring action (`open`, `close`, `toggle`, `on`, `off`, `unlock`, `lock`) as a switch would. |
| `fire(sourceId, targets, action, on, peer?)` | Sends `action` to every target in the list; `follow` / `invert` become open or close from `on`. Never sends to `sourceId` itself. |
| `idOf(target) -> id?` / `resolve(target) -> id?` | An entity, id or name to an entity id, or nil. |
| `component(name) -> type` | interactKit's component type by short name (`Interactable`, `TriggerVolume`, `Door`, `Switch`, `Lock`, `Container`, `Barricade`, `Item`, `InteractSettings`, `InteractHUD`) for `e.component.add(Interact.component("Door"), { kind = "airlock" })`, `get` and `has`. Errors on an unknown name. |
### Events
| Call | Does |
|---|---|
| `on(target, name, fn) -> unsubscribe` | `fn(ev, entityId)` on every peer. `target` is an entity, id, name, or `"*"` for all. Events: `use`, `open`, `close`, `on`, `off`, `unlock`, `lock`, `denied` (`ev.reason`), `loot`, `board`, `unboard`, `press`, `pull`, `enter`, `exit`, `stay` (`ev.dt`), `holder`, `collect`. `ev.peer` is the player's peer id where there is one. Call the returned function to stop listening (in a scene entrypoint, from `onUnload`). |
| `emit(entityId, name, data?)` | Fires an event on this peer only (for your own devices). |
### Reading state
| Call | Does |
|---|---|
| `statusOf(id, peer) -> table` | What the prompt says for that player: `label`, `hint`, `available`, `state`, `locked`, `busy`, `needsCode`, `codeLength`, `progress`. |
| `settingsOf(id) -> table?` | The merged prompt settings: `label`, `trigger`, `range`, `holdTime`, `promptStyle`, `promptOffset`, `active`, `exclusive`. |
| `usable() -> { id }` | Every usable thing this peer knows. |
| `device(target) -> record?` / `lock(target) -> record?` | The registered device or lock behind an entity. |
### Settings
| Call | Does |
|---|---|
| `setPromptStyle(style)` / `promptStyle()` | The world's prompt style (what `InteractSettings.promptStyle` sets). Errors on an unknown style. |
| `setShowLabels(on)` / `showLabels()` | Action text beside the button. |
| `setEffects(on)` | juiceKit feedback on open / close. |
| `setSoundVolume(v)`, `getSoundVolume()` | Volume of interactKit's own sounds on this peer, 0 to 1 (default 0.8; 0 is silent). |
### Keys, keycards and effects
| Call | Does |
|---|---|
| `count(peer, item) -> number` / `give(peer, item, n) -> boolean` | A player's items: `keys`, `keycard_red`, `coins`, ... in interactKit's inventory (`n` may be negative; never below 0). A give on a peer that does not own the inventory is sent to its owner. |
| `items(peer) -> table` | Everything that player carries: `{ keys = 1, coins = 8 }` (a copy). |
| `keyOf(peer) -> string` | The key a player's counts are kept under (`"p<peer>"`). |
| `setInventory({ count = fn(peer, item), give = fn(peer, item, n), counts = fn(peer)?, onPlayer = bool? } or nil)` | Use your own inventory for locks, items and loot instead of interactKit's; nil goes back. interactKit calls these on the owner of the lock or item, with the player's peer id. With `onPlayer = true`, `give` runs instead on the engine of the player who gets the item, exactly once. |
| `juice()` | juiceKit's Juice module, or nil and why not. |
| `fx(preset, at, opts?)` | Plays a juiceKit preset on this peer only. |
| `sound(name, at, opts?) -> id?` | Plays one of `Interact.SOUNDS` at a world point on this peer only (`opts.volume`); the emitter removes itself. Doors, switches, chests, locks, items and the barricade already play theirs. |
Keys in inventoryKit's bag: inventoryKit lets every engine read every bag but only a player's own engine change it, so `count` reads `Inventory.count(item, peer)`, and `onPlayer = true` makes interactKit run `give` (`Inventory.give(item, n)`) on that player's own engine, once per item. The how-to guide (*Keys in a different inventory*) has the lines, and the escape room example uses them. With pickupsKit installed at the top of your world:
```lua
local Pickups = require("~pickupsKit.api") -- your world's own copy
Interact.setInventory({
count = function(peer, item) return Pickups.get("p" .. peer, item) end,
give = function(peer, item, n) Pickups.add("p" .. peer, item, n) end,
})
```
### Your own devices
Make anything a usable device with the same prompts, networking and locks:
```lua
Interact.registerDevice(entity.id, {
family = "custom", kind = "bell", comp = myComponentPublic,
defaults = { label = "Ring", range = 3 },
status = function(peer) return { label = "Ring the bell" } end,
handle = function(peer, verb, args) -- runs on the owner
if verb == "use" then myComponentPublic.rung += 1; return true end
return false, "unknown verb"
end,
signal = function(action, args) return true end, -- optional: wiring
})
```
`unregisterDevice(id, record)`, `registerInteractable(id, comp)` / `unregisterInteractable(id, comp)`, `registerLock(id, { isLocked, setLocked, describe(peer), tryUnlock(peer, args) })` / `unregisterLock(id, record)`. `ensureHud()` makes sure this peer's prompt HUD exists in play (devices call it for you).
## Components
| Component | Fields (state fields are written by the owner) |
|---|---|
| `Interactable` | `label`, `title`, `trigger` (proximity / look), `range`, `holdTime`, `promptStyle`, `promptOffset`, `active`, `exclusive`, `targets`, `action`; event `used` |
| `TriggerVolume` | `size`, `shape` (box / sphere), `targets`, `enterAction`, `exitAction`, `once`, `showInEditor`; state `count`, `fired`; events `entered`, `exited` |
| `Door` | `kind`, `look`, `width`, `height`, `wall`, `wallMaterial`, `matchWalls`, `speed`, `autoClose`, `playerOperable`, `active`, `targets`; state `open` |
| `Switch` | `kind`, `look`, `targets`, `action`, `code`, `once`, `holdTime`, `active`; state `on`, `progress` |
| `Lock` | `kind`, `color`, `item`, `code`, `consume`, `relock`, `openOnUnlock`, `badge`; state `locked` |
| `Container` | `kind`, `look`, `loot`, `lootCount`, `lootItem`, `refill`, `autoClose`, `active`, `targets`; state `open`, `looted` |
| `Barricade` | `look`, `width`, `height`, `wall`, `maxBoards`, `secondsPerBoard`, `active`, `targets`; state `boards`, `tearing`, `work` |
| `Item` | `kind` (key / keycard / coin / gem), `color`, `look`, `item`, `amount`, `perPlayer`, `respawn`, `respawnTime`, `radius`, `removeWhenTaken`, `active`; state `available`, `taken`; event `collect` (`ev.peer`, `ev.item`, `ev.amount`) |
| `InteractSettings` | `promptStyle` (the whole world's), `showLabels`, `effects`, `soundVolume` |
| `InteractInventory` | Spawned for you in play by the host: every player's counts (`counts`), written by its owner. |
| `InteractHUD` | Spawned for you on each player's machine: prompts, hold fill-ups, messages, code pad. |
Set a state field in the editor for the starting state (a door that starts open, a barricade that starts boarded).
## Multiplayer
- **The owner decides.** Any player may ask; the peer that owns the entity (the host, for scene objects) checks reach, the lock, and that the thing is still in the state the player saw, then writes the shared state. Every player animates from it, so all see the same door, lever, chest or barricade, late joiners included.
- **Two players, one handle.** Requests carry the state the player saw, so two players pulling the same lever at once flip it once. Holds (valve, crank, barricade, `exclusive` hold-to-use) are claimed by one player at a time; the other sees "In use by another player", and a claim lapses when its player goes quiet.
- **Keys belong to the player who picked them up.** The owner checks the count of the player who asked, so a locked door opens for the player holding the key and refuses the one who isn't.
- Effects play on every machine from the shared state change; nothing extra is sent. Channels: `ik:req`, `ik:res`, `ik:evt`.
## Tests
`tools.use("tests", "run", "interactKitTests")` in edit mode (shell: `zero tests run interactKitTests`) runs 97 tests. They cover every public call of `interactKit.api` (one test fails if a public call is added without a test), every kind in every look, kind swaps, wiring and every switch, per-player keys and keycards, items (per player, shared, out of reach, respawning) and the shared inventory, combination locks, loot, the barricade, trigger volumes, hold claims, simultaneous requests and remote players (stand-in bodies whose requests go through the real network handler), prompt styles and the code pad, a label set on a device's prompt and the *Hold to use* hint, gives carried once to the receiving player's engine, a door's stonework wearing the `wallMaterial` it is given or matching the wall it stands in, every look's palette and style, every sound playing once and cleaning up, the gallery's signs showing this version, and that both guides ship, link each other and are named here. Guard tests fail if any code reaches a dependency by folder path, adds a pickupsKit component, or times anything with CPU time, and if a taken item rebuilds or respawns its parts, reappears for the player who took it, or shows again after that player's own repeated grab.
For 1.4.0 the suite was run twice in a row with 86 of 86 passing both times, in this world and in a new world holding only interactKit installed from ZeroMind. In that new world the quick start above was played as written: the lever opens the door, walking over the key counts it, the chest says *Locked*, then *Unlock*, and opens, and the spilled coins are collected. The escape room example guide was followed word for word in another new world, alone and with two players. 1.4.1 changes only text; its suite passed 86 of 86 twice in a row here and in a new world with only 1.4.1 installed, where the quick start was played again.
## Known limits
Each limit here is an open public issue you can look up.
- **#14448**: two copies of the engine signed in to the same account collide as one player. Test two players with two accounts.
- **#21420**: an install with several dependencies is slow. interactKit brings two; a game installing interactKit, inventoryKit and dialogueKit waits about a minute.
- **#20750**: the frame rate of the web build is low on multiplayer worlds, the gallery included.
- **#20946**: the web build of each release is checked by the world's owner; this release was verified in the desktop engine.
- **#19258**: the description ZeroMind shows for the package can lag behind a new release for a while.
## How it behaves
Design choices rather than limits:
- The prompt focuses one thing at a time: looking at something in range beats being nearest to something else.
- Codes are digits only, up to 8.
- Doors swing one way, away from the side they face, and do not push players aside while closing.
- Doors, switches and the rest are built from primitive shapes. Their parts are rebuilt on every machine from `kind` and `look` and never saved into a scene.
- In edit mode things snap to their state; they animate in play.
## Changes
- **1.6.7**: the gallery's two saved version signs say this version again (they had stayed at 1.6.4; the gallery rewrites them from `Interact.VERSION` whenever it loads), so the test that checks them passes. Nothing else changes.
- **1.6.6**: The HUD's `lastFrame()` report also carries `rects`: every top-level panel it placed at a fixed position this frame (the prompts, the message line) as `{ id, x, y, w, h }` in screen points, so a screen that draws later in the same frame can keep clear of a prompt the moment it appears. Nothing else changes.
- **1.6.5**: Prompts read on any background and on a phone. In the glyph style the hold bar and the *Hold to use* line now sit on a dark chip of their own under the pill, with a text shadow, instead of bare light text that washed out over bright sand, snow or whatever stood behind the prompt. On a touch screen the focused prompt slides sideways until it clears every on-screen control the engine or the world states (`ui.safeArea().controls`, which a world adds to with `ui.setControlRegions`), so a button column no longer covers its label. Nothing changes on a desktop screen with no controls stated.
- **1.6.4**: Built against controlsKit 1.3.2, the release menusKit 1.3.19, saveKit 1.3.13, inventoryKit 1.0.27 and navUiKit 1.3.9 ship with, so a world that installs interactKit beside questKit, economyKit or arpgKit holds one controlsKit. The files that name controlsKit are re-derived against it; current engine library. No interactKit code changed.
- **1.6.3**: Built against the current controlsKit (1.3.1) and pickupsKit 2.3.11 with its current SecondWind, juiceKit, MatchFlow and Lifeline, and the current engine library, so a world that installs interactKit beside cropsKit, economyKit or inventoryKit holds one release of each. No interactKit code changed; the suite runs 97 of 97.
- **1.6.2**: Built against controlsKit 1.2.8, the release every package that ships with sideScrollerKit moves to together, so a world installing them holds one controlsKit. Nothing plays differently from 1.6.1.
- **1.6.1**: Built against juiceKit 1.2.10 and controlsKit 1.2.4, so an install no longer carries older copies of them. Nothing plays differently from 1.6.0.
- **1.5.4**: The gallery's two big signs showed 1.5.1, because the gallery loads from its saved scene and that was not saved again when the version changed. Now the signs show this version, the gallery rewrites them from `Interact.VERSION` every time it loads, and a new test fails if the saved signs name any other version. Nothing else changes. 93 tests.
- **1.5.3**: Text only. The README's opening paragraph, which ZeroMind shows as the package's description, now names everything the kit gives you (chests and other containers, trigger zones, prompt styles, the six looks, sounds, multiplayer, the two guides) and how to install it. The gallery scene, the looks module and the Door, Switch, Container and Item descriptions say six looks instead of three; the package description says trigger zones. Nothing plays differently from 1.5.2. 92 tests.
- **1.5.2**: The README's opening list says 6 looks, as the kit has since 1.5.0 (it still said 3). Nothing plays differently from 1.5.1. 92 tests.
- **1.5.1**: Guide fixes from following both guides word for word in a new world with 1.5.0 installed from ZeroMind. The example's `talking` control file now has one control of its own, **Esc** to walk away from the conversation, because a control map with no controls cannot be switched on: with 1.5.0's text the hotbar still moved when 1 to 3 picked an answer. Now it does not, for each player on their own engine. The how-to's *Build a room* calls its walls warm grey, as they look. Nothing in the kit plays differently from 1.5.0. 92 tests.
- **1.5.0**: More looks, doors that fit your walls, sounds. Three new looks, `dungeon` (grey oak, stone frames, rusted iron, torch light), `neon` (gloss black with magenta and cyan light) and `royal` (ivory, marble and gold), for every door, switch, lock, container, item and the barricade, still picked with one `look` field; the gallery's right wing shows all six side by side. A door's stonework now takes the material and colour of the wall it is set into by itself (new Door field `matchWalls`, on by default; `wallMaterial` still wins), so doors in your own walls no longer show grey panels; the README, the how-to and the example say so where you first place a door. Sounds, which the kit had none of: doors (wood, heavy gate, sci-fi slide), levers and buttons, chests, unlocking and a locked rattle, pick-ups and the barricade's hammer, played on each player's own engine (new `Interact.sound`, `Interact.SOUNDS`, `setSoundVolume`, `getSoundVolume` and InteractSettings `soundVolume`). A portcullis or garage door shakes the camera only of players near it, not the whole level. The how-to guide opens with *Build a room, step by step* (walls, a door in them, a lever, a chest that hands out the next door's key, a hold-to-open chest, a bag and a character who talks, each with what you should see); the example guide adds checks after its build steps, and its conversation now holds a `talking` control file so pressing 1 to 3 picks an answer without also moving the hotbar. Gallery: the title shows the version, and the rows of labels no longer crowd each other from the spawn. 92 tests.
- **1.4.5**: The first release of 1.4.3 and 1.4.4 below, contributed by a user of the kit (pull request #2); installs go from 1.4.2 straight to 1.4.5. On top of them: the gallery scene is re-baked so its boards are stored with the linear tints its build now makes (new installs load the baked scene); the README and `package.yaml` name the 90 tests the suite runs; the Door component's README names `wallMaterial`. Nothing plays differently from 1.4.4.
- **1.4.4**: Doors fit into your own walls. New Door field `wallMaterial`: the door's stonework (the `wall` pieces beside the frame, and a portcullis's stone jambs and gatehouse, which it always builds) wears that material instead of the look's plain stone colour, so a door set into a textured stone, brick or plaster wall matches it. The README and both guides now say how to set a door into your own walls (`wall = 0` and a doorway cut to the frame, or `wall` plus `wallMaterial`). One new test (90). Builds on 1.4.3.
- **1.4.3**: The three looks now show the colours their palette names. The palette is written as sRGB hex (as a colour picker shows it) but was handed straight to the Model tint, which takes linear light, so every look rendered washed out: the `wood` chest read as pale cardboard with light grey straps instead of dark planks with black iron straps, and `scifi` and `cartoon` were paler than designed too. `Looks.paint` and `Looks.tint` now convert to linear first (new `Looks.linear(hex)`; `Looks.rgb` still returns the sRGB values), and the gallery boards do the same. Nothing else changes: kinds, fields, wiring and prompts play as in 1.4.2.
- **1.4.2**: Fixes from playing the guides. A `label` set on the Interactable beside a device is now what its prompt says while it is closed or off (the example's chest said *Open chest* instead of *Heave open*). A hold prompt now says *Hold to use* under its action, and letting go before the bar fills shows *Keep holding until the bar fills*, so a tap no longer looks like nothing happened. New `onPlayer = true` for `setInventory`: interactKit runs `give` on the engine of the player who gets the item, exactly once, so an inventory each player keeps on their own engine (inventoryKit's bag) needs no messages of its own; the guides use it, and the second player in the example no longer risks getting items twice. README and example: the quick start's lever is on your left and the chest on your right, the example's lever on the left and crate on the right, as seen from the player; the example names the version it was checked with, and its two-player notes say what really happens. 89 tests.
- **1.4.1**: Text only, nothing plays differently. The README's Guides section is shorter: the two guide names, where they live and how to open them. No em dashes in the package's code comments, scene scripts or text. The gallery is re-baked by the current engine, which records its components by their full names (`interactKit.Door`). 86 tests.
- **1.4.0**: Guides. Two guides now ship inside the package: *How to make doors, switches, locks and chests* (every part of the kit, written the way people search for it) and *Example: an escape room puzzle with switches and locked doors* (an empty world to a treasure vault with inventoryKit and dialogueKit, followed word for word in a new world, alone and with two players). README: a Guides section saying how to open them, the family of kits with links, a recipe for keys in inventoryKit's bag, known limits that each name an open issue, and no em dashes. One new test checks the guides ship and link each other (86). No change to how anything plays.
- **1.3.2**: Faster with many usable things. Each frame the prompt HUD merged the settings and asked the status of every usable thing in the world, however far away; with a few hundred (a farm with a prompt per plant) that cost about 5 ms a frame. It now remembers how far each thing can be in focus and skips the far ones with one distance check, so the cost follows what is near the player. Prompts, focus and ranges are unchanged.
- **1.3.1**: Fixed: picking anything up made the game heavier and heavier. A taken item rebuilt all its parts every frame on every player's machine; because they hang under a shared object, that also flooded the network, so a second player fell further behind and saw doors open late or never, and could be told "already taken" for their own key. Items now build their shape once and hide with a single change; a taken item costs a clock check per frame. The player who walks over an item sees it go at once, and their own repeated grab never brings it back. The carried-items strip re-reads the inventory a few times a second instead of every frame. Two-player checks through the kit's network handler: each player keeps their own key, the key door opens for the holder and refuses the one without, a chest two players open in the same frame opens once, and every coin goes to exactly one player.
- **1.3.0**: Fixed: in a world with only interactKit installed, walking over the quick start's key did nothing, because the key was a pickupsKit pickup and pickupsKit's components cannot load from `/source/deps/`. Keys, keycards, coins and gems are now interactKit's own `Item` component, counted per player in interactKit's own shared inventory; containers spill Items; each player sees what they carry in a strip at the top left once they carry something. interactKit no longer depends on or names pickupsKit, so installing it brings only controlsKit and juiceKit (`Interact.pickups` is gone; `setInventory` connects any other inventory). New `Interact.items`, catalog family `item`. Gallery relaid out so every label reads from the spawn point, in the editor (which now opens on that view) and in play, with no label under a station's own prompt; its key and keycards are Items and the pickupsKit counter panel is gone.
- **1.2.2**: Web build hardening. Every timer (hold claims, auto-close, button pop-up, messages) now runs on `getTime()`, the wall clock, instead of `os.clock()`, which is CPU time and drifts in the browser, and would disagree between a desktop host and a web player. controlsKit's glyphs load on first use, so a dependency still downloading in a web build cannot take the kit down; prompts draw a plain lettered keycap until it arrives.
- **1.2.1**: Fixed: with only interactKit installed, its dependencies land under `/source/deps/`, where the folder paths it used (`@root::controlsKit.prompts`, `"interactKit.Door"`) did not reach them. Dependencies are now loaded by package name (`~controlsKit.prompts`) and components by resolved type (`Interact.component("Door")`, new). The quick start uses `require("~interactKit.api")`.
- **1.2.0**: `Interact.spawnKey` (keys and coloured keycards without knowing pickupsKit item names), so the quick start needs only interactKit. Full API reference. Tests cover every public call (68).
- **1.1.0**: `InteractSettings`: the world's prompt style in one field. Fixed a turned airlock's halves blocking its doorway; the bookcase opens to 90°. Keyboard, gamepad and touch verified for press and hold.
- **1.0.0**: first release.
## Dependencies
Installed with interactKit:
- **controlsKit 1.2.8**: button-prompt glyphs.
- **juiceKit 1.2.10**: open / close feedback.
Not a dependency any more: **pickupsKit**. Up to 1.2.2 interactKit used its pickups for keys and loot, but an install puts pickupsKit under `/source/deps/`, where its Pickup components cannot load their own code, so keys never counted in a fresh world. interactKit's own `Item` replaces them, and interactKit no longer names pickupsKit anywhere, so an install does not bring it along. To have pickupsKit's counters open interactKit locks in a world that has pickupsKit installed at the top, see `setInventory` under API.