# game.systems.PlayerState Everything the player *is*, as plain data: one table plus the rules that govern it. No entities, no input, no engine — so the survival numbers can be reasoned about on their own, and the interface reads the same values the simulation runs on rather than a copy that drifts. ```lua local PlayerState = require("game.systems.PlayerState") local state = PlayerState.new() ``` ## What is in it - **`new()`** — health, stamina, torch and battery, what is carried, clues, the objective index, the power, and whether the run has ended. - **Movement** — `spendStamina`, `canStartSprint`. - **The torch** — `useTorch`, `torchLow`, `replaceBattery`. - **Carrying** — `has`, `give` (a unique item already taken is not taken again, which is what stops two peers pocketing the same key), `addClue`, `clueCount`, `requiredCluesFound`. - **Damage** — `damage` (returns true when it is fatal), `heal`. - **The objective chain** — `objectiveMet(state, step)` says what each step waits for, and `syncObjective` walks the chain forward as far as the player has actually got. It only ever moves on. - **`ending(state)`** — which ending the run earned, from the clues found and whether the secret room was opened. ## The co-op split `toShared` and `applyShared` state, once, what the whole session agrees on — a door, a key, an objective, the power — against what is only yours: your stamina, your health, your torch. Mixing the two is how a co-op game desynchronises, so the split is a function rather than a judgement at each call site.

# game.systems.Interactable A thing in the house the player can use. **It marks the spot, it does not behave.** It carries what a thing *is* — a door, a pickup, a note, a switch, a place to hide, the way out — and what it is worth; the `Player` component reads it, decides whether the player may have it, and does it. So the house never has to know about keys, and the keys never have to know about hinges. The scene build attaches one to every door leaf and hiding place the house put down, to the front door, and spawns the pickups, notes and the power switch with one already on them. That is what lets a single query find everything the player could be looking at, of every kind. ## Fields | Field | What it is | |---|---| | `kind` | `"door"`, `"pickup"`, `"note"`, `"switch"`, `"hide"` or `"exit"`. | | `ref` | What it is: a door id, an item id, a clue id, or a switch's id. | | `lockedBy` | The `GameRules.ITEMS` id that opens it. Empty means never locked. | | `label` | What the player reads when they look at it. | | `range` | How close the player has to be. | | `spent`, `taken` | A switch already thrown, a pickup already taken. |

# game.Bus The one table the game's parts talk over. **Every slice announces what happened and listens for what it cares about; no slice requires another**, and this is the table in the middle they share. ```lua local Bus = require("game.Bus") Bus.emit(Bus.E.noise, { id = "sprint", position = p, source = "player" }) local handle = Bus.on(Bus.E.playerCaught, function(payload) print(payload.monster) -- "resident" end) Bus.off(Bus.E.playerCaught, handle) ``` `Bus.E` is the event-name list, spelled once so no slice can invent a string nobody else listens for. It is the same set as `GameRules.EVENTS`, which also documents the payload each event carries; the scene entrypoint checks the two agree on every load and warns if they have drifted. `on`, `once`, `off`, `emit`, `count`, `clear`, plus `error()` and `clearError()` for the last handler failure. ## Two rules, because getting them wrong desynchronises a co-op run 1. **The bus is local.** It is a module, and a module is one instance *per peer*. An emit reaches the parts of the game running on this machine and nowhere else. Anything another player must agree about — a door, a key, the objective list, the monster — is written to the **shared store** (`runtime_data.world`, under the keys in `GameRules.DATA`) and read back by every peer. Emit the local *response* to a thing; store the *fact* of it. A part that emits `doorOpened` and never writes the store has a door that opens for one player and stays shut for everyone else. 2. **An emit is synchronous.** Handlers run before `emit` returns, in subscription order, on the frame the thing happened. The payload table is handed out, not copied — read it, do not keep it, do not mutate it. A handler that throws is caught and reported, so one broken listener cannot silence every other listener on the same event; `Bus.error()` reads the last one back. Who calls it: every slice. The house emits doors and pickups, the monsters emit their state and a sighting, the survival systems emit noise, damage and clues, the interface listens to most of it, and the audio director listens to nearly all of it.

# game.GameRules The constants and rules of **The House That Knows You** — the one module every part of the game reads, so two systems written in different sessions agree on what a room is called, how loud a sprint is, how long a torch battery lasts and which ending the player earned. It holds **no behaviour and no entities**: pure data plus a handful of pure functions. Require it and read it; never write to it. ```lua local RULES = require("game.GameRules") ``` ## What is in it - **`ART_DIRECTION`** — the one sentence every generation prompt reuses word for word, and **`REFERENCES`** — the pictures the game is judged against. - **`PALETTE`** — that sentence as numbers, for the interface and for materials. - **`HOUSE`** — the wall height, the wall thickness, the doorway size, the room module, the storey height and the player's own dimensions. Every prop in the game is sized against these. - **`AREAS`** / **`AREA_BY_ID`** — the twelve areas, each with its floor, its nominal centre on the ground plan and the item that unlocks it. - **`OBJECTIVES`** — the twelve-step chain, in order, each naming the area it happens in and the item it needs. - **`ITEMS`**, **`REQUIRED_CLUES`**, **`CLUE_COUNT_FOR_TRUTH`** — what can be picked up, and what the ending is decided on. - **`ENDINGS`** and **`selectEnding(cluesFound, secretRoomOpened)`** — the three endings and the rule that picks one, stated once so the interface and the systems cannot disagree. - **`SURVIVAL`** — speeds, stamina, health, torch battery, interaction ranges. - **`DIFFICULTY`** — easy, normal, nightmare. These change the monster's persistence, reach and the supply density **only**; all three run the same monster logic. - **`MONSTERS`** and **`MONSTER_STATES`** — THE RESIDENT and THE BROODMOTHER, and the states both run: patrol, investigate, chase, search, attack, recover. - **`NOISE`** — the interface between what a player *does* and what a monster *hears*. A system emits a noise id; the monster AI turns it into a reach. Nothing else may write a raw radius. - **`SPIDERS`** — the baby-spider event: five presses, six seconds, the slow-motion tutorial, the prompts, the damage. - **`ENDLESS`** / **`endlessDifficultyFor(floor)`** — Endless Nightmare, and a floor number that never stops climbing. - **`MODES`**, **`MAX_PLAYERS`**, **`DATA`** — the game modes and the keys shared state lives under. ## Who calls it Every slice: the house builder, both monsters, the survival systems, the interface and the audio director. Every component that runs in play reads its numbers from here rather than carrying its own copy.