分类条目 GUI

分类条目界面的三件事: 布局文件怎么写, 玩家在界面里能做哪些操作, 以及每个格子能用哪些占位符

分类条目图鉴是 EmakiCodex 的第二套图鉴模型, 与 advancements/*.yml 的原版成就页彼此独立. 你用 /codex codex (或 /codex open) 打开它: 界面布局来自 gui/codex_gui.yml, 内容来自 codex/*.yml

分类文件的完整字段表见配置详解. 界面布局, 交互与占位符如下

打开与权限

项目	说明
命令	`/codex codex`, `/codex open`
权限	`emakicodex.use`, 或拥有 `emakicodex.admin` 直接使用
限制	只能由玩家执行; 没有任何有效分类时不会打开界面
模板 id	`codex_gui`, 模板没有加载时打开失败并记一条警告

条目四态

状态	含义	可执行操作
未解锁	玩家还没有满足任何解锁通路	无; `hidden: true` 的条目此时不出现在界面里
可激活	已经解锁, 但还没有激活	左键激活
已激活	`rewards.attributes` 正在生效	右键领取一次性奖励
已领取	一次性奖励已经发放	无 (属性奖励继续生效)

一句话记住操作顺序: 激活与领取是两个独立操作, 激活只开启属性奖励, 领取只执行一次 rewards.actions. 属性奖励不保存数值, 按当前 codex/*.yml 实时算出, 所以调整配置会同步影响已经激活的玩家

GUI 模板字段

gui/codex_gui.yml 每个文件定义一个模板; id 为模板名 (本模块固定用 codex_gui). GUI 模板结构由 CoreLib 解析

字段	类型	必填	默认值	取值范围	说明
`id`	string	是	—	非空字符串	模板 id; 留空时整份模板会被忽略. 本模块固定加载 `codex_gui`
`gui_type`	string	否	`CHEST`	`InventoryType` 名称 (如 `CHEST`)	容器类型; 填了不认识的值会回退到 `CHEST`
`title`	string / 文本配置	否	`GUI`	MiniMessage 字符串或文本配置节点	界面标题
`rows`	integer	否	`3`	`1` ~ `6`	界面行数, 越界会被夹取到边界值; 只对支持行数的 `gui_type` 生效, 其他类型下为 0
`slots`	map	否	空	键为格子名	格子定义集合
`slots.<name>.slots`	string / list	是	—	槽位表达式 (如 `"0-8"`, `"10-16,19-25"`, `[49]`)	这个格子占用的槽位; 留空则整个格子会被忽略
`slots.<name>.type`	string	否	按格子名推断	见下方布局 type	功能格类型; `codex_gui` 的功能格必须显式写出 (`entry`, `category_tab` 等不在默认推断表内)
`slots.<name>.item`	map	否	空	CoreLib 物品定义 (`source` / `amount` / `components` 等)	格子里的物品; `source` 支持 CoreLib ItemSource 简写
`slots.<name>.sounds`	map	否	空	点击类型 → 音效定义	可选点击音效, 例如 `left_click`

布局 type

写布局时记住一条: 功能格必须显式写 type, 没有 type 的格子只是纯装饰

type	作用
`entry`	条目格. 全部条目格共同构成一页, 越界的格子渲染为空气. 左键激活, 右键领取
`category_tab`	分类标签. 按各分类文件的 `order` 升序填充, 越界渲染为空气, 点击切换分类并回到第 1 页
`page_prev`	上一页. 已在首页时不响应
`page_info`	页码信息. 页码只能放在这里, 不能写进 GUI 标题
`page_next`	下一页. 已在末页时不响应
`close`	关闭界面

默认模板的条目区是 10-16,19-25,28-34, 即每页 21 个条目格; 页大小由实际摆放的 entry 格数量决定, 改布局即改页大小

占位符

条目格可用:

占位符	含义
`%entry_title%`	条目标题; 未解锁时替换为未知条目文案
`%entry_description%`	条目描述; 未解锁时为空
`%entry_state%`	四态之一的状态文案
`%entry_hint%`	当前可执行操作的提示
`%entry_rewards%`	奖励清单, 多行展开 (整行只写这一个占位符才会展开)
`%codex_category%`	分类 id
`%codex_entry%`	条目 id

分类标签可用 %category_id%, %category_title%, %category_state%; 页码格可用 %current_page%, %total_pages%, %entry_count%, %category_title%

默认布局片段

yaml

id: "codex_gui"
gui_type: CHEST
title: "<gradient:#D946EF:#F59E0B>图鉴</gradient>"
rows: 6

slots:
  category_tab:
    type: "category_tab"
    slots: "0-8"
    item:
      components:
        custom_name: "%category_title%"
        lore:
          - "<gray>分类: <white>%category_id%</white></gray>"
          - "%category_state%"

  entry:
    type: "entry"
    slots: "10-16,19-25,28-34"
    item:
      components:
        custom_name: "%entry_title%"
        lore:
          - "%entry_description%"
          - "<gray>状态: %entry_state%</gray>"
          - "%entry_rewards%"
          - "%entry_hint%"

  page_info:
    type: "page_info"
    slots: [49]
    item:
      source: "book"
      components:
        custom_name: "<gray>第 %current_page%/%total_pages% 页</gray>"

未解锁条目会使用锁定图标渲染, 并把标题替换为未知条目文案, 因此不需要为"未知条目"单独配置一个格子

分类条目 GUI ​

打开与权限 ​

条目四态 ​

GUI 模板字段 ​

布局 type ​

占位符 ​

默认布局片段 ​

相关页面 ​