ShaiBot/README.md

# ShaiBot

A modular **Discord.js** bot built around a shared Cookie economy,
interactive Crumb Saucer games, player profiles, achievements, global
badges, cooperative boss battles, raid planning, and community
interactions.

> **Status:** Active development. Features, achievements, and game
> balance may change.

## Features

### 🍪 Cookie Economy

Cookies are ShaiBot's shared virtual currency. The economy supports
persistent balances, atomic balance checks, transfers, Mongo-backed
cooldowns, and a shared bot/house vault.

The bot itself acts as the general Cookie vault: gambling losses and
penalties can feed the vault, while wins, heists, collection rewards,
and other systems can pay Cookies back out.

Cookie collection is shared between `/cookies collect` and the **Crumb
Saucer Cookie Bakery**, using the same cooldown and reward logic.

### 👤 Player Profiles

ShaiBot includes persistent player profiles that bring together Cookie
and game activity.

Profiles can expose:

-   Cookie economy statistics
-   Per-game statistics
-   Lifetime gains and losses
-   Stealing and giving activity
-   Achievements
-   Global badges
-   Collection progress

Profile menus are public so other members can view them, while
interactive controls are intended to remain restricted to the session
owner. Errors, cooldown/debug-style feedback, and unauthorized
interaction messages may be ephemeral.

### 🏆 Achievements

Achievements are repeatable across the community: every eligible player
can earn their own copy.

Achievement tracking can use persistent profile statistics as well as
explicit game events. Current and planned categories include:

-   Cookie collection and economy milestones
-   Giving and stealing milestones
-   Game wins and losses
-   Game-specific loss milestones
-   All-In accomplishments
-   Run It Back streaks
-   Cross-game special challenges
-   Collector achievements for earning a portion or all available
    achievements

Game-specific achievements use names such as:

``` text
The House Always Wins: Blackjack
```

where sharing a generalized achievement concept between games makes
sense.

### 🎖️ Global Badges

Global badges are guild-wide collectibles that can have a single owner.
They are intended for special "first player to..." accomplishments and
other unique distinctions.

Examples include:

-   First-time game accomplishments
-   Slots triplet combinations
-   All-In / Run It Back feats
-   Special or hidden manually awarded badges
-   Achievement collection milestones

Badges may be hidden until discovered. Some special badges are
intentionally managed manually in MongoDB rather than automatically
awarded by gameplay.

### 🎰 The Crumb Saucer

The **Crumb Saucer** is ShaiBot's Cookie-powered entertainment hub.

#### Cookie Bakery

Players can collect a fresh batch of Cookies from the Saucer.

The Bakery and `/cookies collect` use the same shared collection
utility, meaning they share:

-   The same Mongo-backed cooldown
-   The same reward range
-   The same balance mutation
-   The same profile/stat tracking

The current default collection range is **1--1000 Cookies**.

#### Slots

-   Multiple Cookie wagers
-   Embed-based reel presentation
-   Different symbol payouts
-   Triplet combinations
-   Jackpot support
-   Run It Back support
-   Shared Cookie vault
-   Game-specific achievements and first-time global badges

Slots triplets can participate in unique global badge progression,
including Lemon, Cherry, Cookie, Star, and Diamond combinations.

#### Blackjack

-   Hit, Stand, and Double
-   Dealer stands on 17
-   Natural Blackjack pays 3:2
-   Push returns the wager
-   All-In support
-   Run It Back support
-   Persistent active hands
-   Per-player session ownership
-   Safe simultaneous sessions
-   Profile, achievement, and badge integration

All-In state should be derived from the committed wager and the player's
vault at the time the wager is made rather than solely from which button
was pressed.

Run It Back preserves immutable metadata from the previous hand. This
allows historical challenges to remain valid even if another player
changes the user's Cookie balance between rounds.

For example, an All-In that pushes can be followed by Run It Back and
still qualify for an All-In → Run It Back challenge even if Cookies were
gifted to the player in between.

Blackjack resolution is designed to guard against rapid repeated
interactions so a hand cannot be resolved and paid multiple times.

#### Roulette

A compact European Roulette implementation using **0--36**.

Available bets include:

-   🔴 Red
-   ⚫ Black
-   Odd
-   Even
-   🟢 Zero

Roulette uses repeated edits of the same embed for a
rate-limit-conscious pseudo-animation. Zero loses on Red, Black, Odd,
and Even.

