Documentation Index
Fetch the complete documentation index at: https://mintlify.com/developer51709/Niko/llms.txt
Use this file to discover all available pages before exploring further.
Niko’s leveling cog awards XP to members for each message sent in the server. XP accumulates toward levels, and admins can assign role rewards at specified level thresholds. The system is fully per-guild — XP earned in one server has no relation to any other server.
Commands
| Command | Description |
|---|
/level [member] | View your own or another member’s current level, XP progress, and server rank. Displays a card with the member’s avatar thumbnail. Alias: /rank. |
level-leaderboard | View the server’s top members ordered by level then XP (paginated). Alias: lvl-lb. |
levelpanel | Open the interactive leveling management panel (requires Manage Server). See Level Panel below. Aliases: lvlpanel, lp. |
levelconfig | View the current leveling configuration for this server. Alias: lvlcfg. Requires Manage Server. |
levelconfig toggle | Enable or disable XP tracking for this server. |
levelconfig multiplier <value> | Set the XP gain multiplier (e.g. 1.5 = 50% more XP per message). Alias: xpmultiplier. |
levelconfig cooldown <seconds> | Set the minimum time between XP awards per user (0 = award on every message). |
levelconfig levelupchannel [channel] | Set the channel where level-up announcements are sent. Omit the channel to send announcements in the same channel as the triggering message. Alias: luchannel. |
levelconfig levelrole <level> [role] | Assign a role to be awarded when a member reaches a specific level. Omit the role to remove the assignment for that level. Alias: role. |
levelconfig resetuser <member> | Reset a specific member’s XP and level to 0. Requires Manage Server. |
level-leaderboard, levelpanel, and levelconfig are prefix-only commands. /level (and its /rank alias) is a hybrid command available as both a slash command and a prefix command.
Level Panel
Run levelpanel to open the interactive dashboard — a Components v2 panel with a section navigation dropdown and contextual buttons. The panel has four sections:
Overview
Shows a summary of all leveling settings at a glance: XP enabled state, multiplier, cooldown, announcement channel, custom level-up message, and all configured level roles.
XP Settings
Displays and lets you edit:
- XP Tracking toggle — Enable or disable XP gain entirely. Green = enabled, Red = disabled.
- XP Multiplier — Multiplies the random 15–25 XP base. Editable via a modal (accepts decimals, minimum 0.1).
- XP Cooldown — Seconds between XP awards per member. Editable via the same modal. Set to 0 to award XP on every message.
Announcements
Lets you configure:
- Level-Up Channel — Select any text channel via a channel picker, or click Clear to announce in the same channel as the message that triggered the level-up.
- Level-Up Message — Click ✏️ Edit Message to open a modal and type a custom template. Click ↩️ Reset Message to restore the default. The reset button is disabled if no custom message is set.
Available placeholders for custom messages:
| Placeholder | Value |
|---|
{mention} | Mentions the member who leveled up |
{level} | The new level they reached |
{name} | The member’s display name |
{guild} | The server’s name |
Level Roles
Lists all role rewards configured for this server. From here you can:
- Click ➕ Add Role to open a two-step flow: enter a level number in a modal, then select a role from a role picker.
- Click ➖ Remove Role to open a dropdown listing existing assignments to remove. The button is disabled when no roles are configured.
Role Rewards
Admins can assign roles that are automatically granted when a member reaches a specific level threshold. Role assignments are additive — members keep all previously earned role rewards by default as they level up.
Role rewards are configured via:
levelpanel → Level Roles sectionlevelconfig levelrole <level> <role> — direct prefix command
When a member levels up and a role reward is defined for that level, Niko attempts to add the role. If the bot lacks permission, the level-up is still recorded and announced; only the role assignment is silently skipped.
How XP Works
-
XP per message — Each message sent in any guild text channel awards a random amount between 15 and 25 XP, then multiplied by the server’s XP multiplier (default
1.0×). Bot messages never earn XP.
-
Cooldown — A per-user, per-guild in-memory cooldown prevents rapid XP farming. If the cooldown is set to
60, a member must wait at least 60 seconds between messages that earn XP. The default cooldown is 0 (every message awards XP).
-
Level-up formula — The XP required to advance from level n to n+1 is:
XP needed = 5 × (n²) + 50n + 100
-
XP reset on level-up — When a member levels up, their current XP resets to 0 and they begin accumulating toward the next level.
-
Message content is never stored — Only the presence of a message (author ID, guild ID, timestamp) is used to award XP. The content itself is not retained by the leveling cog.
Data Storage
Leveling data is stored in the central database in two tables:
| Table | Contents |
|---|
levels | Per-guild, per-user XP and level values |
level_config | Per-guild configuration: enabled flag, multiplier, cooldown, announcement channel, custom message, and level-role mapping |
data/levels.json or data/level_config.json files are present when the cog loads, they are automatically migrated into the database and renamed to *.migrated to prevent duplicate imports.