ShaiBot/docs/GAMES.md

ShaiBot Game Manual

This document gives maintainers a compact overview of the main game systems. Exact rules remain in the owning utilities.

Crumb Saucer

The Crumb Saucer is ShaiBot's Cookie-powered game hub.

Shared principle:

Discord controls
→ game utility
→ Cookie economy / profile system

Slots

Core utility:

utils/crumbSlots.js

Features include multiple wagers, symbol payouts, jackpots, All-In tracking, Run It Back, profile statistics, achievements, and guild-first triplet badges.

Historical replay facts must come from wager-time metadata rather than the player's current Cookie balance.

Blackjack

Core utility:

utils/crumbBlackjack.js

Supports:

• Hit
• Stand
• Double
• Dealer stands on 17
• Natural Blackjack pays 3:2
• Push
• All-In
• Run It Back

Repeated interactions must never resolve/pay the same hand twice.

Roulette

Core utility:

utils/crumbRoulette.js

European Roulette uses 0–36.

Simple bets include Red, Black, Odd, Even, and Zero. Zero loses for Red/Black/Odd/Even.

Animation uses edits of the same message rather than high-frequency message spam.

Vault Heist

Core utility:

utils/cookieHeist.js

Vault Heist targets ShaiBot's house vault and is separate from PvP stealing.

Approaches include Sneak, Hack, and Smash and share the same Heist cooldown.

Bankruptcy

Core utility:

utils/bankruptcy.js

Bankruptcy provides a recovery path and tracks post-Bankruptcy rebuilding in profiles.

Recovery progress should reflect actual balance after Bankruptcy, not merely lifetime Cookie gains.

Run It Back

Supported games can track consecutive replay through the explicit Run It Back action.

A normal/new wager breaks the chain.

Win/loss/push does not inherently break it because the streak represents the player's decision to immediately replay.

Historical All-In and wager state must be preserved at the time the wager occurs.

Poker

Poker is a persistent 2--6 player Texas Hold'em game inside the Crumb Saucer.

Important files:

utils/pokerEngine.js
utils/crumbPoker.js
utils/pokerDiscord.js
utils/pokerInteractions.js
utils/pokerProfile.js
handlers/poker.js
buttons/poker/*
selectMenus/poker/*

Current defaults:

Buy-in:       1,000 Cookies
Blinds:       10 / 20
Turn timer:   90 seconds
Pot model:    single pot

Supported actions:

Fold
Check
Call
Bet
Raise
All-In

Single-Pot Rule

Poker intentionally has no side pots.

At hand start, the maximum amount each participant can commit is limited by the smallest participating starting stack.

Chips above that cap remain protected for a later hand.

Persistence

MongoDB is authoritative for live/recoverable tables.

Poker uses temporary state in:

items_special_games

and optimistic versioning for authoritative updates.

Fully settled games are cleaned up rather than kept permanently as raw history.

Economy

Cookies move only at buy-in and cash-out/refund boundaries.

Betting moves internal table chips.

Recovery-sensitive economy operations are idempotent.

Privacy

Hole cards are private.

The private Cards view may show the requesting player's cards, community cards, turn status, and remaining turn time.

It must never expose opponent cards.

A player-facing equity/win-percentage calculator is intentionally excluded from V1 for fairness.

Turn / Lobby Behavior

Active turns have a 90-second deadline.

Timeout folding uses the same authoritative Fold transition as a normal player action.

Lobby expiry is disabled while a hand is active and refreshed when a hand ends.

The internal between-hand state may be called NEXT_HAND, but the user-facing UI presents HAND COMPLETE.

Cancellation / Cleanup

Host cancellation is allowed outside an active hand.

Cancellation safely settles players before deleting the table state.

Confirmation controls should disappear after Confirm or Keep so stale buttons cannot remain usable.

Crumble Strike

Core utility:

utils/crumbleStrike.js

Crumble Strike is a persistent cooperative boss battle.

Typical flow:

1. Spawn encounter.
2. Recruit players.
3. Start once requirements are met.
4. Fight within the encounter lifetime.
5. Settle success/failure and committed Cookies.

Combat includes:

Strike
Defend
Heal
Revive
Limit Break

Roles include:

DPS
Tank
Healer

Crumble Strike has more lifecycle complexity than ordinary Saucer games. Do not copy its persistence model into simpler games unless the new feature genuinely requires it.

Raid Planner

Raid planning uses Discord embeds and reactions.

Participation can count unique users across reactions without forcibly removing reactions.

Be mindful of Discord partials when changing reaction behavior.