Plugin Enhancement: Levels & XP — boosters, multipliers, streak bonuses, lottery

[DeadIndian]

Plugin Enhancement: Levels & XP — boosters, multipliers, streak bonuses

Enhance adb-plugin-levels with XP boosters, channel/role multipliers, double XP events, level-up rewards lottery, and activity streaks to make the leveling system more engaging.

Why

The current levels plugin is bare-bones: flat XP per message, static cooldown, no incentives for varied participation. Servers need mechanics to reward active periods, encourage specific channel participation, and create FOMO events.

Spec

New Features:

1. XP Multipliers

• /xp-multiplier channel <#channel> <multiplier> — Set channel XP multiplier (e.g., 2x in #general)
• /xp-multiplier role <role> <multiplier> — Set role XP multiplier (e.g., 1.5x for boosters)
• /xp-multiplier stack [additive|multiplicative] — How multipliers stack
• Multipliers visible in /level-config overview

2. Double XP / Events

• /xp-event start <name> <multiplier> <duration> — Start a timed XP event (e.g., 2x XP for 2h)
• /xp-event stop — End active event early
• /xp-event list — Scheduled/active events
• Optional: recurring events (every Saturday 2x XP 6-9pm)
• Event banner embed posted to configured channel on start/end

3. Activity Streaks

• Daily streak: Bonus XP for chatting on consecutive days (+5 XP per day streak)
• Message streak: Bonus for consecutive messages within 5 min (+1 XP per message, capped at +10)
• /streak — Check your current streaks
• /streak leaderboard — Top streak holders
• Streak freeze item (economy integration): pay currency to preserve streak for a day

4. Level-Up Rewards

• /level-lottery prize <amount> — Set pool of currency added per level-up (economy integration)
• /level-lottery toggle — Enable random jackpot on level-up
• Every level-up enters user into a mini lottery (configurable chance, default 5%)
• Winner gets currency from the pool
• /level-reward random <count> <role> — Give random role from pool on level-up

5. Level-Up Announcements

• Custom level-up message templates: {user} leveled up to **Level {level}**!
• Channel-specific: set a dedicated #level-up channel or use the channel the user leveled in
• Role milestone auto-embed showing next role reward
• Level-up GIF/image option (configurable URL)

6. XP Leaderboard Enhancements

• /leaderboard — Add pagination (top 50)
• /leaderboard weekly — This week's top earners
• /leaderboard role <role> — Leaderboard filtered by role
• /leaderboard around <user> — Show ranking around a specific user
• XP decay for inactive users (configurable)

Config Schema Additions:

{
  // Existing config preserved
  // New:
  "multipliers": {
    "channels": { "channelId": 1.5 },
    "roles": { "roleId": 1.5 },
    "stacking": "additive" | "multiplicative"
  },
  "streaks": {
    "dailyBonus": 5,
    "dailyMaxStreak": 365,
    "messageStreakBonus": 1,
    "messageStreakCap": 10,
    "messageStreakWindow": 300000  // 5 min in ms
  },
  "lottery": {
    "enabled": false,
    "poolAmount": 100,
    "chance": 0.05,
    "currencyName": "coins"
  },
  "events": [],
  "decayInactiveDays": 30,
  "decayPercent": 10    // lose 10% XP
}

Acceptance Criteria

• Channel and role XP multipliers working
• Double XP event with timer and announcement
• Daily and message streaks tracked
• Level-up lottery with economy integration
• Paginated leaderboard with weekly filter
• All configurable via slash commands