feat: casino framework and basic slot machine

3 files changed, 61 insertions, 25 deletions

diff --git a/building_guide/rooms.md b/building_guide/rooms.md
index 602e449..7641c75 100644
--- a/building_guide/rooms.md
+++ b/building_guide/rooms.md
@@ -218,6 +218,39 @@ Mobs stop wandering while in combat. Dead mobs respawn at their home room.
 
 ---
 
+### Casino Tables
+
+Rooms may host one or more casino tables. Players join by typing `play <game>`;
+the table ID is an internal room-local identifier and does not need to be typed.
+
+```yaml
+casino_tables:
+  - id: slots
+    game: slots
+    max_players: 8
+    betting_ticks: 20
+    min_bet: 1
+    max_bet: 1000
+```
+
+`max_players`, `betting_ticks`, `min_bet`, and `max_bet` use defaults when omitted.
+Game-specific rule configuration will be added alongside the table definition as
+each game is implemented.
+
+Single-player machines use `casino_machines` and are separate from multiplayer
+tables:
+
+```yaml
+casino_machines:
+  - id: huff_puff_01
+    game: slots
+    variant: huff_and_even_more_puff
+    min_bet: 1
+    max_bet: 1000
+    spin_ticks: 1
+    payout: 0.97
+```
+
 ### Objects — interactive fixtures
 
 Simple placement:
diff --git a/building_guide/tick_order.md b/building_guide/tick_order.md
index 6138fbe..b4d1f1e 100644
--- a/building_guide/tick_order.md
+++ b/building_guide/tick_order.md
@@ -34,27 +34,28 @@ duplicates so any one of them drifting fails the test loudly.
 | #   | System                  | What it does                                                                                                        |
 | --- | ----------------------- | ------------------------------------------------------------------------------------------------------------------ |
 | 1   | `ProcessQueuedCommands` | Drains each player's free-queued commands and the globally timestamp-sorted active queue; advances walk sequences. |
-| 2   | `MoveTick`              | Counts down `p.MoveTicks`; on reach-zero, completes a pending run/walk and re-prompts.                             |
-| 3   | `SequenceTick`          | Advances every active trigger `sequence` (per-player and global) one step.                                         |
-| 4   | `TransientMobTick`      | Despawns owned / `DespawnOnLeave` mobs whose owner has left their room.                                            |
-| 5   | `World.Tick`            | World-internal: ground-item respawn/despawn/reserve timers and shared-object deplete timers.                        |
-| 6   | `MobStore.Tick`         | Mob shop restock and mob HP regenerate. Order: by `InstanceID` so processing is stable across ticks.              |
-| 7   | `RegenTick`             | Player HP regeneration, accelerated by tech HP-regen multipliers.                                                  |
-| 8   | `EnergyRegenTick`       | Run-energy regeneration for every online player.                                                                   |
-| 9   | `DisconnectTick`        | Counts down pending disconnects and hard-removes finished sessions (skipping players still in combat).             |
-| 10  | `WanderTick`            | Mob wandering (exit-based) and object wandering (fishing spots), with enter/leave messages to observers.           |
-| 11  | `SharedDepletionTick`   | Ticks shared-object deplete timers up (in use) or down (recovering).                                               |
-| 12  | `FireTick`              | Decays fire objects; on burn-out, spawns the removal item and cancels stokers.                                     |
-| 13  | `AdvanceActions`        | Advances every active player action by one tick; fires completion handlers per action type.                        |
-| 14  | `TechTick`              | Drains battery for active tech, applies equipment / PreserveDrain reductions, and deactivates all on empty.        |
-| 15  | `ConsumeTick`           | Counts down `ConsumeCooldown` and `HomeTransportCooldown`.                                                         |
-| 16  | `BroadcastRespawns`     | Flushes respawned world objects and broadcasts their `respawn_broadcast` lines to players in those rooms.           |
-| 17  | `VisualTick`            | Optional per-player "visual tick" line/counter for AFK feedback.                                                   |
-| 18  | `SneakTick`             | Advances guard watch timers and sneaking players' tick counters.                                                   |
-| 19  | `FarmTick`              | Crops grow, drain water, and yield on harvest (fires every `FarmTickInterval` ticks).                              |
-| 20  | `BuffTick`              | Potion buff duration countdown; expires and removes effects.                                                      |
-| 21  | `SafespotTick`          | Safespot unsafe-chance and decay-chance rolls per player.                                                          |
-| 22  | `HazardTick`            | Room hazard damage to non-GodMode players.                                                                         |
+| 2   | `CasinoTick`            | Advances casino betting deadlines and resolves completed casino rounds.                                            |
+| 3   | `MoveTick`              | Counts down `p.MoveTicks`; on reach-zero, completes a pending run/walk and re-prompts.                             |
+| 4   | `SequenceTick`          | Advances every active trigger `sequence` (per-player and global) one step.                                         |
+| 5   | `TransientMobTick`      | Despawns owned / `DespawnOnLeave` mobs whose owner has left their room.                                            |
+| 6   | `World.Tick`            | World-internal: ground-item respawn/despawn/reserve timers and shared-object deplete timers.                        |
+| 7   | `MobStore.Tick`         | Mob shop restock and mob HP regenerate. Order: by `InstanceID` so processing is stable across ticks.              |
+| 8   | `RegenTick`             | Player HP regeneration, accelerated by tech HP-regen multipliers.                                                  |
+| 9   | `EnergyRegenTick`       | Run-energy regeneration for every online player.                                                                   |
+| 10  | `DisconnectTick`        | Counts down pending disconnects and hard-removes finished sessions (skipping players still in combat).             |
+| 11  | `WanderTick`            | Mob wandering (exit-based) and object wandering (fishing spots), with enter/leave messages to observers.           |
+| 12  | `SharedDepletionTick`   | Ticks shared-object deplete timers up (in use) or down (recovering).                                               |
+| 13  | `FireTick`              | Decays fire objects; on burn-out, spawns the removal item and cancels stokers.                                     |
+| 14  | `AdvanceActions`        | Advances every active player action by one tick; fires completion handlers per action type.                        |
+| 15  | `TechTick`              | Drains battery for active tech, applies equipment / PreserveDrain reductions, and deactivates all on empty.        |
+| 16  | `ConsumeTick`           | Counts down `ConsumeCooldown` and `HomeTransportCooldown`.                                                         |
+| 17  | `BroadcastRespawns`     | Flushes respawned world objects and broadcasts their `respawn_broadcast` lines to players in those rooms.           |
+| 18  | `VisualTick`            | Optional per-player "visual tick" line/counter for AFK feedback.                                                   |
+| 19  | `SneakTick`             | Advances guard watch timers and sneaking players' tick counters.                                                   |
+| 20  | `FarmTick`              | Crops grow, drain water, and yield on harvest (fires every `FarmTickInterval` ticks).                              |
+| 21  | `BuffTick`              | Potion buff duration countdown; expires and removes effects.                                                      |
+| 22  | `SafespotTick`          | Safespot unsafe-chance and decay-chance rolls per player.                                                          |
+| 23  | `HazardTick`            | Room hazard damage to non-GodMode players.                                                                         |
 
 ### Determinism contract
 
