Glitch The Dark Machine Game Design Document and Room Control Specification Escape Gallery • Version 1.0 • October 17, 2026 Purpose Build one complete, deterministic escape-room run before committing to final physical puzzle mechanics. This specification connects the player experience to authoritative state, device signals, operator actions and acceptance tests. It targets Rust room orchestration, NATS messaging, Godot arcade clients and a Flutter game-master interface. Players investigate an abandoned arcade whose games appear alive. Six recovered tokens awaken six cabinets. Their victories wake a seventh machine, whose defeat exposes a crashed alien spacecraft. Players retrieve six charged power cells, restore the craft and repurpose the arcade controls to calibrate its flight. The final launch succeeds through communication, practiced earlier and adapted to the number of players. Design status Confirmed requirements: six uniquely token-gated cabinets, a seventh boss cabinet, hidden spacecraft, six removable power cells, second-state calibration games, a coordinated launch, computer-controlled Teddy Ruxpin, variable difficulty and small-party support. Rust/NATS and Flutter are the confirmed final approach. Proposed defaults: a 60-minute game; support for 2–8 players, plus an assisted solo test mode; the cabinet assignments, puzzle placeholders, character dialogue, tuning values and event contracts below. These are implementation candidates to validate through simulation and playtesting, not claims of completed room features. How to use this document Implement the rules and state contracts first. Use fake props, accelerated virtual time and scripted game outcomes to execute every act. Then replace each fake adapter with hardware or a Godot game without changing room rules. Sections 2–9 define play; 10–17 specify controls and operations; 18–21 provide implementation and test appendices. Companion file: glitch_implementation_contract.json contains proposed profile values, entity mappings, an event envelope schema, a room-state example and machine-readable test cases. It is a design interchange format requiring an importer, not a drop-in Escape Gallery catalog or existing Odin wire schema. 1 Project alignment and implementation boundary The final system has one room sequencing authority: the Glitch Rust controller. Godot owns local game execution and input feedback; Flutter requests actions and displays authoritative state; NATS carries commands, observations and snapshots. Neither the UI nor an individual cabinet decides that the room has advanced. Area Observed project baseline Required Glitch extension Arcade runtime Seven Godot games and configurable objectives Six first-state assignments, boss treatment and six calibration variants Control path Python controller and browser hub; experimental Rust/NATS/Flutter lab Production Rust room reducer, durable recovery and Flutter run controls Tokens Pac-Man RFID credit admission and Start gating Per-token allowlists for all six cabinets; persistent authorization for retries Sequencing Single predecessor win dependencies All-six join, ship power join, communication rounds and launch barrier Props and hints Device feedback and configured output actions Generic puzzle facts, cell inventory, passage sensing and Teddy scheduler Migration constraints Retain the existing Godot games and their tested lifecycle where possible. Select exactly one controlling backend per cabinet session. Do not let Python scenario sequencing and Rust autopilot both drive the same run. Use the legacy controller only for comparison, rollback or isolated development. The Glitch lab is experimental: named-field MessagePack, a loopback JSON gateway and an in-memory replay cache. The Odin audit describes generated ordered-field prop messages. They are not wire-compatible. Generate agreed Glitch types for Rust and Dart; version the adapter explicitly and do not publish experimental payloads on Odin subjects. Hardware facts that affect this design The integration guide corrects older configuration: BCM23/J20 is an LED, not the power button; physical buttons use an unidentified I2C board. Keep that input mapping disabled until identified. The current catalog has only four cabinet profiles. Cabinets 5–7, cell bays, spacecraft sockets, Teddy and passage sensing need authored definitions. Cabinet 3 lacks Tempest’s second-button capability and Cabinet 4 lists roller where Missile Command requires trackball; reconcile capabilities before assignment. All proposed device names in this GDD are logical identities. Bind them to verified inventory later. Qualify reused local IDs with cabinet identity, for example cabinet_01/cab1_rfid1. 2 Narrative and act structure Act Player experience Exit condition Target minutes Arrival Teddy wakes; investigators learn that tokens belong to particular machines. Briefing acknowledged and run started 0–4 I The arcade Parallel physical discoveries unlock six playable cabinets. Games teach naming, responding and holding a setting. All six first-state wins committed 4–27 II The dark machine Cabinet 7 boots and combines familiar controls into a short boss challenge. Boss won; passage physically confirmed open 27–33 III The passenger Alien reveal; six charged cells are retrieved and installed. All six correct cells present and power stable 33–40 IV Flight school Ship-side navigator gives instructions to arcade-side operators. All calibration checkpoints complete 40–53 V Launch Crew arms stations, confirms readiness and performs a synchronized commit. Launch committed and finale completed 53–60 The story behind the machines Proposed story: the alien’s emergency system has borrowed the arcade’s electrical network. Its damaged translation process makes the games appear mischievous and threatening. Teddy is an imperfect local voice for this system. The boss is a protective firewall, not the alien itself. Defeating it restores enough trust to reveal the passenger and its rescue request. Avoid an abrupt tonal reversal by planting three clues: a repeating distress rhythm after the first win, a star-like pattern after the third, and Teddy briefly saying “help” before correcting himself. The reveal reframes the strange energy as a stranded being trying to survive. The final launch is theatrical; no moving craft is required. Pacing rules Act budgets are targets, not gates or independent countdowns. Early teams progress immediately. At 35 elapsed minutes without the boss completed, suggest assistance; at 45 without ship power, surface a GM pacing alert; at 53 without calibration complete, offer guided calibration. No automatic solve occurs without the configured assistance policy or a logged GM decision. At zero remaining time, enter TIME_EXPIRED and suspend puzzle timers. The GM may extend time or choose a distinct assisted rescue/debrief ending. Only the normal launch guard produces a normal win. Keep achieved checkpoints for extensions; never restart the room merely because time expired. 3 Dependency graph and physical placeholders Run start unlocks five independent discovery branches. Physical mechanics can change while their input/output contracts remain stable. All six tokens must remain obtainable without completing a game that requires one of those same tokens. Puzzle ID Placeholder interaction Prerequisite Reward P01 Restore claw controls using a simple arcade maintenance clue Run active Claw stage A enabled P02A Claw retrieval from a designated prize zone P01 solved T01 for Cabinet 1 P02B Second claw retrieval or alternate prize zone P02A reward delivered T02 for Cabinet 2 P03 Match a record excerpt to an album sleeve Run active T03 for Cabinet 3 P04 Reconstruct a service-panel symbol pattern Run active T04 for Cabinet 4 P05 Match ticket values to a cabinet maintenance label Run active T05 for Cabinet 5 P06 Read a poster overlay or aligned light pattern Run active T06 for Cabinet 6 P02A and P02B are separate reward facts even if they share one physical claw machine. Simulation uses explicit solve and delivery observations. A solution does not prove a token was physically delivered. Jam detection holds reward delivery pending and offers a GM hand-delivery action with a reason. Room dependencies P02A → T01 → A01; P02B → T02 → A02; P03 → T03 → A03; P04 → T04 → A04; P05 → T05 → A05; P06 → T06 → A06. ALL A01–A06 won → B07 available → B07 won → passage release → passage open observation → spacecraft reveal. Reveal → request all six cell bays open. Each cell also requires charge complete before its bay may release. ALL six correct cell installations stable → second-state mode ready on all six cabinets → communication tutorial → calibration waves → final arm → synchronized launch. Token policy Each token has a configured UID or supported identifier mapped to exactly one cabinet. Reject an incorrect token with a short in-world response; do not consume or confiscate it. Admit only a fresh scan in the current run and boot session. The successful scan grants persistent run authorization for that cabinet, not unlimited banked credits. Each failed attempt can restart without finding the token again. Re-scans cannot create additional rewards or wins. The first bench test accepted any card. Production admission must use explicit allowlists and test identifier collisions/reader limitations. A physically discovered token can be accepted even when its delivery sensor was missed; record the discrepancy for the GM rather than create a hidden soft lock. 4 Six arcade assignments and first state Use the first four catalog assignments as the starting point. Cabinets 5–7 are proposals. The branded games below are project assets; public presentation and final naming remain a production decision. A win is a short configured objective, not an expectation that visitors master a full arcade game. ID and game First-state objective prototype Teaches Cell A01 Pac-Man Collect a configured score or clear a shortened board Identify a station and report completion CELL01 A02 Galaga Reach a configured hit/score target Hear a target, repeat it, then act CELL02 A03 Tempest Clear selected lanes or reach score threshold Use named sectors instead of vague directions CELL03 A04 Missile Command Protect a small target set for a short wave Wait for a cue; avoid premature firing CELL04 A05 Frogger Bring a configured number of frogs home Report ready and hold a successful state CELL05 A06 Space Invaders Clear a marked formation or reach score threshold Coordinate a countdown and confirm success CELL06 Objective tuning Proposed baseline: 60–120 seconds of successful play per cabinet, with a 180-second assistance threshold. Begin with the project’s supported score/board/home objectives; bespoke lane or marked-target objectives require game changes. The simulator models progress from 0 to objective_target and emits a validated win; it does not need arcade physics. Default standard fixtures: Pac-Man 500 points, Galaga 500 points, Tempest 500 points, Missile Command 500 points, Frogger 1 home, Space Invaders 500 points. These are simulation seeds, not balanced production goals. Guided uses 60 percent of score targets; challenge uses 140 percent. Integer count objectives use explicit profile values, never rounding to zero. Validate each game adapter’s supported fields at preflight. Teaching without blocking parallel play The first completed cabinet triggers Teddy’s station-name lesson. The next completion triggers an echo/readback example. The third and fifth completions introduce “hold” and “ready.” These beats depend on completion count, not a specific cabinet order. A game win never waits for a voice line to finish. Missed lessons are summarized in the ship tutorial. On loss, show the objective and allow Start again after a three-second reset. Preserve room wins, token authorization and cell charge. Offer reduced target or guidance after two failed attempts; apply a changed target only at the next attempt boundary. No automatic win timer is permitted in a production profile. 5 The boss and spacecraft reveal Cabinet 7 The Dark Machine B07 remains dark and rejects player Start until all six distinct first-state wins are committed. Its boot animation follows a confirmed prepare/ready handshake. Proposed base: a Robotron-inspired protection challenge, subject to cabinet controls, with an alternative bespoke single-joystick variant. Do not require dual joysticks on an unverified cabinet. A three-part boss teaches the later protocol: identify a marked sector, protect the indicated signal, then hold a stable selection through a spoken countdown. Standard target duration is 90–150 seconds with retained stage checkpoints. Loss returns to the current stage after three seconds; repeated failures offer simpler targets. Boss victory is accepted only for its active assignment and attempt. Reveal sequence Step Command or observation Required behavior 1 boss.won committed Latch victory once; queue reveal sound and passage release 2 passage.release requested Only configured action; record command ID and delivery status 3 passage.open observed Fresh sensor stable for 300 ms; begin reveal and cell retrieval 4 ship.reveal complete Show passenger distress, six socket labels and cell instructions 5 cell bay releases Release only charged bays; display pending charge for others Do not equate an acknowledged relay command with an open passage. If no open observation arrives within five seconds, enter a reveal hold, alert the GM and stop the active game clock. The operator can inspect, retry a safe configured action or attest physical opening. Record attestation as an override, not as a sensor reading. Audience and access Use light, sound and the alien’s breathing or movement to carry the reveal; provide readable text alongside speech. No strobe is needed. Keep the passage’s show function separate from emergency egress. A hardware safety layer and venue procedure govern people and moving parts; the narrative controller must never be the only way to leave. Teddy’s reveal line: “That was never an invasion. It was a call for help. The machines have been keeping our visitor alive. Bring the six light cores to the ship. Match every symbol, then come back to the controls.” 6 Power cells and the second state Each cabinet contains one identifiable prop cell. “Charging” is a game abstraction unless engineering later specifies a real electrical function. Start its virtual charge on that cabinet’s first accepted game start. Charge takes 30 seconds of active room time and continues through local game losses. A powered-off or disconnected cabinet pauses only its own charge accumulation. A room hold pauses all charge timers. Cell state Entry or exit rule DOCKED_IDLE Preflight confirms cell identity and bay presence; charge 0 CHARGING First valid game start; accrue verified active time CHARGED_LOCKED Charge reaches 100 percent; cell remains inaccessible until reveal RELEASE_PENDING Reveal reached and charge full; issue bay release once AVAILABLE Bay open confirmed; removal now expected CARRIED Bay absence stable; no ship socket currently contains this identity INSTALLED Matching ship socket reports identity and presence stable for 500 ms UNKNOWN Conflicting or stale observations; hold dependent transition Each cell is mapped one-to-one to its socket, CELL01→SOCKET01 through CELL06→SOCKET06. Reject a wrong socket without penalizing progress. The controller retains both location and charge; a bay sensor going absent alone does not prove the cell reached the ship. Duplicate identity in two places is a fault, not two installed cells. Ship power barrier Require all six correct identities present, charged and healthy continuously for two seconds. Commit ship.power_ready, then prepare all six second-state assignments with new assignment IDs. Every required client must report calibration-ready before issuing tutorial challenges. Token scans are no longer required in this state. Removing any cell before launch commit cancels the current challenge and launch arm, suspends calibration and starts a technical hold. Retain completed calibration checkpoints. Reinsert the correct cell, verify two-second stability and reconcile device readiness; the GM resumes with a fresh challenge ID. Never resume an old countdown automatically. Practical recovery A missing cell may be replaced by a registered spare identity through a logged GM substitution. A failed bay sensor may be attested after inspection. Both actions mark the run assisted. Neither action can make a physically unsafe actuator move. After launch commit, cell removal changes diagnostics only; it does not reverse an already completed story ending. 7 Communication and calibration games Use a consistent spoken grammar: “Station, target, action.” The arcade operator repeats “Station, target, ready.” The navigator answers “Execute.” The game then reports “Locked.” Voice recognition is not required: explicit player buttons and game-state checks record readiness and execution. Teddy models the words, while the actual target remains on the ship display. Station Second-state task Ship-only information Completion check 01 Route Move to one of four route symbols Required symbol Selection equals target at Execute 02 Vector Move a horizontal pointer to a numbered zone Zone number Pointer inside zone for hold duration 03 Heading Rotate to one of eight named sectors Sector label Correct sector stable through commit 04 Shield Select one of three shield banks Bank identifier Correct bank selected on cue 05 Corridor Choose a safe lane or home Lane identifier Correct lane confirmed 06 Thrust Set a discrete thrust level Level 1–4 Correct level held through cue Teaching sequence Round T1 is untimed: one navigator and one arcade operator practice a single station target. The navigator presses Dispatch on the ship console; the operator selects and presses Ready; the ship displays the readback target; the navigator presses Execute. This electronic readback allows the crew to correct mistakes before scoring. Require one successful practice, then one hold-and-countdown practice. Both are repeatable and narrated. Scored calibration contains one or two waves covering all six stations, scheduled at the concurrency supported by the party. Standard has two passes per station with different targets; guided has one; challenge has three. Each completed station-pass is a durable checkpoint. Idle cabinets display their names and wait, avoiding six competing audio tracks. Retry semantics A wrong target, early Execute or expired response window fails only the active wave. Show which station needs correction without erasing earlier passes. Generate a fresh challenge ID and permit replay after three seconds; after two failures, offer slower timing. Late Ready or Execute messages for an old challenge are rejected. Targets are generated from a stored seed, with different consecutive values per station. No calibration step requires an arcade expert. These tasks use familiar controls but assess precise communication. Provide large text, symbols and optional spoken targets; never encode information in color alone. 8 Party size and difficulty profiles Party size determines simultaneous staffing; difficulty determines precision, repetition and hint timing. Store both at run preparation. Do not silently make a larger party harder or force a smaller party to skip story content. Players Navigator and operators Calibration concurrency Final human acknowledgements 1 assisted Ship terminal repeats targets at active cabinet; walk between stations 1; all results latch 1 arcade acknowledgement then ship commit 2 1 ship navigator and 1 roaming arcade operator 1; six stations in sequence 1 arcade acknowledgement then ship commit 3 1 navigator and 2 operators 2 stations per wave 2 arcade acknowledgements then ship commit 4 1 navigator and 3 operators 3 stations per wave 3 arcade acknowledgements then ship commit 5–8 1 navigator; 4–6 operators; extra players scout/check min(players minus 1, 6) One per assigned operator group, up to 6 An operator group owns one or more stations. For two players, one operator sequentially arms all six stations; each station latches and displays armed. That operator acknowledges at the last assigned station, then the navigator commits from the ship. There is no simultaneous six-button requirement. Solo is an assisted simulation/access mode pending approval for sale. Parameter Guided Standard Challenge Passes per station 1 2 3 Response window per wave 60 s 40 s 25 s Stable target hold 1 s 2 s 3 s Final acknowledgement window 30 s 20 s 12 s Inactivity before hint 1 90 s 120 s 180 s Next hint eligibility 60 s later 90 s later 120 s later Boss stage checkpoint Retained Retained Retained Assistance and changes during play Allow GM changes at an attempt or wave boundary; save the previous and new profile with reason. If staffing decreases mid-wave, cancel that wave, repartition unfinished work and preserve completed passes. Changing difficulty cannot retroactively invalidate a win. Accessibility options independently enable captions, longer holds, lower audio, alternative control mappings and a proxy narrator. The timer is 60 minutes for all launch profiles initially. A small-party run reduces concurrent work and repetition through the guided profile if selected; assess physical walking time in playtests. Any extension is visible to staff and logged. Production party limits and timing are pending venue approval. Assisted solo overrides the final acknowledgement window to 90 seconds to allow travel back to the ship. It still uses a five-second synchronized presentation countdown. Store assisted=true throughout; a valid normal launch may set outcome=WON while retaining that assistance marker, distinct from the GM-forced ASSISTED_RESCUE ending. 9 Synchronized launch protocol The synchronization is a barrier of verified readiness followed by one scheduled commit. It must feel simultaneous without depending on every cabinet being physically occupied. Previously calibrated stations remain locked; automatic holding is presented as the ship’s stabilization system. Phase Guard and action Failure or retry ARM All passes complete and ship power stable. Sequentially arm all six stations for a new launch_epoch. Missing/offline station holds launch; GM may configure a proxy explicitly CREW_READY Every assigned operator group acknowledges once at its designated station. Open the profile’s readiness window on the first acknowledgement. Window expiry clears group acknowledgements only; station calibration remains COMMIT_REQUEST Navigator presses ship Commit within the readiness window; all six stations armed and group acknowledgements current. Reject with specific missing prerequisite; never partially commit COUNTDOWN Controller persists start and commit deadlines; five-second audiovisual countdown. Freeze new inputs except cancel. Power loss, offline required agent or GM cancel disarms launch and pauses COMMITTED At deadline, atomically recheck guards and append launch.committed once. Dispatch finale using stable effect IDs. After commit, presentation failures recover without undoing victory DEBRIEF Finale completion reported or GM confirms ending shown. If playback fails, offer alternate ending narration; record fault Timing contract The controller owns the countdown clock and accepts readiness using its receive time, not player-device timestamps. Final presentation commands carry a future presentation time and launch_epoch; clients acknowledge readiness before countdown. A proposed clock-offset tolerance of 100 ms and audiovisual skew target of 250 ms need installation testing. If timing quality is inadequate, centralize the countdown audio and let clients follow state. If a command arrives exactly at a deadline, accept only if received_at_ms < deadline_ms. Persist the ordering chosen by the reducer. A technical hold cancels an in-progress countdown; resumption always creates a new launch_epoch. Crew acknowledgements never survive a new epoch or staffing change. Win and assisted ending Normal outcome is WON when launch.committed is durable. Continue the ending even if a decorative cabinet animation fails. GM Finish assisted uses a separate outcome ASSISTED_RESCUE and reason; it does not forge six wins or cell readings. Abort and time-expired states lead to their own debrief paths. 10 Room and component state machines Separate lifecycle from story phase. Lifecycle is IDLE, PREFLIGHT, READY, RUNNING, PAUSED, RECOVERY_HOLD, TIME_EXPIRED, WON, ASSISTED_RESCUE, ABORTED or RESETTING. Story phase is BRIEFING, ARCADE, BOSS, REVEAL, CELLS, CALIBRATION_TUTORIAL, CALIBRATION, LAUNCH_ARM, COUNTDOWN or DEBRIEF. A hold preserves the current phase and checkpoints. From Event and guard To and effects IDLE prepare; configuration valid PREFLIGHT; poll inventory and versions PREFLIGHT all required checks pass READY; no room timer running READY start_run authorized RUNNING/BRIEFING; start active clock BRIEFING briefing done or GM skip ARCADE; enable discovery branches ARCADE all A01–A06 won BOSS; prepare B07 BOSS valid B07 win REVEAL; request passage release REVEAL passage open confirmed CELLS; reveal and eligible bay releases CELLS all cells stable and clients ready CALIBRATION_TUTORIAL TUTORIAL two practices complete CALIBRATION; generate first wave CALIBRATION all station passes complete LAUNCH_ARM LAUNCH_ARM valid navigator commit COUNTDOWN; persist deadline COUNTDOWN deadline and all guards true WON/DEBRIEF; launch commit once PAUSED is GM-controlled; RECOVERY_HOLD is fault-controlled. Both freeze active elapsed time and gameplay deadlines, while health probes and command expiry continue on wall time. TIME_EXPIRED can return to the saved phase only through a logged time extension. Terminal outcomes accept diagnostics and debrief controls, not gameplay progression. Cabinet states OFF → BOOTING → TOKEN_WAIT → READY → PLAYING → WON or RETRY_READY. A valid token authorization enables READY; Start consumes one attempt credit. Loss enters RETRY_READY and regenerates one credit after three seconds. First-state WON latches permanently for this run. Second-state assignment replaces local play state with CAL_READY → CHALLENGE → LOCKED; it never erases first-state completion. Health ONLINE, STALE or OFFLINE is a separate dimension. Puzzle state is LOCKED, AVAILABLE, SOLVED or REWARD_PENDING/DELIVERED. SOLVED is durable; a delivery failure does not unsolve the puzzle. Device faults are overlays, not invented puzzle states. Any operator rewind requires an explicit dependency cascade preview; prefer local retry over rewinding a room checkpoint. 11 Authoritative state and event contract Use a single serialized reducer per room. Validate an observation, deduplicate it, apply guards, append accepted domain events and update the snapshot in one transaction. Commit outgoing commands to an outbox in that same transaction. Publish after commit. The room state is reconstructed from the journal plus a verified snapshot; UI state is never the source of truth. State group Required fields Run room_id, run_id, schema_version, config_hash, lifecycle, phase, revision, outcome Timing active_elapsed_ms, time_limit_ms, hold_reason, remaining local durations, wall timestamps Configuration difficulty, party_size, operator_groups, seed, controller_epoch Cabinets entity_id, boot_id, assignment_id, attempt_id, mode, first_win, token_authorized, progress, health Props puzzle solved/delivery facts; cell identity/charge/location; socket observations; passage state Calibration challenge_id, wave_index, targets, station passes, ready set, deadlines Launch launch_epoch, armed stations, acknowledged groups, countdown deadline, committed flag Teddy mode, current cue, queue, played semantic keys, hint levels and cooldowns Audit event revision, actor, reason, overrides, command status, observation freshness Envelope shared by normalized events Required: schema_version, event_id, type, room_id, run_id, entity_id, source_id, boot_id, source_seq, assignment_id, occurred_at_ms, received_at_ms and payload. assignment_id is null for non-assignment events. Optional fields include correlation_id, causation_id, actor_id and reason. Controller events use controller identity and epoch. The gateway supplies received_at_ms; a client cannot choose it. event_id is globally unique; source_seq is monotonic within source_id plus boot_id. Reject a wrong room/run, unknown schema, untrusted source or stale assignment before mutation. A duplicate event returns its earlier result without rerunning effects. Gaps trigger a full-state request; do not guess missed progress. Out-of-order lower sequence reports cannot regress state. Important invariants Exactly six distinct first-state wins unlock B07. Seven repeated wins from one cabinet do not. One cell identity occupies at most one known location. Six occupied sockets without identity validation do not power the ship. Only the current challenge or launch epoch can accept readiness. A win occurs once per run. A command acknowledgement is not proof of motion, token delivery, sound playback or passage opening. 12 Signals commands and guard behavior Normalized signal Required payload Acceptance guard puzzle.solved puzzle_id, evidence Puzzle available; trusted adapter or explicit GM override reward.delivered reward_id, evidence Reward pending; identity matches expected token token.observed reader_id, token_id Fresh current-boot scan; correct cabinet; token-wait phase game.started attempt_id Current assignment; credit admitted; cabinet ready game.progress attempt_id, value Current attempt; valid monotonic objective progress game.won / game.lost attempt_id, objective result Current playing attempt; win validated against objective cell.observed cell_id, location, present Known identity/location; debounce and no conflict passage.observed open, sensor_id Trusted current sensor; stable 300 ms calibration.ready challenge_id, selection Expected station; matching current challenge calibration.execute challenge_id Ship navigator; required ready set; deadline open launch.group_ready launch_epoch, group_id Assigned group station; all its stations armed launch.commit_requested launch_epoch Ship terminal; all groups ready; power and health valid teddy.playback_status cue_id, status Current cue; accepted/started/completed/failed distinct Server-generated events include charge.completed, phase.changed, calibration.passed, launch.committed, hint.eligible, timer.expired and recovery.required. Raw observations do not directly trigger outputs: adapters normalize them; the reducer decides the domain transition. Normalize selections to discrete integers: Route 0–3, Vector 1–5, Heading 0–7, Shield 1–3, Corridor 1–4 and Thrust 1–4. Godot reports selection plus stable_for_ms with Ready. The room checks target equality and the profile hold threshold; readback alone cannot award a pass. A station must retain its selection until Execute or revoke readiness if it moves. Commands and acknowledgements Commands include prepare_assignment, power_on, start_attempt, reset_attempt, set_mode, issue_challenge, arm_station, play_cue, cancel_cue, request_snapshot and invoke_configured_action. Each carries command_id, room/run, target boot/session, controller_epoch, expected state revision, expires_at_ms and typed payload. Return ACCEPTED, REJECTED, COMPLETED, FAILED or DELIVERY_UNKNOWN with a reason code and snapshot revision. Default acceptance deadline is two seconds and expiry five seconds; boot completion has a separate ten-second deadline. A pure state-setting command may be retried with the same command_id while unexpired. A pulse, release or other physical action with uncertain delivery is never blindly retried; reconcile feedback or ask the GM to inspect. Keep a durable device dedupe ledger across process restarts. 13 Rust NATS and Flutter target architecture Implement a Rust Glitch domain crate containing a pure reducer, validation and profile resolution. A runtime crate supplies clocks, durable storage and a NATS adapter. Godot communicates through an agreed Rust integration boundary; the current sidecar can prototype it, while GDExtension remains a deployment choice. Each physical driver has one owner. Component Authority and responsibilities Rust room service Room journal/snapshots, dependency joins, timers, hints, recovery, operator audit and output outbox Cabinet agent Assignment validation, game lifecycle, RFID admission, local input, health, durable command dedupe Prop agents Claw and token delivery, cell/socket sensing, passage feedback, Teddy playback and configured outputs NATS Scoped delivery of observations, commands and state; authenticated clients and explicit permissions Flutter GM and gateway Authenticated actions, room map, diagnostic views, subscriptions and revision-aware snapshots Proposed subjects and persistence Use a versioned room namespace such as escape_gallery.glitch.v1. Publish observations to obs., commands to cmd., results to result. and authoritative snapshots to state.room. The gateway exposes room intent actions rather than arbitrary NATS publishing to browsers. Escape Gallery/Odin subjects and identities remain distinct. Recommended baseline: a transactional room journal and outbox in durable local storage, plus JetStream-backed observation delivery. Consumers acknowledge only after durable acceptance/rejection recording. Commands use request/reply plus the durable outbox; an expired command is discarded even if delivered later. State snapshots and reconnect reconciliation remain mandatory. Final storage engine and JetStream policy require engineering sign-off; Core NATS alone must not be treated as a replayable journal. Ordering and leadership Only one active controller owns the room; cabinets accept its fenced controller_epoch. During restart, enter RECOVERY_HOLD, load committed state, acquire authority and reconcile all agents before accepting play. Do not use two active services writing the same run. Any future failover design must define an exclusive lease and fencing before deployment. Generate versioned Rust/Dart contracts from the agreed message source; confirm field ordering for MessagePack and enum encodings. The JSON companion is semantic guidance, not the generated protocol. Flutter must show stale state if its subscription drops, fetch a full snapshot on reconnect and use expected_revision on mutations. Reject conflicting operator edits rather than silently overwrite them. 14 Teddy modes scheduling and overrides Teddy is a character and a control-system output, never an authority that advances game state by speaking. Use authored cues with matching text transcripts. A deterministic cue scheduler selects lines from room facts; generative speech is unnecessary for the initial simulator. Mode Behavior and entry DORMANT Before run; silent, motors in resting pose GUIDE Arrival and discovery; warm, slightly unreliable arcade host GLITCH Brief authored interruptions at major wins; no continuous random chatter REVEAL Boss victory and ship discovery; voice becomes clear and empathetic COACH Calibration tutorial, readback reminders and retry encouragement LAUNCH Priority readiness and countdown coordination HINT Temporary targeted clue, then return to prior narrative mode OPERATOR GM-selected cue or live voice; autopilot narration suspended FAULT or MUTED No motor commands; text/room-speaker fallback available Scheduling rules Priority order: operational stop message, operator voice, launch cue, reveal beat, requested hint, tutorial, automatic hint, ambient line. Only one voice cue plays at a time. Duck cabinet ambience while speaking; never suppress necessary game feedback. Default minimum gap is eight seconds between noncritical lines; ambient frequency at most one per three minutes. Each cue has cue_id, semantic_key, required_phase, precondition, priority, max_duration_ms, interruptible, expires_after_ms and transcript. Before playback, recheck the precondition; discard a queued token hint if that cabinet has already started. Deduplicate story beats by semantic_key per run. Playback completion is recorded separately from scheduling. Override and failure Flutter offers Preview transcript, Play, Stop, Mute, Set mode, Replay last, Choose hint and Take over voice. Takeover cancels pending automatic speech and uses an explicit release back to autopilot. A stopped cue is not automatically replayed; the scheduler reevaluates whether its information is still needed. A GM skip of the briefing is logged and never skips puzzle prerequisites. If playback fails to start within two seconds or exceeds declared duration plus two seconds, stop motion, flag FAULT and show the transcript on the ship/arcade display or room speaker. Story progression does not wait for Teddy. If a mandatory tutorial cue fails, provide its text and require the same player practice, not a playback success flag. Motor limits, pose timing and audio interface require bench validation. 15 Teddy script and escalating hints Cue Trigger and once-only key Proposed line T00 Welcome Run started; welcome “I remember this place full of people. The machines remember too. Find their tokens. Each one belongs to only one machine.” T10 Naming First first-state win; lesson.name “One signal restored. Use the name on the cabinet when you call out. Then we all know who you mean.” T20 Echo Second win; lesson.echo “Say the instruction back before you act. These wires do not always hear us correctly.” T30 Hold Third win; lesson.hold “That pattern looks like stars. Keep a good setting steady until someone says to change it.” T50 Ready Fifth win; lesson.ready “Ready means you are waiting for the same moment. It does not mean go.” T60 Boss All six won; boss.awake “The dark machine is listening now. Break through, and we may finally hear who is calling.” T70 Reveal Passage open; ship.reveal “It was a call for help. Bring the six light cores to the ship. Match their symbols.” T80 Training Calibration ready; coach.begin “Navigator, name a station and its target. Operator, repeat it and press Ready. Navigator, check it, then Execute.” T90 Launch Countdown entered; launch epoch “Every station is holding. Crew ready. Five, four, three, two, one.” T99 Ending Launch committed; ending “A signal has become a journey. You gave our visitor a way home.” Hint policy Maintain a hint level per active puzzle or challenge: 0 none, 1 orientation, 2 concrete direction, 3 explicit next action. Inactivity means no meaningful progress in that branch; button spam and repeated bad scans do not reset it. Automatic level 1 becomes eligible after the profile threshold. Subsequent levels require another threshold interval or a player/GM request. Default automatic maximum is level 2; level 3 is requested or GM-approved. A hint never marks a puzzle solved. Example P03: H1 “The music and the sleeves belong together.” H2 “Listen to the short excerpt and compare it with the marked album choices.” H3 “Choose the sleeve whose symbol matches the displayed excerpt cue, then confirm.” Replace H3 with the actual answer after the record puzzle is finalized; do not claim a nonexistent solution. Example calibration: H1 “Call the station name first.” H2 “The ship has the target; the arcade operator must repeat it.” H3 “Station 3, select NORTH, press Ready, then let the navigator press Execute.” Inject the current target, never a cached one. Suppress hints during reveal/countdown and expire them when the phase changes. 16 Operator dashboard and run operations Flutter’s primary screen should answer: Where is the team, what can happen next, what is blocking it, and what action is safe for staff to take? Show both the narrative phase and technical lifecycle, active time remaining, party/profile, assistance status and the current next-transition guard. Panel Required contents and actions Run header Prepare, Start, Pause, Resume, Extend time, Abort, Finish assisted; show reason and audit outcome Dependency view Puzzles, tokens, six wins, boss, passage, cells and calibration; each blocked item explains its missing prerequisite Cabinet tiles Mode, game, objective, token authorization, attempt, progress, connectivity and latest fault Ship and cells Six identities, bay/socket location, charge percentage, sensor freshness and conflicts Communication Navigator and operator groups, current targets, ready set, wave deadline and completed passes Teddy Current mode/cue, transcript, upcoming cue, hint eligibility, mute and takeover Diagnostics Command lifecycle, delivery unknown, agent boot IDs, version/config mismatch and event history Intervention semantics Separate Retry current attempt, Restart cabinet process, Override puzzle solved, Confirm delivery, Substitute cell, Proxy failed station and Finish assisted. Each button explains its effects before application. Record staff identity, reason, affected entities and before/after revision. Physical actions show configured device and feedback status. Do not offer a generic “force next” that silently skips unknown dependencies. Routine play controls may be immediate. Reset room, abort and dependency rewinds require an explicit confirmation displaying what is lost. A hardware action requires an allowed action binding and valid target session. A stale browser may view history but cannot issue state-changing actions until refreshed. Two simultaneous GM actions use optimistic revision checks; the second receives a conflict with current state. Operational sequence Before guests: validate inventory and capabilities, confirm cells home, test passage and Teddy, reset all game clients, load a matching release/config hash, then Prepare. At briefing: select party size, difficulty and access options; Start begins the game clock. During play: investigate faults before substituting outcomes. After play: complete debrief, export run summary, then enter RESETTING and follow the physical checklist. Run summary records elapsed active time, final outcome, hint use, retries, assistance, technical hold duration, per-act duration and unresolved faults. Keep token identifiers out of guest-facing reports; staff diagnostics can use stable logical token names. 17 Reset recovery and degraded operation Reset transaction Enter RESETTING and inhibit new gameplay. Cancel cues/countdowns; set outputs to their configured resting states. Archive the old run and create a new run_id only after reset checks pass. Clear token authorization, wins, charge, calibration, hints and launch acknowledgements for the new run. Persist device dedupe history and old-run audit records; clearing them can re-enable repeated physical actions. Return T01–T06 to their starting locations, reset claw prizes and placeholder puzzle mechanisms, and verify availability. Return each cell to its own cabinet bay; confirm socket absence and bay identity. Close and latch bays; verify passage show reset independently of egress. Confirm all seven clients in their initial states, boss dark, ship dormant, Teddy resting, and no pending command or delivery-unknown action. Run preflight and have the GM acknowledge the physical checklist. A reset button alone does not prove the room is ready. Fault policy Fault Response Recovery Cabinet disconnect Mark STALE after 3 s, OFFLINE after 8 s; hold if active or required by current barrier Request snapshot; reconcile assignment/attempt and preserve room checkpoints Agent restart New boot_id invalidates old targeted commands Hold; reassign from authoritative room state; never replay an old pulse Controller restart RECOVERY_HOLD, recover journal/outbox Reconcile every required agent and physical state; GM resumes NATS interruption Agents retain current visual state; stop accepting new timed work Reconnect, snapshot, dedupe replay; fresh challenge after resume Unknown delivery No automatic repeat of physical action Inspect sensor/device; confirm or deliberately reissue with reason Teddy unavailable Caption or speaker fallback; no room soft lock Repair independently; resume autopilot only on explicit release Cell removed Cancel current wave/countdown; preserve passes Correct identity reinstalled and stable; fresh challenge/epoch During any hold, health checks and wall-clock command expiry continue. Physical input observations are recorded but gameplay wins/ready inputs are not accepted. On resume, reissue current intent with fresh IDs where necessary. A completed cabinet can be visually reconstructed as won without granting another reward. A failed station proxy is a logged assisted mode; never hide it as healthy hardware. 18 Simulation harness and reference run The simulator uses the same reducer and typed contracts as production. Replace NATS/clock/device adapters with a virtual clock and deterministic fake agents for seven cabinets, physical puzzles, claw delivery, six cell bays, six sockets, passage, ship console and Teddy. Fixtures must not open network connections to real props. Simulation mode is prominently shown and cannot be enabled by a production game profile. Harness controls Provide advance_time(ms), inject_observation, set_agent_online, restart_agent, delay/drop/duplicate/reorder_message, fail_output, confirm_sensor, snapshot and assert_invariant. Seed objective outcomes and calibration targets. Retain a trace of accepted/rejected inputs, state revisions and outgoing commands. Replay the trace to the same final hash without re-emitting physical effects. Virtual minute Stimulus Expected checkpoint 0 Prepare, preflight success, Start, briefing complete RUNNING/ARCADE; five independent branches available 2–12 Solve placeholders and confirm T01–T06 delivery Six rewards recorded; no game is automatically won 4–25 Correct scans, Start and validated wins in arbitrary order Each first win latches once; charge completes after active time 25 Sixth unique win BOSS; B07 boot/ready 28 Boss win; release ACK then passage open sensor REVEAL then CELLS; bay releases requested once 30–36 Confirm bays open, remove cells, insert matching sockets Ship power stable after 2 s; calibration assignments ready 37–39 Complete two practice interactions CALIBRATION 40–51 All required waves pass with current targets LAUNCH_ARM; all station passes retained 52–55 Arm six, acknowledge groups, navigator commit, advance 5 s launch.committed once; WON and debrief After Reset plus physical observations New run ready; no old event can change it Minute values illustrate pacing, not a scheduled autopilot script. The golden-path fixture should also run accelerated without waiting 60 real minutes. No assertion depends on speech completing. Test both player-driven Start and permitted GM start controls, while retaining token admission. Acceptance evidence For every scenario record fixture version, config hash, seed, initial state, exact input trace, expected events, rejected events and final state hash. The tests below are specified acceptance cases; this GDD does not claim that the room implementation or those tests already exist or pass. 19 End to end acceptance scenarios ID Scenario and stimulus Required assertion SIM01 Golden path with 6 players, standard All acts, six cells and two calibration passes; one launch commit SIM02 2 players, guided; one roaming operator All six stations completed; no simultaneous multi-station human input required SIM03 1 assisted player; sequential ship and arcade interactions No deadlock; clearly assisted outcome/metadata SIM04 8 players, challenge; six stations active Unused helper never required for a guard; three passes per station SIM05 Wrong token, repeated scan, stale historical scan No credit for wrong/stale; only one authorization for correct scan SIM06 Lose A03 twice then retry No extra token needed; other wins and charge retained SIM07 Duplicate A01 win and missing A06 win Boss remains dark; unique set count stays 5 SIM08 Claw reward ACK but token delivery jam Reward pending; GM hand-delivery logged; no duplicate dispense SIM09 Boss won; passage ACK without open sensor Reveal hold after 5 s; no assumed opening SIM10 Wrong socket, duplicate cell identity, missing cell Ship power guard false; explicit diagnostic per conflict SIM11 Cell removed during calibration and countdown Current wave/countdown canceled; completed passes retained; fresh IDs SIM12 Late Ready for old challenge; Execute exactly at deadline Both rejected; current wave remains consistent SIM13 One final group late, then retry Acknowledgements clear; calibration retained; launch once on valid retry SIM14 Restart controller after durable boss win before output publish Recovered outbox sends same command ID; no repeated physical release SIM15 Agent restarts after uncertain bay release No blind pulse replay; reconcile or GM inspect SIM16 Network drop, duplicate and reordered events No regression/double reward; snapshot reconciliation reaches same state SIM17 Teddy unavailable or stale queued hint Fallback text; stale hint discarded; gameplay can finish SIM18 Pause 5 min; expire action while paused Active timer frozen; expired wall-time command rejected SIM19 Time expires in calibration; extend 5 min TIME_EXPIRED then preserved phase; no automatic normal win SIM20 Reset and inject old-run win/scan/launch All rejected; fresh run remains pristine 20 Implementation plan and decision register Build order and release gates Milestone 1: agreed generated contracts, Rust reducer, durable run state and a complete fake-prop golden path. Gate: SIM01–13 and SIM17–20 pass. Milestone 2: NATS adapter, durable command dedupe, recovery and Flutter operator view. Gate: SIM14–16 plus conflicting-GM-action and unauthorized-source tests pass. Milestone 3: one real Godot cabinet reproduces power, fresh token, Start, retry and win through the final transport. Gate: reconnect/restart produces no old credit or physical action. Milestone 4: all seven cabinets, calibration variants, cell/socket agents and Teddy. Gate: full run with fake outputs, then each real device accepted independently. Milestone 5: venue rehearsals for 2, 3, 4, 6 and 8 players. Gate: reset, degraded operation, timing, audibility and physical access verified before public operation. Decision Proposed default Owner and validation Party limits and duration 2–8 players, 60 min; solo assisted Room designer; timed small-party walk-through Cabinets 5–7 and controls Frogger, Space Invaders, Robotron-style boss Game/hardware leads; capability validation Physical puzzle mechanics Contracts P01–P06 retained Puzzle designer; confirm token availability and H3 hints Cell charging and sensing Virtual 30 s; identity plus presence Hardware lead; choose sensors and spare procedure Finale timing Latched stations; crew barrier; 5 s countdown Designer/controls lead; test travel and latency Persistence and transport Durable journal/outbox plus JetStream observations Framework owner; retention, schema and recovery review Godot integration Rust boundary; sidecar or GDExtension Framework/game leads; platform lifecycle tests Teddy interfaces Authored audio, captions, bounded motion AV/hardware leads; playback and motor limits Physical release and reset Sensor-confirmed actions; inspection fallback Venue/hardware leads; hardware acceptance Difficulty balance Profile defaults in section 8 Playtest lead; completion and hint metrics Open production decisions do not block the first software simulation. Keep them as explicit configuration values with proposed defaults. Do not encode draft cabinet names, physical pin numbers or one-off test UIDs into the room reducer. 21 Source notes and companion contract guide Design authority The user’s Glitch concept and follow-up requirements establish the room premise, six token gates, seventh cabinet, spacecraft rescue, six cells, second-state coordination and Teddy. The user’s October 17 direction makes Rust/NATS and Flutter the final approach. The timing, task names, thresholds, state contracts and scripts in this document are proposed design decisions. Project material consulted Project root: D:/Projects/escape-gallery/room_glitch. These local files informed compatibility and migration decisions; they were read, not modified: README.md — current arcade framework, games, authoring model and known missing room features. tools/room_controller/README.md and catalog.json — current cabinet assignments, capabilities, scenario structure, operator semantics and reward acknowledgement limitations. docs/odin_integration/README.md — intended Rust/NATS/Flutter responsibilities, single-controller ownership and corrected BCM23/I2C wiring facts. labs/glitch_odin/README.md — simulator and Godot-sidecar scope, experimental contract, replay limits and absent durable room orchestration. labs/glitch_odin/ODIN_MESSAGES.md — generated Odin schema candidates, ordered-field MessagePack distinction and required Glitch-specific messages. Where the older overview and integration notes differ, use the explicit wiring correction in the integration notes. A documentation statement that a bench test passed is historical project evidence, not a new physical verification performed for this GDD. Companion file usage glitch_implementation_contract.json includes design_version, target_architecture, profiles, entity maps, event and command schemas, typed observation payload schemas, an example event, a partial room-state example and simulation_cases. Validate the envelope and its type-selected payload, then apply the semantic guards in sections 11–12. Controller-internal events and complete persistent state types still require generated definitions. No generated Rust/Dart models or existing API compatibility are implied. All durations use integer milliseconds in the companion. Profile resolution happens once at prepare, then any change is logged at a safe attempt/wave boundary. In simulation, physical puzzle solutions and game outcomes are deliberate fixture inputs; in production, adapters must provide their real evidence. Simulation events must never be accepted from production agent credentials. Definition of ready for implementation The first deliverable from engineering should be a full simulated run with visible state transitions and a replayable event trace. Then implement the listed failure scenarios before energizing rewards. The design is successful when a two-person team can finish the full narrative, a restart cannot duplicate an effect, a GM can explain any blocked transition, and a reset reliably produces a clean next run.