feat: roulette in domita casino

1 files changed, 62 insertions, 0 deletions

diff --git a/building_guide/roulette.md b/building_guide/roulette.md
new file mode 100644
index 0000000..205e044
--- /dev/null
+++ b/building_guide/roulette.md
@@ -0,0 +1,62 @@
+# Roulette and casino extension readiness
+
+The casino has a usable extension seam: `tableGame`, generic `tableCore`,
+registered constructors/config validation in `registry.go`, structured snapshots,
+shared participation/control routing, and durable per-stake wallet handles.
+Roulette uses those seams rather than adding another command dispatcher.
+
+Example table (one game of each type per room remains the manager's rule):
+
+```yaml
+casino_tables:
+  - id: roulette_single
+    game: roulette
+    min_bet: 1
+    max_bet: 10000
+    betting_ticks: 15
+    roulette:
+      double_zero: false
+      spin_ticks: 4
+```
+
+`double_zero: true` selects the American 38-pocket wheel; otherwise the
+European 37-pocket wheel is used. Spin ticks default to 3; betting ticks use
+the shared default. Ticks follow the server's configured tick length.
+The wheel order is authentic and the outcome is selected uniformly only when
+spinning finishes. The spinning illustration is intentionally schematic.
+
+Initial scope is **one wager per player per spin**, covering straight-up and
+outside bets (colors, parity, high/low, dozens, columns). Multiple simultaneous
+bets and split/street/corner bets are future work, not silently accepted syntax.
+All returns are checked before debiting a wager. Both winning and losing stakes
+settle through `PayCredits(return, stakeID)`, including a zero return for losses.
+Failures leave the stake pending and do not claim that payment succeeded.
+Shutdown and eviction refund outstanding stakes and reset the round.
+Disconnect refunds are safe because no partial outcome is sampled or exposed.
+
+## Assessment and boundaries
+
+This is a sound foundation for more testing-stage table games, not a blanket
+production-readiness certification. New games must test payout math, overflow,
+phase boundaries, disconnects, queued departure, refunds, persistence failure,
+and spectator output. Shared card-game loss settlement still uses the void
+`ResolveStakesByIDs` API: it preserves failed stakes for recovery but cannot
+report that failure to its caller. Roulette avoids that limitation with the
+existing error-returning payment API. Uniform per-stake error-returning
+settlement would be a worthwhile follow-up for older games.
+
+Multiple concurrent wagers need their own explicit ledger/limit model instead
+of reusing the single `Participant.Wager`. Multiple same-game tables in one room
+would also require changing current addressing/validation assumptions.
+
+## Testing shortcut
+
+`data/objects/casino_test_portal.yaml` is placed in starting room 1001.
+`use casino` gives 1000 chips and teleports to vestibule 6100. It is intentionally
+repeatable and uses ordinary trigger/drop/teleport machinery. Keep an inventory
+slot free (ordinary trigger drops fall to the ground when inventory is full).
+Remove the room's `casino_test_portal` reference before production: this grants
+unlimited test funds and bypasses travel/progression. No account roles are needed.
+
+Single-zero room 6182 and double-zero room 6183 are north of ground-floor
+landing 6102. `help roulette` describes player syntax and supported bets.