Roulette supports All-In and Run It Back tracking for profile
achievements and special accomplishments.

#### Vault Heist

Players can attempt to steal directly from ShaiBot's Cookie vault using
different risk/reward approaches such as **Sneak**, **Hack**, and
**Smash**.

Heist actions share a per-player cooldown so changing approach does not
bypass it.

Heist rewards and fines use percentage-based mechanics with hard caps so
the system remains meaningful for wealthy players without allowing
extreme balances to produce unreasonable penalties.

### 🔁 Run It Back

Supported Crumb Saucer games can track consecutive use of **Run It
Back**.

The streak represents the player's choice to immediately replay through
the Run It Back action; wins, losses, pushes, jackpots, or other
outcomes do not inherently break the streak.

Current achievement concepts include using Run It Back five consecutive
times in supported games:

``` text
One More Spin: Slots
One More Bet: Roulette
One More Hand: Blackjack
```

A normal/new wager breaks that game's Run It Back chain.

### ♾️ I Can Do This All Day

A special cross-game accomplishment tracks the sequence:

``` text
All-In
→ round resolves
→ Run It Back with the same committed wager
```

The original All-In is determined from immutable wager-time data. The
Run It Back relationship is determined from the previous game's stored
bet and All-In state rather than relying on the player's live vault
remaining unchanged.

This prevents another player gifting Cookies between rounds from
invalidating a legitimate sequence.

The accomplishment can exist both as a normal achievement available to
everyone and as a global first-time badge for the first player to
perform it.

### 🏴 Cookie Stealing

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

Steal difficulty can account for attacker and target wealth. Successful
steals use randomized percentages with hard caps, while failed attempts
can apply a percentage-based penalty.

Profile tracking records relevant Cookie gains/losses and stealing
activity.

### ⚔️ Crumble Strike

**Crumble Strike** is a cooperative Cookie-powered boss battle.

-   A player spawns an encounter.
-   Other players join during recruitment.
-   The author can start after at least **5 players** have joined.
-   Players can join an active encounter later.
-   Encounters have a limited lifetime.
-   Failure can result in committed Cookies being lost.

Combat actions include:

-   **Strike** --- basic damage and Energy generation.
-   **Defend** --- reduces incoming damage at an Energy cost.
-   **Heal** --- restores party health at an Energy cost.
-   **Revive** --- party-wide revival progress. Normal roles add +1 to
    every downed player; Healers add +2. Three progress revives a
    player.
-   **Limit Break** --- consumes the party's global Limit resource for
    major damage.

Roles are **DPS**, **Tank**, and **Healer**, with role-specific
proficiencies. The general progression theme includes **Sprout →
Adventurer → Warrior of Light**.

### 📅 Raid Planner

Raid planning uses Discord embeds and reactions. Participation can be
counted across reactions without automatically removing user reactions,
including a count of unique participants.

### 👈 Poke

A lightweight social command can privately poke another guild member
through DMs. Repeated pokes are bounded to a rate-limit-friendly
maximum.

## Project Structure

A typical layout:

``` text
ShaiBot/
├── buttons/
│   ├── crumbSaucer/
│   ├── crumbleStrike/
│   └── profile/
├── commands/
│   └── applications/
├── events/
├── handlers/
├── modals/
├── utils/
│   ├── cookieEconomy.js
│   ├── crumbCollect.js
│   ├── crumbSlots.js
│   ├── crumbBlackjack.js
│   ├── crumbRoulette.js
│   ├── cookieHeist.js
│   ├── profileSystem.js
│   └── crumbleStrike.js
├── index.js
├── package.json
└── .env
```

Interaction modules are loaded into Discord.js collections such as:

``` js
client.commands = new Collection();
client.legacyCommands = new Collection();
client.aliases = new Collection();
client.buttons = new Collection();
client.selectMenus = new Collection();
client.modals = new Collection();
```

## Shared Utility Architecture

Game/application files should remain thin wherever practical.

Shared behavior belongs in `utils/`, particularly:

-   `cookieEconomy.js` --- balances, transfers, cooldowns, and economy
    primitives
-   `crumbCollect.js` --- authoritative Cookie collection behavior
-   `crumbSlots.js` --- Slots state and resolution
-   `crumbBlackjack.js` --- Blackjack state and resolution
-   `crumbRoulette.js` --- Roulette state and resolution
-   `cookieHeist.js` --- Vault Heist behavior
-   `profileSystem.js` --- profile statistics, achievements, badges,
    rendering, and audit helpers

