Problem
Engagement bots are a staple of every growing server, but the popular ones are closed-source, ad-supported, or store everything in flat files that don't survive restarts. The community wanted a leveling bot they could read, extend, and trust with real member data.
The design brief was specific: a leveling system with a deliberate, documented formula, persistent storage that wouldn't lose progress, and a command surface that felt native to modern Discord.
Goals
Leveling
A first-principles XP curve (XP = 5·level² + 50·level + 100) with 15-25 XP per message and a 60-second anti-farming cooldown.
Engagement
Rank cards with progress bars, paginated top-50 leaderboards with medals, and configurable role rewards per level.
Persistence
Async PostgreSQL via asyncpg no flat files, no lost progress, per-guild data isolation.
Extensibility
Modular cog structure plus GitHub integration commands, admin level tools, and hybrid prefix + slash commands.
Architecture
┌──────────────────────────────────────────────────────────────────────────┐ │ MIKU │ ├──────────────────────────────────────────────────────────────────────────┤ │ discord.py → Cog Modules → Data Layer │ │ ┌────────────────────┐→ ┌───────────────────┐→ ┌──────────────────────┐ │ │ │hybrid commands │→ │leveling.py │→ │asyncpg │ │ │ │& prefix + / │→ │help · fun │→ │PostgreSQL │ │ │ │intents: Msg, │→ │info · utility │→ │user_id/guild_id │ │ │ │Members, Guilds │→ │github.py │→ │xp · level · msgs │ │ │ └────────────────────┘→ └───────────────────┘→ └──────────────────────┘ │ │ rank_card.py → progress-bar embeds · leaderboard pagination │ └──────────────────────────────────────────────────────────────────────────┘
Miku is a cog-based discord.py bot with three layers. The gateway layer subscribes to message events (with the Message Content, Server Members, and Guilds intents) and routes them to hybrid commands. The leveling core applies the XP formula, enforces per-user-per-guild cooldowns, and renders rank cards as rich embeds. All state XP, level, message counts, role rewards lives in PostgreSQL through asyncpg, with tables auto-created on first run and isolated per guild.
Gateway & Commands
Hybrid commands answer both &prefix and / slash invocations; privileged intents gate which events the bot can observe.
Leveling Core
Randomized 15-25 XP per message with a 60-second cooldown prevents farming; level-up announcements auto-delete after 10 seconds to reduce spam.
Rank & Leaderboards
rank_card.py renders level, rank, message count, and progress to next level; leaderboards paginate the top 50 with medal emojis.
Persistence
asyncpg talks to PostgreSQL with per-guild rows keyed by user_id + guild_id data survives restarts and never crosses servers.
Key Features
XP & Leveling
Arcane-style curve with documented requirements level 10 needs 3,850 XP, level 50 needs 89,250 and anti-farming cooldowns.
Rank Cards
Beautiful embeds showing rank, level, messages sent, total XP, and an animated progress bar to the next level.
Role Rewards
Admins bind roles to levels (addrole/removerole/rolerewards), turning level-ups into automatic perks.
GitHub Integration
Repo lookups, user/organization profiles, and repository/user search straight from Discord a natural fit for a developer community.
Admin Tools
setlevel, addxp, resetlevel, and resetalllevels (with a CONFIRM guard) give staff full control over leaderboards.
Tech Stack
Python 3.14+
Modern runtime with packaging via pyproject.toml / uv.
discord.py
Async gateway client with hybrid commands and cog system.
asyncpg
High-performance async PostgreSQL driver.
PostgreSQL
Durable, relational storage for XP, levels, and rewards.
Results
Miku proved that a community can ship a leveling bot with production-grade persistence instead of settling for a third-party widget. The XP formula is documented and tunable, the leaderboards drive healthy competition, and the GitHub commands turned the bot into a developer tool as much as a gamification layer.
Challenges & Trade-offs
Challenge
XP farming: members sending spam messages to grind levels would destroy the leaderboard's meaning.
Solution
Randomized 15-25 XP awards plus a 60-second per-user-per-guild cooldown, with bots and DMs excluded entirely.
Challenge
Level-up spam clutters channels in active servers.
Solution
Level-up announcements auto-delete after 10 seconds and can be confined to a dedicated setlevelchannel.
Challenge
Global slash commands take up to an hour to sync, delaying feature rollouts.
Solution
Hybrid commands expose the full surface via & prefix instantly, while slash sync and the applications.commands scope are documented for discoverability.
Implementation Highlights
First-Principles Formula
XP = 5·level² + 50·level + 100 is documented, tunable, and shipped with a level-requirement table no black-box scoring.
Real Database, Not Files
Async PostgreSQL with auto-created tables means member progress survives restarts, deploys, and power failures.
Per-Guild Isolation
Leaderboards and levels never leak across servers each guild gets its own isolated dataset.
Lessons Learned
Gamification is a retention multiplier the documented XP curve made the system transparent and therefore trusted.
Cooldowns and randomization are the two levers that keep engagement systems fair at scale.
Embedding developer tools (GitHub search) into a community bot made it useful beyond gamification.