ShaiBot/README.md

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