# 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:

``` text
Discord controls
→ game utility
→ Cookie economy / profile system
```

## Slots

Core utility:

``` text
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:

``` text
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:

``` text
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:

``` text
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:

``` text
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:

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

Current defaults:

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

Supported actions:

``` text
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:

``` text
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:

``` text
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:

``` text
Strike
Defend
Heal
Revive
Limit Break
```

Roles include:

``` text
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.