Quick start

Get the XP system running in your Robo with a single command. No configuration required -- the defaults work out of the box.

Install

npx robo add @robojs/xp@next

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

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

Try it out

Start your Robo and send a few messages in any text channel. The plugin begins tracking XP immediately.

Check your rank

Use /rank to see your current level, XP, and progress toward the next level. The command shows a progress bar and your position on the server leaderboard.

Use /leaderboard to see the top users in the server. By default, this command requires the Manage Guild permission. Set leaderboard.public to true in your config to make it available to everyone.

Give XP manually

Admins can use /xp give @user 500 to award XP directly. The plugin recalculates the user's level and grants any role rewards automatically.

Plugin config file

When installed, the plugin seeds a config file at config/plugins/robojs/xp.ts. This file controls global defaults applied to all guilds on startup.

config/plugins/robojs/xp.ts

import type { PluginOptions } from '@robojs/xp'

export default {
	defaults: {
		cooldownSeconds: 60,
		xpRate: 1.0
	}
} satisfies PluginOptions

config/plugins/robojs/xp.js

export default {
	defaults: {
		cooldownSeconds: 60,
		xpRate: 1.0
	}
}

The defaults field accepts any GuildConfig fields. These become the global baseline that individual guilds can override through /xp config or the API.

File structure

After installation, the plugin adds the following to your project:

xp.tsXP plugin config

The level-announcements.ts seed file is a starter template for sending messages when users level up. Customize it or remove it if you don't need announcements.

Enable the REST API

The plugin includes optional HTTP endpoints for building web dashboards. Install @robojs/server to enable them:

npx robo add @robojs/server@next

Once installed, endpoints like GET /api/xp/users/:guildId/:userId and GET /api/xp/leaderboard/:guildId become available automatically. See REST API for the full endpoint reference.

Next steps

Configuration

Customize cooldowns, multipliers, and no-XP zones.

Commands

Full slash command reference.

Events

Listen to level-ups and XP changes.

Recipes

Common integration patterns.