Level System

Level System

The level system awards XP to Discord users for activity in your server's Discord (chat messages and voice calls), then lets them claim Minecraft rewards when they reach configured level thresholds.

---

How It Works

Earning XP

Text XP — awarded when a user sends a message in a qualifying channel. A per-user cooldown prevents farming by sending rapid messages.

Voice XP — awarded periodically while a user is connected to a voice channel.

XP accumulates and the plugin calculates the user's current level from the configured XP thresholds.

Claiming Rewards

When a player runs /discordreward in Minecraft:

1. The plugin looks up their linked Discord account.
2. It checks which level rewards have been unlocked but not yet claimed.
3. It executes the reward commands for each unclaimed level.
4. The claimed levels are recorded so they cannot be claimed again.

---

Requirements

• Players must have a linked account to claim Minecraft rewards.
• The bot needs Message Content Intent for text XP.
• The bot needs Guild Voice States intent for voice XP.

---

Configuration

All level system settings live in level-system.yml:

level-system:
  enabled: true

  text:
    enabled: true
    xp-per-message: 5           # XP gained per qualifying message
    cooldown: 60                # Seconds between XP awards per user (anti-spam)
    channels:                   # Channel IDs that grant XP. Leave empty for all channels.
      - "1234567890"

  voice:
    enabled: true
    xp-per-interval: 10         # XP gained per interval tick
    interval: 300               # Seconds between voice XP ticks
    exclude-afk-channel: true   # Skip users in the AFK channel
    afk-channel-id: "AFK_CHANNEL_ID"

  # Notify users when they level up
  level-up-notification:
    enabled: true
    dm-user: true
    dm-message: "You reached level %level% on %server_name%! Run /discordreward to claim your reward."

  # Define levels: each entry is one level threshold
  levels:
    - level: 1
      required-xp: 100
      commands: []               # No reward for level 1
    - level: 5
      required-xp: 500
      commands:
        - "give %player_name% emerald 1"
    - level: 10
      required-xp: 1500
      commands:
        - "give %player_name% emerald 5"
        - "eco give %player_name% 500"
    - level: 25
      required-xp: 5000
      commands:
        - "lp user %player_name% parent set vip"
        - "give %player_name% nether_star 1"

---

Level Threshold Calculation

The plugin uses the required-xp values you define. A user's level is the highest entry whose required-xp is less than or equal to their total XP.

Example with the config above:

• 0 XP → Level 0
• 100 XP → Level 1
• 500 XP → Level 5
• 1499 XP → Level 5 (not yet Level 10)
• 1500 XP → Level 10

---

Reward Commands

Commands run as the console with the Minecraft player online.

Available placeholders:

Placeholder	Description
%player_name%	Minecraft username
%player_uuid%	Minecraft UUID
%discord_id%	Discord user ID
%level%	The level being claimed
%server_name%	Server name from config

---

Leaderboard

Players can view the top Discord users by XP using Discord commands:

/leaderboard text    # Top users by text XP
/leaderboard voice   # Top users by voice XP

The leaderboard shows the top 10 users with their levels and XP counts.

---

Checking Your Level

Players can check their own Discord level and XP progress:

/level               # In Discord: shows your text level, voice level, and XP
/discordreward       # In Minecraft: claims all unclaimed level rewards

---

Data Storage

Level data is stored in the level_data table:

Column	Description
discord_id	Discord user ID
text_xp	Total text XP earned
voice_xp	Total voice XP earned
text_level	Current text level
voice_level	Current voice level
claimed_rewards	JSON list of claimed level numbers

---

Anti-Abuse

• Text cooldown — XP is only awarded once per cooldown seconds per user. Sending 100 messages in a minute only awards XP once.
• Channel whitelist — Restrict XP to specific channels to prevent spamming low-traffic channels.
• AFK channel exclusion — Users parked in the AFK channel do not earn voice XP.
• One-time claim — Each level reward can only be claimed once. Claimed levels are stored persistently.