Shaiwase/ShaiBot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

added more documentation

Browse Source
This commit is contained in:
DeSqBlocki
2026-09-13 22:10:34 +02:00
parent dd4d6e4817
commit 6e3e1620d1
7 changed files with 1020 additions and 669 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+189 -558
View File
@@ -1,611 +1,280 @@
# 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.
ShaiBot is a modular Discord community bot built around a persistent
**Cookie economy**, interactive games, player progression, and
multiplayer activities.
> **Status:** Active development. Features, achievements, and game
> balance may change.
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.
## Features
ShaiBot also includes persistent player profiles, achievements,
guild-unique badges, cooperative encounters, raid planning, and lighter
community features.
### 🍪 Cookie Economy
> **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.
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.
## Highlights
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.
- 🍪 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
Cookie collection is shared between `/cookies collect` and the **Crumb
Saucer Cookie Bakery**, using the same cooldown and reward logic.
## The Crumb Saucer
### 👤 Player Profiles
The **Crumb Saucer** is the main home for ShaiBot's Cookie-powered
games.
ShaiBot includes persistent player profiles that bring together Cookie
and game activity.
### 🍪 Cookie Bakery
Profiles can expose:
Collect Cookies using the same shared collection system as
`/cookies collect`.
- Cookie economy statistics
### 🎰 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
- Lifetime gains and losses
- Stealing and giving activity
- 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
- 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.
Completed multiplayer game documents do not need to become permanent
history when the meaningful result already belongs in the profile
system.
### 🏆 Achievements
## Achievements & Global Badges
Achievements are repeatable across the community: every eligible player
can earn their own copy.
**Achievements** are personal progression. Any eligible player can earn
them.
Achievement tracking can use persistent profile statistics as well as
explicit game events. Current and planned categories include:
**Global badges** are guild-unique distinctions, usually awarded to the
first player in a guild to accomplish something notable.
- 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
Progression spans the Cookie economy, stealing, Crumb Saucer games,
activity, social interactions, Poker, and special cross-game challenges.
Game-specific achievements use names such as:
## Cookie Stealing
``` text
The House Always Wins: Blackjack
```
Player-to-player stealing is separate from Vault Heist.
where sharing a generalized achievement concept between games makes
sense.
The current system accounts for wealth differences, recent pressure on
the victim, percentage-based loot, hard caps, and an hourly exposure
budget.
### 🎖️ Global Badges
Detailed balancing and mechanics are documented in
[`COOKIE_LOGIC.md`](COOKIE_LOGIC.md).
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.
## ⚔️ Crumble Strike
Examples include:
Crumble Strike is ShaiBot's cooperative boss-battle system.
- First-time game accomplishments
- Slots triplet combinations
- All-In / Run It Back feats
- Special or hidden manually awarded badges
- Achievement collection milestones
Players recruit a party, choose combat roles, commit Cookies, and work
together using actions such as Strike, Defend, Heal, Revive, and Limit
Break.
Badges may be hidden until discovered. Some special badges are
intentionally managed manually in MongoDB rather than automatically
awarded by gameplay.
Encounters use persistent state because they can span many players and
interactions.
### 🎰 The Crumb Saucer
## 📅 Raid Planner & Community Features
The **Crumb Saucer** is ShaiBot's Cookie-powered entertainment hub.
ShaiBot also includes raid-planning tools and smaller social/community
commands alongside its economy and progression systems.
#### 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.
# Installation
## Requirements
- Node.js
- Discord.js
- MongoDB
- A Discord bot application/token
- `dotenv`
- Dependencies listed in `package.json`
Use the Node.js version required by the dependencies in `package.json`.
## Installation
Clone the repository:
Clone and install:
``` bash
git clone https://git.desq-gaming.de/Shaiwase/ShaiBot.git
cd ShaiBot
```
Install dependencies:
``` bash
npm install
```
Create `.env` in the project root:
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
```
Start the bot:
Never commit `.env`.
Start normally:
``` bash
node index.js
```
For PM2, a typical command is:
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's Cookie economy intentionally does **not** depend on MongoDB
transactions, allowing it to work with deployments that do not support
replica-set transactions.
ShaiBot does not require MongoDB multi-document transactions for its
core economy.
If your deployment does not support retryable writes, include:
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
```
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:
# Documentation
``` text
items_cookies
cooldown_cookies
items_games
```
The central README intentionally stays high-level. Detailed
implementation rules live in focused manuals:
`items_cookies` stores balances, `cooldown_cookies` stores action
cooldown timestamps, and `items_games` can store persistent game state.
------------------------------------------------------------------------------------
Document Purpose
------------------------------------------------ -----------------------------------
[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) Runtime structure, handlers,
utilities, Mongo persistence,
concurrency, and recovery
Profile-related collection names should be treated as part of the
profile utility's implementation contract rather than duplicated
throughout command/button modules.
[`docs/ECONOMY.md`](docs/ECONOMY.md) Cookie balances, transfers,
cooldowns, house vault, settlement,
and idempotency
### Recommended Indexes
[`docs/PROGRESSION.md`](docs/PROGRESSION.md) Profiles, achievements, badges,
activity, social progression, and
maintenance
Run the shared index initializer after MongoDB connects:
[`docs/GAMES.md`](docs/GAMES.md) Crumb Saucer games, Poker, Crumble
Strike, and important game rules
``` js
const {
ensureCookieIndexes
} = require("./utils/cookieEconomy");
[`COOKIE_LOGIC.md`](COOKIE_LOGIC.md) Detailed PvP Cookie stealing rules
and balancing
await mClient.connect();
await ensureCookieIndexes();
```
[`AGENTS.md`](AGENTS.md) Repository-wide safety and
architecture guide for AI coding
agents
------------------------------------------------------------------------------------
The intended unique keys include:
The current repository code remains the final source of truth.
``` text
items_cookies → userId
cooldown_cookies → userId + guildId
```
------------------------------------------------------------------------
Profile and badge utilities may establish their own required indexes.
# Development Principles
## Discord Intents
ShaiBot generally favors:
The current client uses intents including:
- 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
``` 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
For stateful changes, always consider duplicate interactions,
simultaneous users, insufficient-balance races, and bot restarts during
settlement.
## Security
A suitable `.gitignore` should include at least:
Keep at least the following out of version control:
``` gitignore
node_modules/
@@ -613,46 +282,8 @@ node_modules/
*.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.
Rotate Discord or MongoDB credentials immediately if they are exposed.
## 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. 🍪
See the repository's current license information, if present.