@@ -65,7 +66,7 @@ Three layers of ordering decide what happens on a given tick, in priority:
    `cmd/thoi/main.go`) always fires first; every system in
    `RunTickSystems` then runs in the table order above. Dynamic combat /
    aggro / respawn subscribers registered later get higher IDs and fire
-   after the canonical 22 systems. This is asserted by
+    after the canonical 23 systems. This is asserted by
    `internal/engine/tick_test.go::TestProcessTickFiresInSubscriptionOrder`.
 
 2. **Per-system iteration order** — deterministic, as of the deterministic
@@ -138,4 +139,4 @@ should fire *after* regen, a sequence whose step messages should appear
   already advanced.
 
 When in doubt, the test in `tick_systems_test.go` is the executable
-specification.
\ No newline at end of file
+specification.
diff --git a/building_guide/triggers.md b/building_guide/triggers.md
index 60b1c82..f7720bb 100644
--- a/building_guide/triggers.md
+++ b/building_guide/triggers.md
@@ -47,7 +47,8 @@ its steps run as a scripted sequence.
         take_item: ""
         teleport: 0
         heal: 0
-        credits: 0
+         credits: 0
+         start_game: ""         # joins a casino table for the current room
         spawn_mob: null           # SpawnMobConfig (or bare string)
         despawn_mob: ""
         aps_node: false
@@ -87,6 +88,7 @@ wait elapses.
 | `teleport` | Moves the player to a room ID. |
 | `heal` | Restores hitpoints (clamped to MaxHP). |
 | `credits` | Positive = award, negative = deduct credits. |
+| `start_game` | Joins the named casino game configured in the player's current room. |
 | `aps_node` | Marks this room's APS node as unlocked. |
 | `condition` | Per-step gate (evaluated once when the sequence reaches this step). |
 
@@ -726,4 +728,4 @@ definition, `give_item`/`take_item` reference existing items, `teleport` and
 
 Validation does NOT check that the watched flags (`on_player_flag` / `on_global_flag`)
 are ever set — those are dynamic, set by runtime gameplay, and can't be statically
-verified.
\ No newline at end of file
+verified.