diff --git a/README.md b/README.md index e5ac3c1..c45445b 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,124 @@ # ShaiBot -A modular **Discord.js** bot with a shared Cookie economy, interactive -Crumb Saucer games, cooperative boss battles, raid planning, and -community interactions. +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. Game balance and individual features -> may change. +> **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, per-user +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, and rewards can pay -Cookies back out. +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 and jackpots -- Replay support +- 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 @@ -37,15 +126,33 @@ The **Crumb Saucer** is ShaiBot's Cookie-powered entertainment hub. - 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: +Available bets include: - πŸ”΄ Red - ⚫ Black @@ -57,12 +164,74 @@ 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. +**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 @@ -90,13 +259,6 @@ Roles are **DPS**, **Tank**, and **Healer**, with role-specific proficiencies. The general progression theme includes **Sprout β†’ Adventurer β†’ Warrior of Light**. -### 🏴 Cookie Stealing - -Normal player-to-player stealing is separate from Vault Heist. Steal -difficulty can account for attacker and target wealth, successful steals -can use a randomized percentage with a cap, and failed attempts can -apply a fee that feeds the bot vault. - ### πŸ“… Raid Planner Raid planning uses Discord embeds and reactions. Participation can be @@ -117,7 +279,8 @@ A typical layout: ShaiBot/ β”œβ”€β”€ buttons/ β”‚ β”œβ”€β”€ crumbSaucer/ -β”‚ └── crumbleStrike/ +β”‚ β”œβ”€β”€ crumbleStrike/ +β”‚ └── profile/ β”œβ”€β”€ commands/ β”‚ └── applications/ β”œβ”€β”€ events/ @@ -125,8 +288,12 @@ ShaiBot/ β”œβ”€β”€ modals/ β”œβ”€β”€ utils/ β”‚ β”œβ”€β”€ cookieEconomy.js +β”‚ β”œβ”€β”€ crumbCollect.js +β”‚ β”œβ”€β”€ crumbSlots.js β”‚ β”œβ”€β”€ crumbBlackjack.js β”‚ β”œβ”€β”€ crumbRoulette.js +β”‚ β”œβ”€β”€ cookieHeist.js +β”‚ β”œβ”€β”€ profileSystem.js β”‚ └── crumbleStrike.js β”œβ”€β”€ index.js β”œβ”€β”€ package.json @@ -144,6 +311,40 @@ 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 @@ -152,15 +353,14 @@ client.modals = new Collection(); - A Discord bot application/token - `dotenv` -Use the Node.js version required by the dependencies in your -`package.json`. +Use the Node.js version required by the dependencies in `package.json`. ## Installation Clone the repository: ``` bash -git clone https://github.com/YOUR_USERNAME/ShaiBot.git +git clone https://git.desq-gaming.de/Shaiwase/ShaiBot.git cd ShaiBot ``` @@ -210,7 +410,11 @@ M_URI=mongodb://USER:PASSWORD@HOST:PORT/DATABASE?authSource=admin&retryWrites=fa Never commit database credentials. -Important economy collections include: +Important collections include Cookie balances, cooldowns, persistent +game state, profile statistics, achievements, and global badge +definitions/ownership. + +Core economy collections include: ``` text items_cookies @@ -221,6 +425,10 @@ 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: @@ -234,13 +442,15 @@ await mClient.connect(); await ensureCookieIndexes(); ``` -The intended unique keys are: +The intended unique keys include: ``` text -items_cookies β†’ userId -cooldown_cookies β†’ userId + guildId +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: @@ -272,14 +482,20 @@ Enable any required privileged intents in the Discord Developer Portal. ShaiBot generally follows these conventions: -- Public game output uses **embeds**. -- Short private errors/feedback can use **ephemeral messages**. +- 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 @@ -295,6 +511,14 @@ 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: @@ -304,31 +528,80 @@ Preferred pattern: directory. 3. Reuse `cookieEconomy.js` rather than implementing separate balance logic. -4. Preserve the player/session owner through every screen. -5. Check house liquidity before accepting a wager. -6. Prefer editing the current embed for animation/state transitions. -7. Protect wager resolution against rapid repeated interactions. +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 -The major planned Cookie systems are implemented or designed. Remaining -work is primarily testing, balancing, and hardening. +ShaiBot is currently focused on testing, balancing, hardening, and +expanding progression. -- [ ] Verify Slots replay behavior after deployment -- [ ] Deploy and test limited Roulette +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 boss HP, damage, healing, Energy, Limit generation, - entry costs, and rewards -- [ ] Stress-test simultaneous gambling interactions -- [ ] Stress-test repeated/double button presses -- [ ] Test insufficient-balance races -- [ ] Test behavior with a nearly empty house vault -- [ ] Consider dynamic Vault Heist payout caps -- [ ] Consider an economy audit/log collection +- [ ] 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 Crumb Saucer attractions +- [ ] Add more achievements, hidden badges, and Crumb Saucer + attractions ## Security @@ -343,6 +616,9 @@ node_modules/ 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 @@ -360,11 +636,15 @@ Bug reports, balance suggestions, and contributions are welcome. When contributing: - Keep commands and button handlers modular. -- Reuse shared economy utilities. +- 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