配置详解

EmakiCodex 各份配置文件里的字段, 每个字段的默认值和作用如下

EmakiCodex 的配置分为主配置, 原版成就页配置, 分类条目配置, GUI 模板和语言文件. config.yml, codex/*.yml, gui/codex_gui.yml 与 lang/*.yml 各管一块, 先记住它们各自的分工:

• config.yml: 全局开关, 默认资源是否释放, 原版成就注册和 PacketEvents 坐标通道
• codex/*.yml: 分类, 条目, 解锁条件和奖励; 与 advancements/*.yml 的 page_id 是独立命名空间
• gui/codex_gui.yml: 分类条目 GUI 布局和占位符
• lang/*.yml: 命令, GUI 与控制台提示

advancements/*.yml 的页面与节点字段见成就页定义, 分类条目 GUI 见分类条目 GUI, 两类自动解锁触发器见事件触发器

config.yml

默认主配置:

version: "1.1.6"
language: "zh_CN"
release_default_data: true
op_bypass: false

advancement:
  enabled: true
  announce_default: false
  remove_on_disable: true
  packet_coordinates: true
  triggers_enabled: true

字段说明 (必填=否 表示源码带默认值, 可省略):

字段	类型	必填	默认值	取值范围	说明
version	string	否	1.1.6	任意字符串	这是配置结构的版本标记, 默认资源的版本由资源同步流程维护. 源码内部还有一个迁移常量是 1.0.14, 不要和它混用
language	string	否	zh_CN	lang/<language>.yml 的文件名	指定使用 lang/<language>.yml 这个语言文件. 留空或文件缺失时回退到 zh_CN
release_default_data	boolean	否	true	true / false	填 true 且对应文件缺失时, 释放内置的 advancements/example_page.yml 与 codex/example_category.yml 等默认数据
op_bypass	boolean	否	false	true / false	填 true 时 OP 可以跳过命令的权限检查, 填 false 时 OP 也必须拥有对应权限节点
advancement.enabled	boolean	否	true	true / false	原版成就注册的总开关. 关掉后不再加载和注册成就, /codex reload 会移除本插件已经注册的节点
advancement.announce_default	boolean	否	false	true / false	节点自己没有单独配 announce 时, 是否默认全服广播
advancement.remove_on_disable	boolean	否	true	true / false	插件被禁用时是否移除已经注册的动态成就. /codex reload 的重建流程总是先清掉本插件命名空间再注册, 不受这个开关控制
advancement.packet_coordinates	boolean	否	true	true / false	安装了 PacketEvents 时, 是否把节点 x / y 写进客户端成就树. 这个值在插件启用时构造发包网关时读取, 运行中改了要重启才生效
advancement.triggers_enabled	boolean	否	true	true / false	是否开启按游戏事件自动授予 (节点 triggers.entries 与条目 unlock.triggers). 关掉后仍然可以用命令, API 或 CoreLib 动作手动授予

配置示例 (关闭自动触发, 保留坐标注入):

language: "en_US"
op_bypass: true

advancement:
  enabled: true
  packet_coordinates: true
  triggers_enabled: false

分类条目文件 codex/*.yml

每个文件定义一个 GUI 分类; 文件名不参与 id 识别, 分类 id 取 category_id. 条目的复合 id 固定为 <category_id>/<entry_id>, 例如 example/first_blood

随插件发布的默认值片段 (节选自 codex/example_category.yml):

category_id: "example"
title: "<gold>试炼图鉴</gold>"
icon: "minecraft-book"
order: 100

entries:
  first_blood:
    title: "<yellow>初次讨伐</yellow>"
    description: "<gray>击败任意敌对生物。</gray>"
    icon: "minecraft-iron_sword"
    hidden: false
    unlock:
      triggers:
        - event: "entity_kill"
      advancements: []
    rewards:
      attributes:
        physical_attack: 2.0
      actions:
        - "send_message text=<green>已领取初次讨伐的奖励。</green>"

字段说明 (entries 下每个条目都可用以下键):

字段	类型	必填	默认值	取值范围	说明
category_id	string	否	空	非空字符串 (会归一化为 id)	分类 id. 留空时整份文件会被跳过
title	MiniMessage string	否	category_id	MiniMessage	分类标题, 界面上的分类标签会用到它
icon	ItemSource string	否	minecraft-book	CoreLib ItemSource 短写	分类图标
order	integer	否	100	整数	分类标签的排序权重, 越小越靠前; 权重相同时再按 category_id 排序
entries	map	否	空	键为条目 id	条目定义集合
entries.<id>.title	MiniMessage string	否	条目 id	MiniMessage	条目标题
entries.<id>.description	MiniMessage string	否	空	MiniMessage	条目描述
entries.<id>.icon	ItemSource string	否	minecraft-book	CoreLib ItemSource 短写	条目图标; 条目未解锁时改用锁定图标渲染
entries.<id>.hidden	boolean	否	false	true / false	未解锁时是否从界面里藏起来; 填 false 时会显示成未知条目
entries.<id>.unlock.triggers	list	否	空	触发器列表	共享玩法事件触发器, 见事件触发器
entries.<id>.unlock.triggers[].event	string	是	—	CoreLib 事件 ID	触发器事件 ID (会归一化); 留空则跳过这一条
entries.<id>.unlock.triggers[].condition	CoreLib condition group	否	空	condition.type + condition.entries	可选项; 省略时只要事件发生就算命中
entries.<id>.unlock.advancements	list<string>	否	空	原版 advancement key	任意一个命中就能解锁; 取值会先去掉首尾空格再去重
entries.<id>.rewards.attributes	map<string,double>	否	空	属性 id → double (非 0.0)	条目激活后实时提供, 不会把数值快照写进玩家文件; 值为 0.0 的项会被丢掉, 同名的键相加
entries.<id>.rewards.actions	list<string>	否	空	CoreLib 动作行	领取时只执行一次的 CoreLib Action; 领取状态先写进玩家文件, 然后才执行动作

一句话记住这套解锁逻辑: unlock.triggers 与 unlock.advancements 是并列通路, 任一通路成功即可把条目变为"已解锁". 解锁, 激活, 领取是三件独立的事: 解锁不会自动激活, 激活也不会自动执行一次性领取动作

使用示例 (两个条目, 分别走触发器与 advancement 解锁):

category_id: "example"
title: "<gold>试炼图鉴</gold>"
icon: "minecraft-book"
order: 100

entries:
  first_blood:
    title: "<yellow>初次讨伐</yellow>"
    description: "<gray>击败任意敌对生物。</gray>"
    icon: "minecraft-iron_sword"
    hidden: false
    unlock:
      triggers:
        - event: "entity_kill"
    rewards:
      attributes:
        physical_attack: 2.0
      actions:
        - "send_message text=<green>已领取初次讨伐的奖励。</green>"

  master_miner:
    title: "<aqua>掘进者</aqua>"
    icon: "minecraft-diamond_pickaxe"
    hidden: true
    unlock:
      triggers:
        - event: "block_break"
          condition:
            type: "all_of"
            entries:
              - '%block_type% == "DIAMOND_ORE"'
      advancements:
        - "emakicodex:example/first_step"
    rewards:
      attributes:
        max_health: 5.0

语言文件

语言文件位于 lang/*.yml. 默认包含:

version: "1.1.6"
general:
  prefix: "<gray>[ <gradient:#D946EF:#F59E0B>EmakiCodex</gradient> ]</gray>"
  no_permission: "<red>你没有权限执行此操作。</red>"

command:
  help:
    commands:
      reload: "重载配置、重注册成就并给全员重发成就"
      grant: "授予玩家成就"
      revoke: "撤销玩家成就"
      debug: "管理 Debug 模式"

语言文本支持 MiniMessage (一套用标签写颜色和样式的文本格式). 改完执行 /codex reload 就能生效

修改 config.yml, advancements/*.yml, codex/*.yml, gui/codex_gui.yml 与 lang/*.yml 后, 执行 /codex reload 应用变更. 玩家的 data/<uuid>.yml 不会因 reload 清空, 放心重载

相关页面

• 成就页定义: advancements/*.yml 的页面与节点字段, key 规则与完成动作
• 分类条目 GUI: 分类文件与 GUI type, 四态状态和奖励操作
• 事件触发器: 原版 triggers.entries 与分类 unlock.triggers 的写法, 可用事件与条件组示例
• 命令与权限: /codex reload, 原版授予/撤销和分类条目管理
• CoreLib 动作: 在动作链中授予, 撤销或广播成就