Gambling BOT – Discord Casino & Admin Dashboard Ecosystem

• A persistent virtual currency with complete transaction logging.
• Casino-style games with fully configurable RTP and fairness controls.
• VIP rooms that feel personal, private, automated, and temporary.
• A modern admin dashboard for analytics, management, and server customization.
• A shared NPM package providing schemas, validation, helpers, and strong typing across all apps.

To prevent desynchronization between the bot and the admin dashboard, all logic that defines the casino ecosystem lives inside a dedicated NPM package: gambling-bot-shared.

• Mongoose schemas & models for User, Transaction, Games, Predictions, VIP Rooms, GuildConfiguration.
• Strongly typed constants and enums used by both applications.
• Shared helper functions including RTP calculations and probability utilities.
• Reusable validation logic for commands, forms, and internal systems.
• Utilities for formatting, randomization, state transitions, and gameplay rules.

• User — stored per guild, containing balance, lockedBalance, and daily-streak metadata.
• Transaction — immutable economic log entry with fields such as type (deposit, withdraw, bet, win, bonus, vip, refund), source (command, web, system, casino), and optional betId.

1. Validate registration and guild configuration (allowed channels, limits).
2. Validate bet size using per-guild min/max limits and the user balance.
3. Lock funds by decrementing balance and creating a bet transaction.
4. Execute the game logic (single or multi-round flow, animations, embeds).
5. Compute winnings, update balance, and create win transaction(s).
6. Render a final summary embed with optional balance information.

Instead of treating RTP (Return to Player) as a vague concept, the system exposes it explicitly through a dedicated calculateRTP function. This function reads the guild’s casino settings and computes the real, effective RTP for every game using probability and configuration data — not hardcoded values.

• Dice – a fixed 1/6 probability with a configurable win multiplier.
• Coinflip – 50/50 outcome scaled by a guild multiplier.
• Slots – RTP derived from weighted symbols + multiplier tables using probability across all 3-of-a-kind outcomes.
• Lottery – uses combinatorics to compute exact match probabilities.
• Mini Roulette – RTP per bet type (number, color, parity, range, dozen, column) based on custom 0–18 wheel.
• RPS – simply 1 - casinoCut.
• Golden Jackpot – winMultiplier / oneInChance.
• Blackjack – currently fixed at ~99.4% to match real-world expected return.

case 'coinflip': {
  const { winMultiplier } = settings;
  return 0.5 * Number(winMultiplier) * 100;
}

case 'slots': {
  const { symbolWeights, winMultipliers } = settings;
  const totalWeight = Object.values(symbolWeights).reduce((a, b) => a + b, 0);
  let rtp = 0;

  for (const [symbol, weight] of Object.entries(symbolWeights)) {
    const p = (weight / totalWeight) ** 3; // probability of 3-of-a-kind
    const multi = winMultipliers[symbol + symbol + symbol] ?? 0;
    rtp += p * multi;
  }

  return rtp * 100;
}

To keep players engaged without forcing them to gamble constantly, the system includes a flexible daily bonus mechanic. The bonus logic is fully configurable per guild through bonusSettings, allowing each community to tune progression and pacing.

• Linear or exponential reward mode.
• Base reward, streak increment or multiplier.
• Maximum reward with optional cycle reset behavior.
• Weekly and monthly milestone bonuses.

The /bonus command exposes two subcommands: check and claim. The check subcommand renders a 28-day calendar using emoji icons to represent past, current, and upcoming rewards. The claim subcommand enforces the 24-hour cooldown, updates streak progression, writes a bonus transaction, and updates both balance and lockedBalance on the user document.

VIP rooms are private text channels that players can purchase for a configurable duration. The system ties together the GuildConfiguration, User, and VipRoom models to manage pricing, ownership, permissions, and expiration.

• Prediction documents store title, guild, channel, creator, status, autolock time, and all choices with their odds and attached bets.
• Autolock automatically closes the prediction after a configured timeout.
• When resolved, winning bets are paid out as amount × odds.
• Cancelled predictions refund all users and create refund transactions.