EmakiCodex

先弄清 EmakiCodex 模块做什么, 用到哪些文件, 装好之后先跑哪几条命令验证

EmakiCodex 里有两套各自独立的图鉴, 先分清它们. 第一套是 advancements/*.yml, 定义并注册原版成就页和节点, 成就 (Advancement) 就是 Minecraft 自带的进度系统. 第二套是 codex/*.yml, 定义分类, 条目, 解锁条件和奖励, 由独立的分类条目 GUI 展示

两套模型可以通过 Advancement 解锁关联, 但 page_id 与 category_id 不能互相代替

装了 PacketEvents (一个负责收发网络封包的依赖插件) 时, EmakiCodex 会额外启用两件事: 客户端成就树坐标注入, 以及向在线玩家重推 (重新把成就数据推送给客户端)

没装 PacketEvents 也不影响使用: 原版成就仍会注册, 只是节点位置由客户端按 parent 树自动排布, 在线玩家可能需要重新登录才能看到刚重载后的成就树变化

分类条目 GUI 不依赖 PacketEvents, 但它的奖励动作仍通过 CoreLib 执行, 属性奖励按当前配置实时算出

基本信息

项目	值
模块版本 (POM/runtime)	1.1.6
API Jar	emaki-codex-api-1.1.5.jar
默认配置结构版本	1.1.6
主类	emaki.jiuwu.craft.codex.EmakiCodexPlugin
主命令	/codex
别名	/ecodex
硬依赖	EmakiCoreLib
软依赖	EmakiAttribute, PlaceholderAPI, PacketEvents, MythicMobs
最低服务端	Paper 26.1+ (api-version: 26.1, folia-supported: true)
Java	Java 25
主要权限	emakicodex.use (默认 true), emakicodex.reload (op), emakicodex.debug (op), emakicodex.admin (op)

模块 runtime 与默认 config.yml 的版本值是 1.1.6, API 构件另为 1.1.5; 源码内部的 AppConfig.CURRENT_VERSION = "1.0.14" 是配置迁移结构常量, 不是插件的发布版本, 也不是 API 构件的版本号

功能页面

页面	内容
命令与权限	/codex, /ecodex 的可用子命令, 权限和示例
配置详解	config.yml, codex/*.yml, gui/codex_gui.yml 与 lang/*.yml 的入口和版本号含义
成就页定义	advancements/*.yml 的页面与节点字段, 节点 key 规则, 坐标规则与完成动作
分类条目 GUI	codex/*.yml 分类与条目, 四态进度, 激活与一次性领取, 布局 type 和占位符
事件触发器	原版 Advancement 的 triggers.entries 与分类条目的 unlock triggers
CoreLib 动作	EmakiCodex 注册到 CoreLib ActionRegistry 的七个动作段
API 与集成	第三方插件通过 emaki-codex-api 调用原版 Advancement 层的方式

核心能力

• 原版 Advancement 图鉴: 一个 advancements/*.yml 文件就是一个原版成就标签页, 节点 key 形如 emakicodex:<page>/<node>
• 分类条目图鉴: 一个 codex/*.yml 文件定义一个 GUI 分类, 条目复合 id 为 <category_id>/<entry_id>, 分类按 order 排序
• 四态条目进度: 条目状态依次为未解锁, 可激活, 已激活, 已领取; 激活与领取是两个独立操作
• 两条解锁通路: unlock.triggers 监听共享事件, unlock.advancements 监听原版 Advancement, 任一命中即可解锁
• 两类奖励: rewards.attributes 在激活后按当前配置实时提供属性; rewards.actions 在右键领取时只执行一次
• 手动授予/撤销: 管理员可用 /codex grant 与 /codex revoke 管理在线玩家原版节点进度; admin unlock/reset 管理分类条目状态
• 动作链授予与通知: 其他插件可在 CoreLib Action 中调用五个 Advancement 操作, codex_show_toast 和 codex_broadcast_achievement
• 事件触发器: 原版节点可配置 triggers.entries, 分类条目可配置 unlock.triggers, 两者使用共享 gameplay 事件与条件
• 完成动作: 原版节点完成后执行 actions.complete; 分类条目领取时执行 rewards.actions
• PacketEvents 坐标通道: 安装 PacketEvents 且开启 advancement.packet_coordinates 时, 原版节点 x / y 会写入客户端成就界面位置

文件结构

服务器运行后, EmakiCodex 主要使用以下文件:

plugins/EmakiCodex/
├─ config.yml
├─ advancements/
│  └─ example_page.yml
├─ codex/
│  └─ example_category.yml
├─ gui/
│  └─ codex_gui.yml
├─ data/
│  └─ <player-uuid>.yml
└─ lang/
   ├─ zh_CN.yml
   └─ en_US.yml

路径	说明
config.yml	这是主配置, 控制默认资源是否释放, 原版成就是否注册, 是否注入 PacketEvents 坐标, 以及触发器总开关. 它的 version 当前是 1.1.6
advancements/*.yml	原版成就页配置. 每个文件定义一个成就页, 里面有一个根节点和任意数量的子节点
codex/*.yml	分类条目配置. 每个文件定义一个 GUI 分类, 条目复合 id 为 <category_id>/<entry_id>
gui/codex_gui.yml	分类条目界面的模板. 功能格必须显式写出 type
data/<uuid>.yml	记录每个玩家的解锁, 激活和领取状态. 属性数值不写进这里, 按当前分类配置实时算出
lang/*.yml	命令, 界面, 重载和控制台用到的提示文本

快速开始

照着下面的顺序做, 7 步就能跑起来:

1. 把 EmakiCoreLib-*.jar 与 EmakiCodex-*.jar 放入服务器 plugins/
2. 不要把 emaki-codex-api-*.jar 放进服务器 plugins/; API Jar 只给开发者作为编译依赖使用
3. 首次启动后查看 plugins/EmakiCodex/advancements/example_page.yml
4. 修改或新增成就页后执行:

/codex reload

5. 打开分类条目图鉴 GUI:

/codex codex

6. 测试授予原版示例节点:

/codex grant Steve example/first_step

7. 管理分类条目时使用复合 id:

/codex admin unlock Steve example/first_blood
/codex admin reset Steve example/first_blood

完整 key 也可写成:

/codex grant Steve emakicodex:example/first_step

两套配置模型速览

你需要记住的分工很简单. 一个 advancements/*.yml 定义一个原版成就页:

• 页面级: page_id (key 路径前缀), title, background, root
• 节点级: icon, title, description, frame, parent, x / y, toast, announce, hidden
• 节点完成动作写在 actions.complete, 事件触发器写在 triggers.entries

一个 codex/*.yml 定义一个分类条目页:

• 分类级: category_id, title, icon, order, entries
• 条目级: title, description, icon, hidden, unlock.triggers, unlock.advancements, rewards.attributes, rewards.actions
• 条目 id 在命令, GUI 状态和数据文件中使用 <category_id>/<entry_id> 复合形式

两类触发条件都使用 CoreLib 标准条件组: condition.type + condition.entries. 原版节点会注册为 emakicodex:<page_id>/<node_id>; 完整字段见成就页定义与分类条目 GUI

使用提示

• 原版 Advancement 与分类条目 GUI 是两套独立状态; 不要把 advancements/<page_id> 当作 codex/<category_id> 使用
• 原版节点完成条件统一由 Codex 授予: 命令, Action, 公开 API 或触发器会奖励内部 codex criterion
• actions.complete 只会在原版节点首次完成时触发; 分类条目的 rewards.actions 只会在一次性领取时触发
• 分类条目的 rewards.attributes 不保存数值, 按当前配置实时算出; 修改奖励配置会影响已激活玩家
• 如果开启原版成就坐标, 建议同一成就页全部节点都配置 x / y, 避免"部分显式坐标 + 部分自动排布"导致重叠