DeSqBlocki
263 lines
4.8 KiB
Markdown
263 lines
4.8 KiB
Markdown
# 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.
|