Application commands and button handlers should call these utilities
rather than independently reimplementing economy or progression logic.

This is especially important for features reachable from multiple
interfaces. For example:

``` text
/cookies collect
        │
        ▼
  crumbCollect.js
        ▲
        │
Crumb Saucer Bakery
```

Both interfaces therefore share one authoritative implementation.

## Requirements

-   Node.js
-   Discord.js
-   MongoDB
-   A Discord bot application/token
-   `dotenv`

Use the Node.js version required by the dependencies in `package.json`.

## Installation

Clone the repository:

``` bash
git clone https://git.desq-gaming.de/Shaiwase/ShaiBot.git
cd ShaiBot
```

Install dependencies:

``` bash
npm install
```

Create `.env` in the project root:

``` env
D_TOKEN=YOUR_DISCORD_BOT_TOKEN
M_URI=YOUR_MONGODB_CONNECTION_STRING
M_DB=YOUR_DATABASE_NAME
```

Start the bot:

``` bash
node index.js
```

For PM2, a typical command is:

``` bash
pm2 start index.js --name ShaiBot
```

## MongoDB

ShaiBot's Cookie economy intentionally does **not** depend on MongoDB
transactions, allowing it to work with deployments that do not support
replica-set transactions.

If your deployment does not support retryable writes, include:

``` text
retryWrites=false
```

in the connection string, for example:

``` env
M_URI=mongodb://USER:PASSWORD@HOST:PORT/DATABASE?authSource=admin&retryWrites=false
```

Never commit database credentials.

Important collections include Cookie balances, cooldowns, persistent
game state, profile statistics, achievements, and global badge
definitions/ownership.

Core economy collections include:

``` text
items_cookies
cooldown_cookies
items_games
```

`items_cookies` stores balances, `cooldown_cookies` stores action
cooldown timestamps, and `items_games` can store persistent game state.

Profile-related collection names should be treated as part of the
profile utility's implementation contract rather than duplicated
throughout command/button modules.

### Recommended Indexes

Run the shared index initializer after MongoDB connects:

``` js
const {
    ensureCookieIndexes
} = require("./utils/cookieEconomy");

await mClient.connect();
await ensureCookieIndexes();
```

The intended unique keys include:

``` text
items_cookies      → userId
cooldown_cookies   → userId + guildId
```

Profile and badge utilities may establish their own required indexes.

## Discord Intents

The current client uses intents including:

``` js
GatewayIntentBits.Guilds
GatewayIntentBits.GuildMembers
GatewayIntentBits.GuildMessages
GatewayIntentBits.GuildPresences
GatewayIntentBits.GuildMessageReactions
GatewayIntentBits.GuildVoiceStates
GatewayIntentBits.DirectMessages
GatewayIntentBits.MessageContent
```

and partials including:

``` js
Partials.Channel
Partials.Message
Partials.User
Partials.GuildMember
Partials.Reaction
```

Enable any required privileged intents in the Discord Developer Portal.

## Interaction Design

ShaiBot generally follows these conventions:

-   Normal user-facing messages, achievements, menus, and game output
    are **public by default**.
-   Errors, unauthorized interaction feedback, cooldown/debug-style
    notices, and similar operational messages may be **ephemeral**.
-   Games use **buttons** for interaction.
-   Existing messages are edited where practical instead of repeatedly
    sending new messages.
-   Game/session ownership is preserved so multiple users can play
    independently.
-   Public menus may be visible to everyone without allowing other users
    to control the owner's session.
-   Animation-like effects use rate-limit-conscious message edits.
-   Embed state should not be treated as the only authoritative source
    for critical economy/game resolution data.

## Economy Safety

Economy operations favor atomic MongoDB updates for balance checks and
debits.

Transfers avoid MongoDB transactions for deployment compatibility. If a
destination credit fails after a successful debit, the shared economy
utility performs a best-effort compensating credit to the source
account. Administrators should monitor logs for critical compensation
failures.

When adding games, check that the house vault can cover the maximum
possible payout before accepting a wager.

Game resolution should be protected against rapid repeated interactions.
A result must never be paid twice simply because two button interactions
reached the server close together.

Historical game facts such as wager amount, vault-at-wager, All-In
state, and replay origin should be persisted when needed rather than
reconstructed later from a player's live balance.

## Adding a Crumb Saucer Game

