HTLevelSystem

HTLevelSystem

Level/experience API for Hytale server plugins. Stores player XP in your choice of SQLite/Postgres/MySQL and exposes a flexible leveling curve plus events that other plugins can hook into.

Features

• Persistent player XP with database backends: SQLite (default), PostgreSQL, MySQL.
• Configurable leveling curve: quadratic, linear, or exponential.
• Optional max-level cap (clamps XP once reached).
• Custom events: experience change/gain/loss, level up/down.
• Simple public API so other plugins can read or modify XP.

Installation

1. Drop the built JAR into your server's plugins folder. 2) Start the server once; htlevel.conf will be generated inside the plugin data folder. 3) Edit htlevel.conf to choose DB backend and XP curve, then restart.

Configuration (htlevel.conf)

# Database backend: sqlite | postgres | mysql
backend=sqlite

# SQLite
sqlite.file=users.sql

# PostgreSQL
postgres.host=localhost
postgres.port=5432
postgres.database=hytale
postgres.user=hytale
postgres.password=change_me
postgres.ssl=false

# MySQL
mysql.host=localhost
mysql.port=3306
mysql.database=hytale
mysql.user=hytale
mysql.password=change_me
mysql.useSSL=false

# XP / Leveling
xp.algorithm=quadratic     # quadratic | linear | exponential
xp.maxLevel=100            # <=0 for no cap

# Quadratic: xp = basePerLevel * L + step * L^2
xp.quadratic.basePerLevel=100
xp.quadratic.step=25

# Linear: xp = basePerLevel * L
xp.linear.basePerLevel=150

# Exponential cumulative: base * (multiplier^L - 1)/(multiplier - 1)
xp.exponential.base=100
xp.exponential.multiplier=1.15

Developer API (examples)

// Access the service
HTLevelSystem plugin = (HTLevelSystem) pluginManager.getPlugin("HTLevelSystem");
ExperienceService xp = plugin.getExperienceService();

// Give XP
xp.addExperience(player.getUuid(), 50);

// Set absolute XP
xp.setExperience(player.getUuid(), 1200);

// Read current snapshot
ExperienceSnapshot snap = xp.getOrCreate(player.getUuid());
int level = snap.level();
long totalXp = snap.experience();

// Resolve XP required for a level
long xpFor20 = xp.experienceForLevel(20);

Listening to XP events

getEventRegistry().registerGlobal(LevelUpEvent.class, event ->
    getLogger().info("Player " + event.getPlayerId() + " reached level " + event.getNewLevel())
);

getEventRegistry().registerGlobal(ExperienceLossEvent.class, event ->
    getLogger().info("Player " + event.getPlayerId() + " lost " + Math.abs(event.getDelta()) + " XP")
);

Admin commands

All commands require permission htlevel.admin.

Root: /htxp (aliases: /htlevel, /htlvl)

• /htxp get <playerName> — show XP, level, and max-level cap status.
• /htxp setxp <playerName> <amount> — set absolute XP.
• /htxp givexp <playerName> <amount> — add XP.
• /htxp takexp <playerName> <amount> — remove XP (floors at 0; respects max-level cap).
• /htxp setlvl <playerName> <level> — set level directly (XP auto-adjusts).
• /htxp givelvl <playerName> <levels> — add levels (honors max-level cap).
• /htxp takelvl <playerName> <levels> — remove levels (floors at 0).

Commands execute asynchronously and always respect the configured XP curve and xp.maxLevel cap.

Notes

• If xp.maxLevel is set, XP is clamped to the max-level requirement; players cannot progress past it.
• When the event bus is unavailable, XP still updates but events are skipped.