Chapter 4
Engagement Systems
Retention is more than another game. Daily bonus streaks, VIP rooms, predictions markets, scheduled raffles, and quests keep guilds active between casino rounds, still on the same ledger and guild configuration.
- Daily bonus streaks credit bonusBalance only - farm stays in-casino.
- VIP rooms: timed private channels with buy / extend / member flow.
- Predictions and raffles run on the same ledger as casino play.
- Quests push repeat engagement between rounds without new currency.
Daily bonus & streaks
Per-guild bonusSettings control linear or exponential streak growth, caps, reset-on-max, and weekly / monthly milestones. Rewards credit bonusBalance only, keeping farmed value inside the casino economy.
- /bonus check - 28-day preview calendar (shared generateBonusPreview).
- /bonus claim - 24h cooldown enforced in DB; streak + transaction logged.
- Linear or exponential streak growth, caps, reset-on-max, weekly/monthly milestones - all guild-configurable.
- Dashboard bonus form with live calendar preview when editing settings.
- Admins can grant or revoke bonus balance from the users table without touching withdrawable cash.
VIP rooms
Players buy private Discord channels for a duration. Config covers category, owner/member roles, pricing per day, creation fee, and multi-member support (maxMembers, pricePerAdditionalMember) so rooms can be shared without ad-hoc permission edits.
Purchase & extend
- /vip buy and /vip extend with atomic balance checks.
- reserveVipPurchase / finalizeVipPurchase mirrors casino bet locking.
- VipRoom documents + VIP transactions track expiry and ownership.
- Mod /manage-vip tooling for staff overrides when needed.
Lifecycle
- /vip add-member and remove-member with Discord permission updates.
- On expiry: channel stays, write access revoked (not a hard delete).
- vipExpiration worker (~1 min) + vipExpiryWarning before lapse.
- Dashboard VIP settings form + active VIP channels table.
Predictions
Moderators run parimutuel-style event markets: create a prediction with up to three choices and odds, players bet in-channel, optional autolock, then resolve or cancel with full refunds. Shared validatePredictionBet keeps bot and tests aligned on stake rules.
- Dedicated prediction action/log channels in guild configuration.
- predictionAutolock worker (~1 min) closes betting at the configured time.
- Win payout: stake x odds; cancellations issue refund transactions.
- Dashboard manage UI for creating/inspecting predictions alongside Discord mod commands.
Raffles
Scheduled ticket raffles complement the casino: ticket price, per-user max tickets, draw time, and repeat interval. Players buy in the raffle channel; the pot pays out minus a configurable house cut. Recurring raffles reschedule after each draw.
- /raffle create, cancel, and ticket purchase flows with atomic DB updates.
- raffleDraw worker (~1 min) picks a weighted random winner by ticket count.
- Single-participant edge case refunds the pot instead of charging a house cut.
- Separate raffle action/log channels - configured in dashboard channel settings.
- Dashboard manage/raffles for ops who prefer tables over Discord embeds.
Quests
Quests are first-class in gambling-bot-shared: daily and normal kinds with conditions like casino wins/bets (optionally per game), bonus claims, and streak targets. Admins seed default templates or author custom quests; players track progress via /quests.
- Example templates: win 3 blackjack, place 5 bets, claim daily bonus, first win, 7-day bonus streak.
- Rewards credit bonusBalance with ledger entries, the same non-withdrawable bucket as daily bonus.
- Dashboard manage/quests: create, wipe progress, diagnostics for stuck progression.
- Progress tracked per user per guild without polluting the casino bet pipeline.
- Seed is idempotent by template name - "Add defaults" will not duplicate existing quests.