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

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:

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.

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:

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:

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.

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:

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:

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:

/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:

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

Install dependencies:

npm install

Create .env in the project root:

D_TOKEN=YOUR_DISCORD_BOT_TOKEN
M_URI=YOUR_MONGODB_CONNECTION_STRING
M_DB=YOUR_DATABASE_NAME

Start the bot:

node index.js

For PM2, a typical command is:

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:

retryWrites=false

in the connection string, for example:

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:

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:

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

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

The intended unique keys include:

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:

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

and partials including:

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:

Put shared game logic in utils/.
Put individual Discord button handlers in the appropriate buttons/ directory.
Reuse cookieEconomy.js rather than implementing separate balance logic.
Reuse profileSystem.js for statistics, achievements, and badges.
Preserve the player/session owner through every screen.
Check house liquidity before accepting a wager.
Prefer editing the current embed for animation/state transitions.
Protect wager resolution against rapid repeated interactions.
Persist immutable wager metadata required by achievements or replay behavior.
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:

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

README.md

ShaiBot