ShaiBot is a modular Discord community bot built around a persistent Cookie economy, interactive games, player progression, and multiplayer activities.

The bot's main entertainment hub is the Crumb Saucer, where players can collect and wager Cookies, play casino-style games, attempt Vault Heists, recover through Bankruptcy, and sit down at a multiplayer Texas Hold'em table.

ShaiBot also includes persistent player profiles, achievements, guild-unique badges, cooperative encounters, raid planning, and lighter community features.

Status: Active development and stabilization. The major economy, profile, achievement, and Poker overhaul is live; current work is focused primarily on testing, balancing, and polish.

Highlights

🍪 Persistent Cookie economy
🎰 Crumb Saucer game hub
🎰 Slots, Blackjack, Roulette, Vault Heist, and Bankruptcy
♠️ Persistent 2--6 player Texas Hold'em
🏴 Player-to-player Cookie stealing
👤 Lifetime player profiles and statistics
🏆 Personal achievements
🎖️ Guild-unique global badges
🔁 All-In and Run It Back progression
⚔️ Cooperative Crumble Strike encounters
📅 Raid planning and community utilities
💾 Mongo-backed persistence and recovery

The Crumb Saucer

The Crumb Saucer is the main home for ShaiBot's Cookie-powered games.

Collect Cookies using the same shared collection system as /cookies collect.

🎰 Slots

Spin for symbol combinations, jackpots, All-In wagers, and Run It Back streaks.

🃏 Blackjack

Includes Hit, Stand, Double, natural Blackjack, pushes, All-In, and Run It Back.

🎡 Roulette

A compact European Roulette game using numbers 0–36, with Red, Black, Odd, Even, and Zero bets.

🏦 Vault Heist

Attempt to steal from ShaiBot's house vault using different risk/reward approaches.

🆘 Bankruptcy

A recovery mechanic for players who need a fresh start, with profile progression for rebuilding afterward.

♠️ Shai Poker

A persistent multiplayer Texas Hold'em game for 2--6 players.

Current defaults:

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

Poker supports private hole cards, public community cards, Fold/Check/Call/Bet/Raise/All-In, automatic timeout folding, restart recovery, host cancellation, safe buy-in/cash-out settlement, Poker statistics, achievements, and guild-first badges.

Side pots, tournaments, bots, rake, and player-facing equity assistance are intentionally outside the current V1 design.

Player Profiles

Profiles provide the permanent history behind ShaiBot's progression systems.

They track things such as:

Game wins and losses
Per-game statistics
Cookie gains and losses
Giving and stealing
Daily activity and streaks
Social progression
Run It Back streaks
Poker history and hand accomplishments
Achievements
Global badges

Completed multiplayer game documents do not need to become permanent history when the meaningful result already belongs in the profile system.

Achievements & Global Badges

Achievements are personal progression. Any eligible player can earn them.

Global badges are guild-unique distinctions, usually awarded to the first player in a guild to accomplish something notable.

Progression spans the Cookie economy, stealing, Crumb Saucer games, activity, social interactions, Poker, and special cross-game challenges.

Player-to-player stealing is separate from Vault Heist.

The current system accounts for wealth differences, recent pressure on the victim, percentage-based loot, hard caps, and an hourly exposure budget.

Detailed balancing and mechanics are documented in COOKIE_LOGIC.md.

⚔️ Crumble Strike

Crumble Strike is ShaiBot's cooperative boss-battle system.

Players recruit a party, choose combat roles, commit Cookies, and work together using actions such as Strike, Defend, Heal, Revive, and Limit Break.

Encounters use persistent state because they can span many players and interactions.

📅 Raid Planner & Community Features

ShaiBot also includes raid-planning tools and smaller social/community commands alongside its economy and progression systems.

Installation

Requirements

Node.js
MongoDB
A Discord bot application/token
Dependencies listed in package.json

Clone and install:

git clone https://git.desq-gaming.de/Shaiwase/ShaiBot.git
cd ShaiBot
npm install

Create .env in the repository root:

D_TOKEN=YOUR_DISCORD_BOT_TOKEN
M_URI=YOUR_MONGODB_CONNECTION_STRING
M_DB=YOUR_DATABASE_NAME

# Optional
BOT_AUTHOR_ID=YOUR_DISCORD_USER_ID
PROFILE_TIMEZONE=Europe/Berlin

Never commit .env.

Start normally:

node index.js

Or with PM2:

pm2 start index.js --name ShaiBot

A typical update cycle is:

node --check path/to/changed-file.js
pm2 restart ShaiBot
pm2 logs ShaiBot --lines 100

MongoDB

ShaiBot does not require MongoDB multi-document transactions for its core economy.

The bot instead relies on atomic updates, unique indexes, optimistic concurrency, idempotent operations, and recovery logic where appropriate.

If your Mongo deployment does not support retryable writes, your connection string may require:

retryWrites=false

Never commit database credentials.

Documentation

The central README intentionally stays high-level. Detailed implementation rules live in focused manuals:

Document Purpose

docs/ARCHITECTURE.md Runtime structure, handlers, utilities, Mongo persistence, concurrency, and recovery

docs/ECONOMY.md Cookie balances, transfers, cooldowns, house vault, settlement, and idempotency

docs/PROGRESSION.md Profiles, achievements, badges, activity, social progression, and maintenance

docs/GAMES.md Crumb Saucer games, Poker, Crumble Strike, and important game rules

COOKIE_LOGIC.md Detailed PvP Cookie stealing rules and balancing

`AGENTS.md` Repository-wide safety and architecture guide for AI coding agents

The current repository code remains the final source of truth.

Development Principles

ShaiBot generally favors:

Shared utilities instead of duplicated game/economy logic
Thin Discord command/button wrappers
Persistent authoritative state where recovery matters
Atomic and idempotent economy operations
Centralized profile progression
Public game experiences with private sensitive information
Small explicit solutions over unnecessary abstraction

For stateful changes, always consider duplicate interactions, simultaneous users, insufficient-balance races, and bot restarts during settlement.

Security

Keep at least the following out of version control:

node_modules/
.env
*.log

Rotate Discord or MongoDB credentials immediately if they are exposed.

License

See the repository's current license information, if present.

README.md Unescape Escape

ShaiBot