@robojs/xp

XP and leveling system with role rewards, multipliers, and multi-store support.

MIT939.7 kB Package Size 7.9 kB Bundle Size

Install @robojs/xp with:

Standard chat XP system for Discord bots built on Robo.js. Awards XP for messages, tracks levels, manages role rewards, and exposes an event-driven API for building custom features.

Features

Standard XP

Awards 15-25 XP per message with configurable cooldown

Role Rewards

Automatic role assignment with stack or replace modes

Multipliers

Server, role, and user XP multipliers

Cached Leaderboards

Optimized for 10k+ users with sub-200ms refresh

No-XP Zones

Exclude specific roles and channels from earning XP

Admin Commands

Complete control via /xp command suite with interactive UI

Event System

Real-time hooks for level changes and XP updates

Custom Curves

Quadratic, linear, exponential, lookup, or fully custom formulas

Multi-Store

Run parallel progression systems (leveling, currencies, reputation)

Custom Branding

Rename "XP" to "Reputation", "Points", "Karma", or anything else

Quick taste

A complete level-up announcement system in a few lines:

src/robo/start/level-announcements.ts

import { events } from '@robojs/xp'
import { getClient } from '@robojs/discordjs'

events.onLevelUp(async ({ guildId, userId, newLevel }) => {
	const client = getClient()
	const guild = await client.guilds.fetch(guildId)
	const channel = guild.channels.cache.find((c) => c.name === 'level-ups')
	if (!channel?.isTextBased()) return

	await channel.send(`<@${userId}> just reached Level ${newLevel}.`)
})

src/robo/start/level-announcements.js

import { events } from '@robojs/xp'
import { getClient } from '@robojs/discordjs'

events.onLevelUp(async ({ guildId, userId, newLevel }) => {
	const client = getClient()
	const guild = await client.guilds.fetch(guildId)
	const channel = guild.channels.cache.find((c) => c.name === 'level-ups')
	if (!channel?.isTextBased()) return

	await channel.send(`<@${userId}> just reached Level ${newLevel}.`)
})

The same pattern works for contest bonuses, moderation penalties, premium XP boosts, analytics tracking, and any other XP-based feature.

Installation

npx robo add @robojs/xp@next

Or start a new project with the plugin pre-installed:

npx create-robo@next my-project -p @robojs/xp@next

Optional: REST API

Install @robojs/server to enable HTTP endpoints:

npx robo add @robojs/server@next

How it works

When a user sends a message in a guild text channel, the plugin:

Validates the message (not a bot, not a DM, text channel)
Increments the user's messages counter
Checks no-XP channels, no-XP roles, and cooldown
If eligible, rolls 15-25 base XP, applies xpRate and multipliers
Computes the new level and persists the data
Emits levelUp/levelDown and xpChange events

Built-in commands like /rank and /leaderboard let users check their progress. Admins manage the system through /xp config (interactive UI) and /xp give, /xp remove, /xp set.

Default behavior

Setting	Default
XP per message	15-25 (random)
Cooldown	60 seconds per user
Level curve	`XP = 5 * level² + 50 * level + 100`
Rewards mode	Stack (keep all role rewards)
Remove rewards on loss	Disabled
Leaderboard visibility	Admin-only

All defaults are configurable per guild, per store, or globally. See Configuration for the full reference.

Next steps

Quick start

Install the plugin and see it in action.

Configuration

Customize cooldowns, rates, and more.

Commands

Full slash command reference.

API reference

TypeScript API for building custom features.