XP & Leveling System

1. Feature Brief

The XP & Leveling System is a guild-normalized activity tracker that rewards genuine interaction across text and voice channels. Rather than using fixed XP per message that invites spam, Utilara evaluates activity quality inside rolling 2-minute windows against your server’s own dynamic baseline. Spammers receive diminishing returns automatically, while real conversation is naturally rewarded.

1. Adaptive dynamic curve - XP rewards peak for steady, natural participation and naturally penalize repetitive spam bursts
2. Dual text & voice tracking - independently tracks text conversation and active voice participation with dedicated stats
3. Rank Card V2 - a high-resolution 934x282px Canvas card displaying text level, voice level, progress bars, and server rankings
4. Custom card banners Premium - upload custom background artwork or provide image URLs with /xp banner
5. Flexible role rewards - assign roles that trigger on Text XP, Voice XP, or Combined Total XP milestones
6. Role synchronization - run /xp sync anytime to scan all server members and grant missing level roles retroactively
7. Anti-farm voice safeguards - voice XP requires at least 2 non-bot, unmuted members in a non-AFK voice channel
8. Level-up announcements - customizable text channel with embed or plain-text formats and member mentions

Who can use this?

All members can check their rank with /rank and view /leaderboard. Managing XP, rewards, and sync commands requires Manage Server permission.

---

2. Sub-Systems

Rank Card V2

The /rank [user] command renders a custom Canvas card showcasing:

• Member Avatar & Badges: Discord avatar with current activity status
• Dual Progress Bars: Separate level indicators and progress bars for Text XP and Voice XP
• Server Standings: Independent server rank positions for text and voice leaderboards
• Total Active Time: Exact seconds tracked and seconds needed for next level threshold

Spam Protection

Checking another member’s rank has no cooldown. Self-checks have a 5-second anti-spam cooldown to keep channels clean.

Server Custom Banner (/xp banner) Premium:

• Premium servers can customize the default background artwork on all server rank cards
• Upload an image file directly (PNG, JPG, WebP up to 8MB, recommended 934x282px) or enter a hosted URL
• Use /xp banner preview:true to preview the render or /xp banner reset:true to revert to default

Role Rewards & Sync

Reward active community members with automated Discord roles as they level up.

Trigger Types:

• Text XP Milestone: Grants role when target text level is achieved
• Voice XP Milestone: Grants role when target voice level is achieved
• Combined XP Milestone: Grants role based on cumulative overall server participation

Stacking Modes:

• Stack Mode (default): Members keep all previously earned level roles as they advance
• Replace Mode: Members retain only the highest role reward they qualify for

Retroactive Role Sync (/xp sync):

• Scans every member in your server against current level records
• Automatically grants any missing role rewards to members who leveled up while offline or before a new role was configured

Voice XP Requirements

Voice tracking operates independently of text chat. To earn Voice XP, a member must:

1. Be connected to an active voice channel (not the designated AFK channel)
2. Not be self-muted, server-muted, self-deafened, or server-deafened
3. Share the channel with at least 2 non-bot members (prevents solo AFK farming)

Sessions commit elapsed time periodically, ensuring zero lost progress during network reconnects.

Effort Scoring

Utilara groups messages into rolling 2-minute windows, scoring:

• Filtered word counts (rejecting repetitive character floods)
• Conversation depth and reply chains
• Message frequency capped per window

This ensures that community members having meaningful discussions gain consistent progress, while low-effort spam yields diminishing returns.

---

3. Setup Guide

1. Open the settings panel - run /xp settings to review baseline toggles, announcement channels, and blacklist settings.

2. Configure role rewards - run /xp rewards to map roles to specific level milestones (Text, Voice, or Combined).

3. Exclude staff or bot channels Optional - click Configure Blacklists in the settings panel to exempt specific channels or moderation roles from earning XP.

4. Sync existing members - run /xp sync after creating or modifying rewards to ensure existing members have all matching roles.

XP Command Reference

Command	Permission	Description
/rank [user]	Everyone	View Rank Card V2 with dual text and voice progress
/leaderboard	Everyone	View top 10 rankings across text and voice
/xp settings	Manage Server	Interactive dashboard for XP toggles, announcements, and blacklists
/xp rewards	Manage Server	Interactive role rewards manager
/xp sync	Manage Server	Retroactively scans server members and grants missing level roles
/xp banner	Manage Server	Set custom rank card background image or URL [Premium]
/xp setxp <user> <seconds>	Manage Server	Overwrite a member’s XP seconds for text or voice
/xp addxp <user> <seconds>	Manage Server	Add XP seconds to a member
/xp removexp <user> <seconds>	Manage Server	Deduct XP seconds from a member
/xp resetxp [user]	Manage Server	Reset XP for a specific member or all server members