成就页定义

一个 advancements/*.yml 文件定义一个原版成就标签页。本页说明页面与节点字段、注册 key 规则、PacketEvents 坐标通道与完成动作。

自动授予的触发器写法见事件触发器。

advancements/*.yml

基础结构：

page_id: "example"
title: "<gradient:#F59E0B:#EC4899>图鉴示例</gradient>"
background: "minecraft:textures/gui/advancements/backgrounds/adventure.png"
root: "root"

advancements:
  root:
    icon: "minecraft-enchanted_book"
    title: "<gold>图鉴之路</gold>"
    description: "<gray>开启你的探索之旅。</gray>"
    frame: "task"
    x: 0.0
    y: 1.0
    toast: false
    announce: false
    hidden: false
    actions:
      complete: []

页面字段：

字段	类型	说明
page_id	string	成就页 ID，也作为原版 key 的路径前缀。必填；为空时整页会被跳过。示例节点会注册为 emakicodex:example/root。
title	MiniMessage string	标签页标题。省略时回退为 page_id。
background	string	原版成就页背景材质路径，例如 minecraft:textures/gui/advancements/backgrounds/adventure.png。省略时使用 minecraft:textures/gui/advancements/backgrounds/stone.png。
root	string	根节点本地 ID，必须对应 advancements 下的一个节点。
advancements	map	节点定义。key 是节点本地 ID。

节点字段：

字段	类型	默认	说明
icon	ItemSource string	minecraft-book	节点图标，使用 CoreLib ItemSource 简写，例如 minecraft-diamond。
title	MiniMessage string	节点 ID	节点标题。
description	MiniMessage string	空	节点描述。
frame	string	task	原版框样式：task、goal、challenge；未知值回退 task。
parent	string	空	父节点本地 ID；根节点不写。
x	number	0.0	成就界面 X 坐标，仅 PacketEvents 坐标通道生效。
y	number	0.0	成就界面 Y 坐标，仅 PacketEvents 坐标通道生效。
toast	boolean	true	完成时是否显示原版 toast。
announce	boolean	false	完成时是否广播。
hidden	boolean	false	是否隐藏到完成前。
actions.complete	list	空	节点首次完成时执行的 CoreLib Action 列表。
triggers.entries	list	空	自动授予触发器列表，见事件触发器。

节点 key 规则

EmakiCodex 会把节点注册为：

emakicodex:<page_id>/<node_id>

例如：

emakicodex:example/root
emakicodex:example/first_step
emakicodex:example/challenge

命令、API 与 Action 可使用短写 example/first_step，也可使用完整 key emakicodex:example/first_step。

PacketEvents 坐标规则

x / y 只有在满足以下条件时才影响客户端成就界面：

1. 服务器安装并启用 PacketEvents。
2. config.yml > advancement.packet-coordinates: true。
3. 节点至少一个坐标不是 0.0。

注意：

• x=0.0 且 y=0.0 会被视为“未设置”，该节点回退为客户端自动排布。
• 建议同一页所有节点都写坐标，避免显式坐标节点和自动排布节点重叠。
• 未安装 PacketEvents 时，Advancement 仍正常注册，只是不注入坐标。

只要 advancement.enabled: true，玩家加入服务器后会被延迟重推一次成就数据，让坐标与最新注册结果在登录时即刻生效。

完成动作 actions.complete

actions.complete 是 CoreLib Action 字符串列表，会在节点首次完成时执行。

advancements:
  first_step:
    actions:
      complete:
        - "sendmessage text=<green>你迈出了图鉴之路的第一步！</green>"
        - "giveitem item=minecraft-diamond amount=1"

行为说明：

• 节点通过命令、API、Action 或触发器完成时，都会走同一套原版 Advancement 完成链路。
• 对已完成节点重复授予不会再次完成，也不会重复执行 actions.complete。
• 动作上下文有玩家时才适合执行需要玩家目标的动作。

相关页面

• 事件触发器：triggers.entries 的写法、可用事件与条件组示例。
• 配置详解：advancement.enabled、packet-coordinates 等全局开关。
• 命令与权限：授予、撤销与 /codex reload。
• CoreLib 动作：在其他模块的动作链中授予成就。