EmakiCodex

EmakiCodex 同时包含两套独立的图鉴模型：advancements/*.yml 定义并注册原版 Advancement 页面与节点；codex/*.yml 定义分类、条目、解锁条件和奖励，由独立的分类条目 GUI 展示。两套模型可以通过 Advancement 解锁关联，但 page_id 与 category_id 不互相替代。

安装 PacketEvents 时，EmakiCodex 会额外启用客户端成就树坐标注入与在线玩家重推能力；未安装 PacketEvents 时，原版成就仍会注册，但节点位置由客户端按 parent 树自动排布，在线玩家可能需要重新登录才能看到刚重载后的成就树变化。分类条目 GUI 不依赖 PacketEvents，但其奖励动作仍通过 CoreLib 执行，属性奖励由当前配置实时推导。

基本信息

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

POM/runtime/API 与默认 config.yml 的版本值是 1.1.0；源码内部的 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	主配置，控制默认资源释放、Advancement 注册、PacketEvents 坐标注入和触发器总开关；version 当前为 1.1.0。
advancements/*.yml	原版成就页配置。每个文件定义一个页面、一个根节点和任意数量子节点。
codex/*.yml	分类条目配置。每个文件定义一个 GUI 分类，条目复合 id 为 <category_id>/<entry_id>。
gui/codex_gui.yml	分类条目 GUI 模板；功能格必须显式写 type。
data/<uuid>.yml	每个玩家的解锁、激活和领取状态；属性数值不写入，按当前分类配置实时推导。
lang/*.yml	命令、GUI、重载和控制台提示文本。

快速开始

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，避免“部分显式坐标 + 部分自动排布”导致重叠。