命令与权限
EmakiLevel 的主命令是 /emakilevel，别名为 /elv 和 /elevel。文档示例统一使用最短别名 /elv。
所有子命令都会先检查 emakilevel.use。也就是说，即使是管理员命令，执行者也必须同时拥有 emakilevel.use 和对应的管理权限。
玩家命令
| 命令 | 权限 | 说明 |
|---|---|---|
/elv | emakilevel.use | 查看自己所有已加载等级类型的当前等级、经验、需求经验和进度。只能由玩家执行。 |
/elv info [type] | emakilevel.use | 查看自己指定等级类型；不填 type 时等同 /elv。 |
/elv gui [type] | emakilevel.use | 打开等级 GUI；不填 type 时使用 config.yml > primary_type。别名：/elv open [type]。 |
/elv levelup [type] | emakilevel.levelup | 手动升级指定等级类型；不填 type 时使用 config.yml > primary_type，默认 main。别名：/elv up [type]。 |
/elv top [type] | emakilevel.top | 查看指定等级类型的当前缓存排行榜前 10；不填 type 时使用主等级类型。 |
/elv topgui [type] | emakilevel.top | 打开排行榜 GUI；不填 type 时使用主等级类型。别名：/elv topopen [type]。只能由玩家执行。 |
示例：
text
/elv
/elv info combat
/elv gui main
/elv levelup mining
/elv up main
/elv top combat
/elv topgui combat手动升级会受到 types/<type>.yml 中以下字段影响：
yaml
upgrade:
enabled: true # false 时完全禁止升级
manual_upgrade: true # false 时禁止 /elv levelup
cost:
enabled: false # true 时需要满足经济/材料消耗如果某个类型只想通过获得经验自动升级，可以保留 auto_upgrade: true，并把 manual_upgrade: false。
管理命令
这些命令要求 emakilevel.admin，并且目标玩家必须在线，因为命令实现使用在线玩家名精确匹配。
| 命令 | 权限 | 说明 |
|---|---|---|
/elv giveexp <player> <type> <amount> | emakilevel.admin | 给在线玩家增加经验。别名：addexp。会按该类型配置触发自动升级。 |
/elv takeexp <player> <type> <amount> | emakilevel.admin | 扣除在线玩家当前等级内经验，最低为 0，不会自动降级。别名：removeexp。 |
/elv setexp <player> <type> <amount> | emakilevel.admin | 设置在线玩家当前等级内经验，不直接改变等级。 |
/elv addlevel <player> <type> <amount> | emakilevel.admin | 增加等级，结果会被限制在该类型 start_level 与 max_level 之间。别名：givelevel。 |
/elv takelevel <player> <type> <amount> | emakilevel.admin | 扣除等级，结果不会低于 start_level。别名：removelevel。 |
/elv setlevel <player> <type> <level> | emakilevel.admin | 设置等级，结果会被限制在该类型等级范围内。 |
/elv reset <player> <type> | emakilevel.admin | 重置指定类型：等级回到 start_level，exp 与 total_exp 清零。 |
示例：
text
/elv giveexp Steve combat 250
/elv takeexp Steve mining 30
/elv setexp Steve main 0
/elv addlevel Steve main 5
/elv takelevel Steve combat 1
/elv setlevel Steve fishing 20
/elv reset Steve mining经验与等级操作的差异：
| 操作 | 改变等级 | 改变当前经验 | 改变总经验 | 备注 |
|---|---|---|---|---|
giveexp | 可能自动升级 | 增加并在升级时扣除需求经验 | 增加 | 自动升级取决于类型配置。 |
takeexp | 否 | 扣除到最低 0 | 不变 | 不会降级。 |
setexp | 否 | 设置为指定值 | 不变 | 适合修正当前等级内经验。 |
addlevel | 是 | 清零 | 不变 | 直接改等级，不发放升级奖励。 |
takelevel | 是 | 清零 | 不变 | 直接改等级，不回退奖励。 |
setlevel | 是 | 清零 | 不变 | 用于管理员修正。 |
reset | 是 | 清零 | 清零 | 回到该类型起始状态。 |
重载与调试命令
| 命令 | 权限 | 说明 |
|---|---|---|
/elv reload | emakilevel.reload 或 emakilevel.admin | 保存当前缓存数据，重载主配置、等级类型、需求、来源规则、语言、PDC 和属性桥接，并同步在线玩家。 |
/elv debug requirement <type> <level> | emakilevel.debug 或 emakilevel.admin | 查看某个类型升到目标等级时的需求经验，以及命中的需求来源。 |
/elv debug pdc <player> | emakilevel.debug 或 emakilevel.admin | 触发在线玩家 PDC 重新同步。实现上会同步所有在线玩家。 |
/elv debug | emakilevel.debug 或 emakilevel.admin | 输出 CoreLib 调试状态概览。 |
/elv debug status / on / off | emakilevel.debug 或 emakilevel.admin | CoreLib 通用调试开关：查看状态、全部开启、全部关闭。 |
/elv debug player <player> | emakilevel.debug 或 emakilevel.admin | 切换某个在线玩家的调试输出。 |
/elv debug module <module> | emakilevel.debug 或 emakilevel.admin | 切换调试子模块。EmakiLevel 自身提供 script，另外可用 CoreLib 共享子模块 action、item_operation、variables、placeholder、gui。 |
示例：
text
/elv reload
/elv debug requirement main 10
/elv debug requirement combat 35
/elv debug pdc Steve
/elv debug module scriptdebug requirement 的来源可能是：
| 输出来源 | 含义 |
|---|---|
type.values | types/<type>.yml > requirement.values 中写了目标等级的精确值。 |
type.formula | types/<type>.yml > requirement.formula 覆盖了分组/全局公式。 |
groups.<group>.values | requirements.yml > groups.<group>.values 中写了目标等级的精确值。 |
groups.<group>.formula | 使用了 requirements.yml > groups.<group>.formula。 |
global.values | 使用了 requirements.yml > global.values。 |
global.formula | 使用了 requirements.yml > global.formula。 |
权限节点
| 权限 | 默认 | 覆盖范围 |
|---|---|---|
emakilevel.use | true | 使用主命令和基础查询命令，也是主命令自身的注册权限。所有子命令都会先检查此权限。 |
emakilevel.levelup | true | 使用 /elv levelup / /elv up。 |
emakilevel.top | true | 使用 /elv top 与 /elv topgui / /elv topopen。 |
emakilevel.reload | op | 使用 /elv reload。 |
emakilevel.debug | op | 使用 /elv debug requirement 与 /elv debug pdc。 |
emakilevel.admin | op | 使用经验/等级管理命令，并可代替 reload/debug 的专用权限。 |
常见 LuckPerms 示例：
text
/lp group default permission set emakilevel.use true
/lp group default permission set emakilevel.levelup true
/lp group default permission set emakilevel.top true
/lp group admin permission set emakilevel.admin true
/lp group admin permission set emakilevel.reload true
/lp group admin permission set emakilevel.debug true常见失败原因
命令和 API 返回的失败原因是固定英文 ID，语言文件会把常用原因翻译成玩家可读文本。
| 原因 ID | 常见场景 |
|---|---|
player_not_found | 目标玩家不存在、离线，或 API 调用没有有效 UUID。 |
player_data_unavailable | 玩家等级数据尚未加载或已卸载。 |
type_not_found | type 不存在，或者 sources/*.yml / Action 中写错类型 ID。 |
type_disabled | 等级类型存在但 enabled: false。 |
invalid_amount | 经验或等级数量小于等于 0，或设置经验时传入负数。 |
daily_cap_reached | 该类型当日经验额度已用尽，见 config.yml > daily_caps。 |
upgrade_disabled | upgrade.enabled: false。 |
manual_upgrade_disabled | 玩家手动执行 /elv levelup，但类型禁用了手动升级。 |
max_level | 已达到该类型 max_level。 |
not_enough_exp | 当前等级内经验不足以升到下一级。 |
not_enough_money | 升级经济消耗不足。 |
not_enough_material | 升级材料消耗不足。 |
cost_compensation_failed | 升级消耗已扣除但后续步骤失败，且退还消耗时出错。 |
invalid_requirement | 需求经验公式或配置结果小于等于 0，无法升级。 |
通过公开 API 异步写入时还可能返回以下原因：api_unavailable、not_entity_owner、player_offline、owner_schedule_retired、owner_schedule_rejected。这些原因与线程归属调度有关，不由配置引起。