Preferred pattern:

1.  Put shared game logic in `utils/`.
2.  Put individual Discord button handlers in the appropriate `buttons/`
    directory.
3.  Reuse `cookieEconomy.js` rather than implementing separate balance
    logic.
4.  Reuse `profileSystem.js` for statistics, achievements, and badges.
5.  Preserve the player/session owner through every screen.
6.  Check house liquidity before accepting a wager.
7.  Prefer editing the current embed for animation/state transitions.
8.  Protect wager resolution against rapid repeated interactions.
9.  Persist immutable wager metadata required by achievements or replay
    behavior.
10. Keep application/button handlers thin and avoid duplicating shared
    rules.

## Achievement and Badge Design

Achievements and global badges serve different purposes:

**Achievements** are personal progression. Multiple players can earn the
same achievement.

**Global badges** are unique guild-wide distinctions and may have a
single owner.

When adding progression:

-   Prefer stat-backed achievements for durable numeric milestones.
-   Use explicit event tracking when the accomplishment depends on a
    particular sequence or action.
-   Keep generalized achievement naming consistent between games where
    appropriate.
-   Do not make collector completion depend on achievements that cannot
    actually be obtained.
-   Use atomic badge claiming so two players cannot both receive a
    guild-first badge.
-   Hidden/manual badges do not need gameplay evaluators if they are
    intentionally awarded directly in MongoDB.

## Administration and Auditing

The profile system includes administrative/audit concepts for validating
profile progression data and expected badge definitions.

When changing achievement or badge schemas:

-   Keep existing IDs stable once players may have unlocked them.
-   Prefer adding new IDs over renaming historical IDs.
-   Treat legacy/disabled definitions explicitly.
-   Audit missing or malformed definitions after database changes.
-   Avoid hardcoding optional manually managed badges as mandatory
    configuration unless they are intended to exist in every guild.

## Roadmap / TODO

ShaiBot is currently focused on testing, balancing, hardening, and
expanding progression.

Near-term work includes:

-   [ ] Continue stress-testing simultaneous gambling interactions
-   [ ] Continue testing repeated/double button presses
-   [ ] Test insufficient-balance races
-   [ ] Test behavior with a nearly empty house vault
-   [ ] Validate All-In and Run It Back achievement edge cases
-   [ ] Validate Run It Back streak progression across supported games
-   [ ] Validate Slots triplet badge claiming
-   [ ] Continue balancing Vault Heist rewards and fines
-   [ ] Add Bankruptcy / starter recovery behavior
-   [ ] Continue centralizing persistent interaction/session ownership
-   [ ] Consider an economy audit/log collection
-   [ ] Verify Crumble Strike AoE Revive behavior
-   [ ] Verify Crumble Strike expiration/failure cleanup survives bot
    restarts
-   [ ] Balance Crumble Strike boss HP, damage, healing, Energy, Limit
    generation, entry costs, and rewards
-   [ ] Add more Crumble Strike bosses, lore, and encounter variety
-   [ ] Add more achievements, hidden badges, and Crumb Saucer
    attractions

## Security

A suitable `.gitignore` should include at least:

``` gitignore
node_modules/
.env
*.log
```

If a Discord token or MongoDB credential is accidentally committed,
rotate it immediately.

Do not expose administrative secrets or database credentials through
embeds, logs intended for public channels, or repository commits.

## Disclaimer

ShaiBot Cookies are fictional in-bot currency with no real-world
monetary value. Crumb Saucer gambling-style games are entertainment
mechanics using that fictional currency.

Final Fantasy XIV names and concepts referenced by community game
features belong to their respective rights holders. ShaiBot is not
affiliated with or endorsed by Square Enix.

## Contributing

Bug reports, balance suggestions, and contributions are welcome.

When contributing:

-   Keep commands and button handlers modular.
-   Reuse shared economy and profile utilities.
-   Avoid blocking the event loop.
-   Be mindful of Discord API rate limits.
-   Validate interaction ownership.
-   Keep database operations safe under concurrent interactions.
-   Preserve existing achievement/badge IDs where users may already own
    them.
-   Avoid introducing a second implementation of behavior that already
    has a shared utility.

## License

Add the license used by the repository here. If the project is open
source, include a `LICENSE` file and replace this section with the
chosen license.

------------------------------------------------------------------------

Made for Discord communities that believe every problem can be improved
with a few more Cookies. 🍪