命令与权限

全部 /codex 子命令, 每一条需要什么权限, 以及几类常见报错的含义如下

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