HT等级系统

HTLevelSystem

用于 Hytale 服务器插件的等级/经验值 API。将玩家经验值存储在你选择的 SQLite/Postgres/MySQL 中，并提供一个灵活的经验曲线以及可供其他插件挂钩的事件。

功能

• 持久化玩家经验值，支持多种数据库后端：SQLite（默认）、PostgreSQL、MySQL。
• 可配置的经验曲线：二次函数、线性函数或指数函数。
• 可选的最大等级上限（达到后锁定经验值）。
• 自定义事件：经验值变化/获得/损失、升级/降级。
• 简单的公共 API，方便其他插件读取或修改经验值。

安装

1. 将构建好的 JAR 文件放入服务器的 plugins 文件夹。
2. 启动一次服务器；htlevel.conf 将在插件数据文件夹内生成。
3. 编辑 htlevel.conf 以选择数据库后端和经验曲线，然后重启。

配置（htlevel.conf）

# 数据库后端：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 / 升级
xp.algorithm=quadratic     # quadratic | linear | exponential
xp.maxLevel=100            # <=0 表示无上限

# 二次函数：xp = basePerLevel * L + step * L^2
xp.quadratic.basePerLevel=100
xp.quadratic.step=25

# 线性函数：xp = basePerLevel * L
xp.linear.basePerLevel=150

# 指数累进：base * (multiplier^L - 1)/(multiplier - 1)
xp.exponential.base=100
xp.exponential.multiplier=1.15

开发者 API（示例）

// 访问服务
HTLevelSystem plugin = (HTLevelSystem) pluginManager.getPlugin("HTLevelSystem");
ExperienceService xp = plugin.getExperienceService();

// 给予经验值
xp.addExperience(player.getUuid(), 50);

// 设置绝对经验值
xp.setExperience(player.getUuid(), 1200);

// 读取当前快照
ExperienceSnapshot snap = xp.getOrCreate(player.getUuid());
int level = snap.level();
long totalXp = snap.experience();

// 计算升至某级所需经验值
long xpFor20 = xp.experienceForLevel(20);

监听经验值事件

getEventRegistry().registerGlobal(LevelUpEvent.class, event ->
    getLogger().info("玩家 " + event.getPlayerId() + " 达到了 " + event.getNewLevel() + " 级")
);

getEventRegistry().registerGlobal(ExperienceLossEvent.class, event ->
    getLogger().info("玩家 " + event.getPlayerId() + " 损失了 " + Math.abs(event.getDelta()) + " 经验值")
);

管理员命令

所有命令需要权限 htlevel.admin。

根命令：/htxp（别名：/htlevel、/htlvl）

• /htxp get <玩家名称> — 显示经验值、等级和最大等级上限状态。
• /htxp setxp <玩家名称> <数值> — 设置绝对经验值。
• /htxp givexp <玩家名称> <数值> — 添加经验值。
• /htxp takexp <玩家名称> <数值> — 移除经验值（最低为0；尊重最大等级上限）。
• /htxp setlvl <玩家名称> <等级> — 直接设置等级（经验值自动调整）。
• /htxp givelvl <玩家名称> <等级> — 增加等级（遵守最大等级上限）。
• /htxp takelvl <玩家名称> <等级> — 降低等级（最低为0）。

命令异步执行，并始终遵循配置的经验曲线和 xp.maxLevel 上限。

注释

• 如果设置了 xp.maxLevel，经验值将被限制在最大等级所需范围内；玩家无法继续升级。
• 当事件总线不可用时，经验值仍会更新，但事件会被跳过。