# ShaiBot 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. ### 🍪 Cookie Bakery 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: ``` text 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. ## Cookie Stealing 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`](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: ``` bash git clone https://git.desq-gaming.de/Shaiwase/ShaiBot.git cd ShaiBot npm install ``` Create `.env` in the repository root: ``` env 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: ``` bash node index.js ``` Or with PM2: ``` bash pm2 start index.js --name ShaiBot ``` A typical update cycle is: ``` bash 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: ``` text 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`](docs/ARCHITECTURE.md) Runtime structure, handlers, utilities, Mongo persistence, concurrency, and recovery [`docs/ECONOMY.md`](docs/ECONOMY.md) Cookie balances, transfers, cooldowns, house vault, settlement, and idempotency [`docs/PROGRESSION.md`](docs/PROGRESSION.md) Profiles, achievements, badges, activity, social progression, and maintenance [`docs/GAMES.md`](docs/GAMES.md) Crumb Saucer games, Poker, Crumble Strike, and important game rules [`COOKIE_LOGIC.md`](COOKIE_LOGIC.md) Detailed PvP Cookie stealing rules and balancing [`AGENTS.md`](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: ``` gitignore node_modules/ .env *.log ``` Rotate Discord or MongoDB credentials immediately if they are exposed. ## License See the repository's current license information, if present.