Levels

interface Levels(source)

Levels of players from all RPG plugins supported by Mimic. Get it via Mimic.levels. To make your own plugin's levels available here, implement LevelProvider instead.

A track is one thing a player levels up in: a class, a skill, a profession, a job, or the single global level. A player may have many tracks from several plugins at once.

It replaces the deprecated LevelSystem API, which supports only a single level per player.

Quick start

If you need just "the player's level", use the primary track. Server owners choose its plugin in Mimic config:

LevelTrack track = levels.getPrimaryTrack(player);
if (track == null) return; // The selected plugin has no primary track

// Check level quickly
if (levels.hasLevel(player, track.key(), 10)) { ... }

// Or get a progress object containing info about level and experience
LevelProgress progress = levels.getProgress(player, track.key());
if (progress != null && progress.getLevel() >= 10) { ... }

Track IDs

Tracks are identified by Key, which consists of a namespace and a path:

  • The namespace is the ID of the plugin providing the track: minecraft, auraskills.

  • The path is the track within that plugin: level, mining.

For example, minecraft provides a single track minecraft:level - the vanilla level, and a skills plugin may provide auraskills:mining and auraskills:combat.

The namespace is required, since the same path in different plugins means a different level. Note that Key.key("mining") turns into minecraft:mining, so validate track IDs read from configs against getAllTracks.

Rules

  • Works only with online players.

  • null or false means "not possible right now": the track doesn't exist, the player doesn't have it, the plugin doesn't support this action, or the player's data isn't loaded yet.

  • Don't cache results. Read them again each time you need them.

  • Read from any thread. Change levels and experience only on the main thread (on Folia - on the player's thread).

Since

0.10.0

Functions

Link copied to clipboard
abstract fun getAllTracks(): List<LevelTrack>

Returns all tracks of all providers, regardless of players. Use it for discovery and config validation. Tracks are sorted by provider priority, then in the order the provider returns them.

Link copied to clipboard
abstract fun getPrimaryTrack(player: Player): LevelTrack?

Returns the track that best represents the player's overall level, or null if there is no such track.

Link copied to clipboard
abstract fun getProgress(player: Player, trackId: Key): LevelProgress?

Returns progress on the trackId, or null if the player doesn't have the track or their data isn't loaded.

Link copied to clipboard
abstract fun getTracks(player: Player): List<LevelTrack>

Returns tracks the player currently has. Tracks are sorted by provider priority, then in the order the provider returns them.

Link copied to clipboard
abstract fun giveExp(player: Player, trackId: Key, amount: Double): Boolean

Gives exactly amount experience on the trackId, ignoring boosters, party sharing and other bonuses the plugin applies to experience earned in-game. Some plugins always apply their boosters, so the player may get more. The plugin's level-up rewards and messages still work as usual.

Link copied to clipboard
abstract fun hasLevel(player: Player, trackId: Key, level: Int): Boolean

Returns true if the player has the track with trackId and their level on it is at least level.

Link copied to clipboard
abstract fun setLevel(player: Player, trackId: Key, level: Int): Boolean

Sets level with 0 experience within the level on the trackId. The level is clamped to LevelProgress.minLevel and LevelProgress.maxLevel. Whether the player gets the plugin's level-up rewards (skill points, unlocks, messages) for skipped levels depends on the plugin. Lowering the level may not take rewards back.

Link copied to clipboard
abstract fun takeExp(player: Player, trackId: Key, amount: Double): Boolean

Takes experience amount on the trackId, lowering levels down to LevelProgress.minLevel if needed.