ZMN Bot Logo
    Documentation

    ZMN Bot Documentation

    Setup guides and configuration reference for every ZMN module — security, moderation, roles, leveling, and access control.

    Quick Navigation

    Basics
    Modules

    Leveling

    XP-based leveling system with dual tracks, customizable rewards, and rank cards

    Overview

    The ZMN Bot Leveling module engages your community with an XP and leveling system. Members earn XP through two independent tracks — text and voice — and can unlock role rewards as they level up. The system supports customizable rank cards, level-up announcements, and a granular configuration for XP rates.

    What's Included

    • • Dual XP Tracks — text and voice XP tracked independently
    • • 4 Leveling Commands — rank, leaderboard, give-xp, remove-xp
    • • Role Rewards — automatic role assignment on level-up with tier management
    • • Level-Up Announcements — 4 announcement modes with template variables
    • • Custom Rank Cards — configurable accent color, overlay, and background image
    • • XP Multipliers — global and per-role multipliers for text and voice

    XP System

    The leveling module awards XP through two independent systems: text XP for messaging and voice XP for voice channel activity. Both tracks level independently using the same formula.

    Text XP

    Members earn text XP by sending messages in server channels. The system uses a cooldown to prevent spam-based XP farming.

    • • Base XP: 1–3 per message (random)
    • • Cooldown: 3 seconds between XP gains
    • • Role multiplier: additional XP multiplier for specific roles
    • • Tracks: text XP, text level, and message count

    Voice XP

    Members earn voice XP by spending time in voice channels. The system requires at least 2 eligible members in the channel to prevent idle XP farming.

    • • Base XP: 1–3 per 10-second tick (random)
    • • Requirement: ≥2 non-deafened, non-bot members in channel
    • • AFK channels and deafened members are excluded
    • • Role multiplier: additional XP multiplier for specific roles
    • • Tracks: voice XP, voice level, and voice minutes
    Both text and voice XP contribute to a total XP score used for the server leaderboard. Total XP = text XP + voice XP.

    Level Formula

    The XP required to advance from level N to level N+1 follows a quadratic formula that scales progressively:

    XP for next level = 5L² + 50L + 100where L is the current level
    At level 4468, the formula reaches ~100M XP per level. Beyond this, XP per level is capped at 100,000,000.
    Maximum level: 9,999

    Level Threshold Examples

    0 → 1100 XP
    1 → 2155 XP
    5 → 6425 XP
    10 → 111,100 XP
    25 → 264,350 XP
    50 → 5115,350 XP
    Level is calculated from total XP using binary search — at most 14 iterations for levels 0–9999. This means even if you manually add XP, the level is always consistent.

    Leveling Commands

    All leveling commands are grouped under the /levels slash command. Administrative commands require Manage Server permission.

    User Commands

    /levels rankSlash Command

    View your or another user's rank card

    Usage: /levels rank [user]
    /levels leaderboardSlash Command

    View the server leaderboard

    Usage: /levels leaderboard [type] [page]
    Types: total (default), text, voice

    Admin Commands

    /levels give-xpSlash Command

    Give XP to a user

    Usage: /levels give-xp <user> <amount> <type>
    Requires Manage Server permission
    /levels remove-xpSlash Command

    Remove XP from a user

    Usage: /levels remove-xp <user> <amount> <type>
    Requires Manage Server permission
    XP types: text, voice

    Level-Up Announcements

    When a member levels up, the bot can send an announcement. Choose from 4 announcement modes:

    Disabled

    No announcement is sent when a member levels up.

    Current Channel

    Sends the announcement in the same channel where the user sent the message that triggered the level-up. Only applies to text XP.

    Private Message

    Sends the announcement as a DM to the member who leveled up.

    Custom Channel

    Sends the announcement to a specific configured channel.

    Template Variables

    Use these variables in your level-up message. Both [var] and {var} formats are supported.

    [user][user] — Mentions the user
    [user.username][user.username] — Shows the username without mentioning
    [level][level] — Shows the new level
    [oldlevel][oldlevel] — Shows the previous level
    template
    🎉 Congratulations {user}! You've reached level {level}!
    The current-channel mode only works for text XP since voice XP doesn't have a specific text channel context.

    Reward Roles

    Configure role rewards that are automatically assigned when a member reaches a specific level. Rewards can be set for both text and voice levels independently.

    How It Works

    1

    Member reaches a configured reward level

    2

    Bot assigns the configured role to the member

    3

    If 'Remove with higher' is enabled, lower-tier reward roles are removed

    4

    If 'DM Member' is enabled, the member receives a congratulatory DM

    Remove with Higher Reward

    When enabled, reaching a higher-tier reward level removes all lower-tier reward roles. This creates a progressive rank system where members only hold their highest earned rank.

    DM Member

    When enabled, the bot sends a DM to the member when they receive a reward role. The message includes the role name and level reached.

    Immediate Rewards (Level 0)

    Setting a reward at level 0 grants the role immediately when a member earns their first XP. This is useful for giving a 'Verified' or 'Active' role as soon as someone starts participating.

    The bot must have Manage Roles permission and its highest role must be above the reward roles in the server role hierarchy.

    Rank Card

    The /levels rank command generates a visual rank card image showing the member's level, XP progress, and rank position. The card is fully customizable.

    Customization Options

    Accent Color — color of the progress bar and level text

    Overlay Opacity — controls background overlay darkness (0–100%)

    Custom Background — upload a custom image as the rank card background

    If the rank card image fails to generate, the bot falls back to a text response showing the member's rank, level, and XP.

    Configuration

    General Settings

    Enabled

    toggle

    Enable or disable the leveling system

    Level Up Announcement

    select

    Choose how and where level-up messages are sent

    Level Up Channel

    channel

    Channel for level-up announcements (when using custom channel mode)

    Level Up Message

    text

    Custom message template with variable placeholders

    Ignored Roles

    roles

    Members with these roles will not earn any XP

    Ignored Channels

    channels

    No XP will be earned in these channels

    XP Rate Settings

    Text XP Multiplier

    number

    Global multiplier for text XP gain (default: 1.0)

    Text Role XP Multiplier

    roles

    Additional multiplier for members with specific roles in text channels

    Voice XP Multiplier

    number

    Global multiplier for voice XP gain (default: 1.0)

    Voice Role XP Multiplier

    roles

    Additional multiplier for members with specific roles in voice channels

    Rank Card Settings

    Accent Color

    color

    Color of the progress bar and level text on the rank card

    Overlay Opacity

    number

    Controls how dark the overlay on the rank card background is

    Custom Background

    image

    Upload a custom image as the rank card background

    Reward Settings

    Text Level

    number

    The text level at which this reward is granted

    Voice Level

    number

    The voice level at which this reward is granted

    Rewarded Role

    role

    The role given when the member reaches the specified level

    Remove with Higher

    toggle

    Remove lower-tier reward roles when a higher tier is reached

    DM Member

    toggle

    Send a DM to the member when they receive a reward role

    Best Practices

    ✓ Recommended Setup

    • • Start with default XP rates (1.0x) and adjust based on your community activity
    • • Use ignored channels for bot commands and spam channels to prevent XP farming
    • • Set up progressive reward roles with 'Remove with Higher' for a clean rank hierarchy
    • • Enable level-up announcements in a dedicated channel to celebrate milestones
    • • Use role XP multipliers to reward boosters or premium members
    • • Set level 0 immediate rewards to give new members a role on first activity

    ✗ Common Mistakes

    • • Setting XP multipliers too high (members max out too quickly, losing engagement)
    • • Not ignoring bot command channels (members farm XP by running commands)
    • • Creating too many reward tiers at low levels (role clutter)
    • • Forgetting to position the bot role above reward roles (role assignment fails silently)
    • • Using voice XP without the 2-member requirement check (solo idle farming)
    • • Not testing level-up messages with variables before enabling announcements
    Bot Role Requirement: The bot needs Manage Roles permission to assign reward roles. The bot's highest role must be positioned above all reward roles in the server hierarchy.