gui.yml

gui.yml 负责成就 GUI 的展示层：标题、分类按钮、详情页、翻页按钮、返回按钮、进度条、状态文案，都在这里。

如果你想改的是：

• 主界面长什么样
• 分类页成就图标怎么显示
• 隐藏成就显示成什么
• 详情页的描述顺序和奖励信息

那就看这份。

主要分组

分组	用途
titles	主界面 / 分类页 / 详情页标题
main-gui	主界面大小、分类物品、玩家头颅、边框
category-gui	分类页成就物品和导航按钮
detail-gui	详情页布局、背景、进度信息、奖励信息
progress-bar	进度条长度、字符和颜色
status-text	已解锁 / 未解锁 / 是 / 否 文案

titles

titles:
  main: "&6&l成就系统"
  category: "&e成就 - "
  detail: "&b成就详情 - "

这一组只是标题壳子：

• 分类名、成就名会在运行时自己拼上去

main-gui

main-gui:
  size: auto
  category-item:
    lore:
      - "{description}"
      - ""
      - "&7已解锁: &e{unlocked}&7/&e{total}"
      - "&7完成度: &e{percentage}%"

几个关键点：

• size: auto 表示按分类数量自动调整界面大小
• category-item.lore 支持 {description}、{unlocked}、{total}、{percentage}
• player-head 会显示当前玩家自己的总完成度

category-gui

这里最关键的是三种状态：

• unlocked
• locked
• hidden

category-gui:
  achievement-item:
    unlocked:
      name-prefix: "&a✓ "
    locked:
      name-prefix: "&c✗ "
    hidden:
      material: "BEDROCK"
      name: "&8&l???"

这三种状态正好对应源码里的：

• 已完成
• 未完成
• 隐藏成就

如果你用了 hidden 或 hiddenUntilComplete，玩家在分类页看到的就是这套表现。

导航按钮

当前默认导航位是：

• 上一页：45
• 页码信息：47
• 返回：49
• 下一页：53

如果你想改分页按钮位置，优先从这组下手。

detail-gui

详情页默认是 27 格，核心是中间三块：

• achievement-info
• progress-info
• reward-info

detail-gui:
  achievement-info:
    slot: 13
  progress-info:
    slot: 11
  reward-info:
    slot: 15

这个布局很适合标准成就详情页。如果你只是想换材质、改 lore、调进度条，不需要重做整个界面结构。

progress-bar

progress-bar:
  length: 20
  filled-char: "█"
  empty-char: "█"
  filled-color: "&a"
  empty-color: "&7"

这组会直接影响：

• 主界面玩家头颅的总进度条
• 分类页成就进度条
• 详情页进度条

IA / CustomModelData 支持

当前 GUI 配置里多处都支持这种写法：

material: "paper{model-data=10001}"

这类写法更适合：

• ItemsAdder 图标
• 自定义材质图标
• 高辨识度分类页按钮

使用建议

• 先只改文字和材质，别一上来就把整套 slot 逻辑全改乱。
• 隐藏成就的表现尽量和普通未完成成就明显区分开。
• 主界面如果分类不多，保留 size: auto 最省心。
• 进度条长度别写得太长，否则描述区会很挤。

常见问题

GUI 里图标不显示

优先检查：

• 材质名是否和当前服务端版本兼容
• 是否用了 CustomModelData 但客户端资源包没跟上
• icon / iconUnlocked / iconLocked 是否填错

隐藏成就看起来和普通未完成成就一样

那通常是你只改了普通 locked，没改 hidden。

隐藏成就的材质、名称、描述是单独一套配置。