命令与权限

EmakiCodex 的主命令是 /codex，别名为 /ecodex。codex 与 open 都会打开分类条目图鉴 GUI；文档示例统一使用 /codex。

普通入口检查 emakicodex.use；emakicodex.admin 可作为 use、reload 和 debug 的旁路。所有管理目标目前都要求在线玩家。

命令列表

命令	权限	说明
/codex / /codex help	emakicodex.use	显示帮助。
/codex codex / /codex open	emakicodex.use 或 emakicodex.admin	打开分类条目图鉴 GUI。
/codex reload	emakicodex.reload 或 emakicodex.admin	重载配置、语言、原版成就页和分类条目，重建注册内容，并尝试向在线玩家重推。
/codex grant <player> <advId>	emakicodex.admin	授予在线玩家一个原版 Codex Advancement 节点。
/codex revoke <player> <advId>	emakicodex.admin	撤销在线玩家一个原版 Codex Advancement 节点。
/codex admin unlock <player> <category/entry>	emakicodex.admin	直接解锁一个分类条目，不执行激活或领取。
/codex admin reset <player> [category/entry]	emakicodex.admin	重置一个分类条目，省略复合 id 时重置该玩家全部分类条目状态。
/codex debug ...	emakicodex.debug 或 emakicodex.admin	管理 advancement debug 模块。具体子命令由 CoreLib DebugCommand 提供。

示例

/codex
/codex codex
/codex open
/codex reload
/codex grant Steve example/first_step
/codex grant Steve emakicodex:example/challenge
/codex revoke Steve example/first_step
/codex admin unlock Steve example/first_blood
/codex admin reset Steve example/first_blood
/codex admin reset Steve
/codex debug advancement on
/codex debug advancement off

grant 与 revoke 的目标玩家必须在线，因为当前实现使用在线玩家名精确匹配。admin unlock/reset 的目标玩家也必须在线。原版节点的 advId 支持两种写法：

写法	示例	说明
page/node	example/first_step	推荐给服主使用的短写。
完整 NamespacedKey	emakicodex:example/first_step	与底层原版 Advancement key 一致。

分类条目命令不使用原版 NamespacedKey，而使用 codex/*.yml 的复合 id：

<category_id>/<entry_id>

例如 example/first_blood。admin unlock 只改变“已解锁”状态；GUI 中的左键激活会另外开启属性奖励，右键领取才会执行一次性 rewards.actions。

reload 行为

/codex reload 会执行以下工作：

1. 释放缺失的默认资源，受 config.yml > release_default_data 控制。
2. 重新读取 config.yml、lang/*.yml、advancements/*.yml、codex/*.yml 与 GUI 模板。
3. 移除并重新注册 EmakiCodex 命名空间下的动态 Advancement，并重建分类条目与奖励提供器。
4. 如果 PacketEvents 可用，向在线玩家重推原版成就树；否则在线玩家可能需要重新登录才能看到原版成就界面变化。
5. 玩家分类条目数据保留在 data/<uuid>.yml，奖励属性按新配置重新推导。

权限节点

权限	默认	覆盖范围
emakicodex.use	true	使用帮助、打开分类条目 GUI（codex/open）和普通入口。
emakicodex.reload	op	使用 /codex reload。可被 emakicodex.admin 代替。
emakicodex.debug	op	使用 /codex debug ...。可被 emakicodex.admin 代替。
emakicodex.admin	op	使用 grant、revoke、admin unlock/reset，并可代替 use/reload/debug 专用权限。

常见 LuckPerms 示例：

/lp group default permission set emakicodex.use true
/lp group admin permission set emakicodex.admin true
/lp group admin permission set emakicodex.reload true
/lp group admin permission set emakicodex.debug true

常见失败原因

场景	说明
Player not found	grant / revoke 的目标玩家不在线，或玩家名不完全匹配。
Advancement ... 未注册或状态无变化	成就 ID 写错、页面未成功加载，或授予/撤销时玩家当前进度没有变化。
category/entry 找不到	分类文件未加载、复合 id 拼写错误，或条目仍未解锁。
admin unlock 成功但没有属性	unlock 只改变解锁态；还要在 GUI 左键激活，且属性奖励来自 rewards.attributes。
右键领取失败	条目未解锁、没有 rewards.actions，或已经领取过；领取是一次性状态。
在线玩家看不到 reload 后的新成就树	未安装 PacketEvents 或重推失败时，在线玩家需要重新登录。
节点坐标不生效	需要安装 PacketEvents，并开启 advancement.packet_coordinates: true。