Emaki Series

成就页定义 ​

advancements/*.yml 怎么写: 页面和节点有哪些字段, 节点 key 的规则, 客户端坐标怎么生效, 以及节点完成后执行什么动作

先记住一句话: 一个 advancements/*.yml 文件定义一个原版成就标签页. 下面按页面与节点字段, 注册 key 规则, PacketEvents 坐标通道与完成动作四块来讲

NOTE

这里只讲原版 Advancement. codex/*.yml 的分类条目是另一套模型, 其 category_id 与这里的 page_id 互不替代, 见分类条目 GUI

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

advancements/*.yml ​

基础结构:

yaml
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_idstring否空非空字符串成就页 ID, 同时作为原版 key 的路径前缀; 留空时整页会被跳过. 示例里的节点会注册为 emakicodex:example/root
titleMiniMessage string否page_idMiniMessage标签页标题
backgroundstring否minecraft:textures/gui/advancements/backgrounds/stone.png资源包材质路径原版成就页的背景材质路径, 例如 minecraft:textures/gui/advancements/backgrounds/adventure.png
rootstring否空本地节点 ID根节点的本地 ID, 必须对应 advancements 下面的一个节点; 留空或找不到对应节点时整页会被跳过
advancementsmap否空键为节点本地 ID节点定义集合

节点字段:

字段类型必填默认值取值范围说明
iconItemSource string否minecraft-bookCoreLib ItemSource 短写节点图标, 例如 minecraft-diamond
titleMiniMessage string否节点 IDMiniMessage节点标题
descriptionMiniMessage string否空MiniMessage节点描述
framestring否tasktask / goal / challenge原版框样式; 填了不认识的值会回退到 task
parentstring否空本地节点 ID父节点的本地 ID, 根节点不写. 留空或不写就当成根节点
xnumber否0.0任意 double成就界面上的 X 坐标, 只在 PacketEvents 坐标通道下生效
ynumber否0.0任意 double成就界面上的 Y 坐标, 只在 PacketEvents 坐标通道下生效
hiddenboolean否falsetrue / false是否在完成之前隐藏
toastboolean否truetrue / false完成时是否显示原版 toast
announceboolean否advancement.announce_defaulttrue / false完成时是否全服广播; 不写时取 config.yml 里的 advancement.announce_default
actions.completelist<string>否空CoreLib 动作行节点第一次完成时执行的 CoreLib Action 列表
triggers.entrieslist否空触发器列表自动授予触发器列表, 见事件触发器

节点 key 规则 ​

EmakiCodex 会把节点注册为:

text
emakicodex:<page_id>/<node_id>

例如:

text
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 (跨模块统一执行的指令行) 字符串列表, 会在节点首次完成时执行

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

行为说明:

  • 节点通过命令, API, Action 或触发器完成时, 都会走同一套原版 Advancement 完成链路
  • 对已完成节点重复授予不会再次完成, 也不会重复执行 actions.complete
  • 只有当动作上下文里有玩家时, 才适合执行那些需要玩家作为目标的动作
  • actions.complete 执行时可用的上下文变量: advancement_id (完整 key), advancement_node (节点本地 ID), advancement_title, advancement_page (页 ID)

相关页面 ​