属性面板与 GUI 配置

这页专门讲 HNAttribute 现在新增的只读玩家属性面板。

如果你想了解：

/hnattr stats [玩家] 到底能看什么
面板里的属性分组、Buff、周期效果是怎么组织的
gui/attribute-stats.yml 应该怎么改
面板物品什么时候可以直接走 HNCore ItemSpec
修改完面板配置后如何生效

就看这页。

1. 面板的定位

这套面板不是编辑器，而是 运行时观察 + 自助排查工具。

它主要解决的是下面这些问题：

玩家想看自己当前最终属性是多少
管理员想确认某条属性为什么会是现在这个值
服主想快速核对 Buff / 周期效果有没有真的挂上
新增属性后，想确认分组展示有没有跟着更新

如果你要排查“Lore 为什么没读出来”，仍然优先用：

text

/hnattr inspect

如果你要排查“最终值为什么是这样”，优先用：

text

/hnattr stats

2. 一个重要变化：GUI 物品现在优先支持 HNCore ItemSpec

当前属性面板里的按钮、摘要物品、来源页摘要物品，在构建时会优先尝试走 HNCore ItemSpec / Resolver；如果当前配置不是 ItemSpec 风格，再回退旧格式。

这意味着你现在可以逐步把 GUI 物品配置统一到 HNCore 的物品模板语义上，同时仍保留原有 YAML 写法。

另外，GUI 物品当前也支持额外的 append-lore，适合在保留公共模板 lore 的同时追加面板侧说明文案。

3. 命令入口

text

/hnattr stats [玩家]

别名：

text

/hnattr panel [玩家]
/hnattr menu [玩家]
/hnattr ui [玩家]

默认行为

玩家自己执行 /hnattr stats：打开自己的属性面板
玩家执行 /hnattr stats Steve：尝试查看目标玩家面板
控制台执行 /hnattr stats Steve：会直接为 Steve 打开面板

权限

查看其他玩家需要：

text

hnattribute.stats.others

当前默认是：

op 拥有
普通玩家默认没有

4. 现在面板里能看到什么

首页：属性总览

首页会展示：

目标玩家头像摘要
属性分组入口
Buff 状态入口
周期效果入口
关闭按钮

当前默认分组是：

攻击
防御
其他

分组详情页

点击某个分组后，会看到该分组里的属性列表：

属性显示名
当前值
默认值
最小值 / 最大值

属性来源页

点击某个属性后，会继续进入来源页。

这一页主要用来回答：

这条属性到底是哪些来源叠出来的？

会显示：

当前值
默认值
来源数量
每个来源的修饰符明细

例如你可能会看到：

default
equipment:mainhand
buff:力量提升

Buff 状态页

这里会显示目标当前正在生效的 Buff：

Buff 名称
等级
剩余时间
来源
影响属性行

周期效果页

这里会显示目标当前的周期实例：

key
来源实体
下次触发时间
当前层数 / 最大层数
已完成次数 / 总次数
标签
失败策略
动作摘要

4. 这套面板最适合什么时候用

场景一：玩家自查

玩家想知道：

为什么自己血量上限变了
为什么攻击力和预期不一样
身上到底挂了哪些 Buff

这时直接 /hnattr stats 就够了。

场景二：管理员排查

管理员想知道：

某个玩家的属性是不是装备给的
Buff 到底有没有进运行时
DOT / HOT 是不是还在跑

这时适合：

text

/hnattr stats <玩家>

场景三：改配置后的回归检查

你新增了：

一个属性
一个派生属性
一个 Buff
一个周期效果

改完后最稳的验证方式通常是：

text

/hnattr reload
/hnattr stats

5. 配置文件在哪里

首次启动后，插件会在数据目录下释放：

text

plugins/HNAttribute/gui/attribute-stats.yml

源码默认资源位置是：

text

src/main/resources/gui/attribute-stats.yml

如果你是服主，真正应该改的是：

text

plugins/HNAttribute/gui/attribute-stats.yml

不是源码资源目录。

6. 改完后怎么生效

有两种方式：

方式一：重启服务器

最稳，但成本高。

方式二：执行重载命令

text

/hnattr reload

当前版本会一起重载：

config.yml
attributes/*.yml
read-patterns.yml
damage_types/*.yml
stages/*.yml
pipelines/*.yml
buffs/*.yml
periodic/*.yml
display.yml
gui/attribute-stats.yml

也就是说，改完属性面板配置后，通常直接：

text

/hnattr reload

就够了。

7. `attribute-stats.yml` 负责什么

这份文件主要负责：

首页标题
分组详情页标题
Buff / 周期页标题
GUI 行数
装饰槽位
内容槽位
返回 / 翻页 / 关闭按钮位置
玩家摘要物品样式
分组按钮图标与文案
分组下归属哪些属性
空状态提示
明细行数限制

简单理解：

布局、分组、按钮文案、展示风格，都在这份文件里。

8. 当前最关键的配置项

`settings.hide-zero-values`

yml

settings:
  hide-zero-values: true

控制是否隐藏值为 0 的属性。

适合：

想让面板更干净
不想把大量默认 0 值属性都展示出来

如果你在调试阶段想“把所有属性都摊开看”，可以临时改成：

yml

hide-zero-values: false

`settings.show-empty-groups`

yml

settings:
  show-empty-groups: true

控制一个分组当前没有可展示属性时，首页是否仍显示它。

适合：

想保持布局稳定
想告诉玩家“这个分组存在，只是当前没有值”

`settings.detail-sort`

yml

settings:
  detail-sort: config_order

可选值：

config_order：按配置顺序展示
value_desc：按数值从高到低展示

`settings.unassigned-group-id`

yml

settings:
  unassigned-group-id: other

没有被任何分组显式写进 attributes 列表的属性，会统一归到这个组。

这意味着：

你新增属性后即使忘了分组
它也不会完全消失
而是先落到 other 这类兜底分组里

9. 分组怎么配

当前默认结构大致是：

yml

groups:
  attack:
    slot: 20
    icon: DIAMOND_SWORD
    name: "&c攻击"
    attributes:
      - attack_damage
      - crit_chance

  defense:
    slot: 22
    icon: SHIELD
    name: "&9防御"
    attributes:
      - defense
      - max_health

你最常改的是这几个字段

`slot`

分组按钮放在哪个槽位。

`icon`

分组按钮显示什么材质。

`name`

分组按钮显示名。

`attributes`

这个分组里有哪些属性。

10. 新增属性后，面板怎么跟着改

如果你新增了一个属性，比如：

yml

lightning_damage:
  display: "&e雷电伤害"

你有三种结果：

情况一：你把它手动放进某个分组

例如：

yml

groups:
  attack:
    attributes:
      - lightning_damage

那它会出现在“攻击”分组。

情况二：你没放进任何分组

那它会落进 unassigned-group-id 对应的兜底分组，比如 other。

情况三：它值一直是 0，而且你开启了 `hide-zero-values`

那它会被隐藏，看起来像“没显示”。

所以新增属性后，如果你在面板里没看到它，优先检查：

这个属性当前是不是有值
有没有被手动分组
是否被 hide-zero-values 隐藏了

11. 面板里的数据分别来自哪里

属性值

来自运行时最终值，而不是只看装备原文。

也就是说，这里会综合：

装备来源
Buff 来源
其他修饰符来源

属性来源页

来自运行时修饰符视图。

它能帮你确认：

是默认值
是装备给的
是 Buff 给的
还是其他系统来源注入的

Buff 页

来自 BuffManager 当前正在生效的 Buff。

周期效果页

来自 PeriodicRuntimeFacade 当前活跃实例视图。

12. 最推荐的配套排查方式

只想看最终结果

text

/hnattr stats

想看最终结果 + 读取层

text

/hnattr inspect
/hnattr stats

想看最终结果 + 来源层

text

/hnattr stats
/hnattr trace <属性ID>

想看 Buff / DOT 是否真的在运行

text

/hnattr stats
/hnattr buffs
/hnattr periodic inspect <key>

13. 最容易踩的坑

坑 1：改错目录

真正应该改的是：

text

plugins/HNAttribute/gui/attribute-stats.yml

不是源码里的 src/main/resources/gui/attribute-stats.yml。

坑 2：改完没 reload

如果你改了面板配置却没执行：

text

/hnattr reload

那游戏里通常不会立刻看到效果。

坑 3：新增属性后没显示

优先检查：

当前值是否为 0
是否被 hide-zero-values 隐藏
是否被放进错误分组
是否只落进了 other

坑 4：玩家看不了别人

这是权限问题，检查：

text

hnattribute.stats.others

1. 面板的定位 ​

2. 一个重要变化：GUI 物品现在优先支持 HNCore ItemSpec ​

3. 命令入口 ​

默认行为 ​

权限 ​

4. 现在面板里能看到什么 ​

首页：属性总览 ​

分组详情页 ​

属性来源页 ​

Buff 状态页 ​

周期效果页 ​

4. 这套面板最适合什么时候用 ​

场景一：玩家自查 ​

场景二：管理员排查 ​

场景三：改配置后的回归检查 ​

5. 配置文件在哪里 ​

6. 改完后怎么生效 ​

方式一：重启服务器 ​

方式二：执行重载命令 ​

7. attribute-stats.yml 负责什么 ​

8. 当前最关键的配置项 ​

settings.hide-zero-values ​

settings.show-empty-groups ​

settings.detail-sort ​

settings.unassigned-group-id ​

9. 分组怎么配 ​

你最常改的是这几个字段 ​

slot ​

icon ​

name ​

attributes ​

10. 新增属性后，面板怎么跟着改 ​

情况一：你把它手动放进某个分组 ​

情况二：你没放进任何分组 ​

情况三：它值一直是 0，而且你开启了 hide-zero-values ​

11. 面板里的数据分别来自哪里 ​

属性值 ​

属性来源页 ​

Buff 页 ​

周期效果页 ​

12. 最推荐的配套排查方式 ​

只想看最终结果 ​

想看最终结果 + 读取层 ​

想看最终结果 + 来源层 ​

想看 Buff / DOT 是否真的在运行 ​

13. 最容易踩的坑 ​

坑 1：改错目录 ​

坑 2：改完没 reload ​

坑 3：新增属性后没显示 ​

坑 4：玩家看不了别人 ​

14. 推荐阅读 ​

1. 面板的定位

2. 一个重要变化：GUI 物品现在优先支持 HNCore ItemSpec

3. 命令入口

默认行为

权限

4. 现在面板里能看到什么

首页：属性总览

分组详情页

属性来源页

Buff 状态页

周期效果页

4. 这套面板最适合什么时候用

场景一：玩家自查

场景二：管理员排查

场景三：改配置后的回归检查

5. 配置文件在哪里

6. 改完后怎么生效

方式一：重启服务器

方式二：执行重载命令

7. `attribute-stats.yml` 负责什么

8. 当前最关键的配置项

`settings.hide-zero-values`

`settings.show-empty-groups`

`settings.detail-sort`

`settings.unassigned-group-id`

9. 分组怎么配

你最常改的是这几个字段

`slot`

`icon`

`name`

`attributes`

10. 新增属性后，面板怎么跟着改

情况一：你把它手动放进某个分组

情况二：你没放进任何分组

情况三：它值一直是 0，而且你开启了 `hide-zero-values`

11. 面板里的数据分别来自哪里

属性值

属性来源页

Buff 页

周期效果页

12. 最推荐的配套排查方式

只想看最终结果

想看最终结果 + 读取层

想看最终结果 + 来源层

想看 Buff / DOT 是否真的在运行

13. 最容易踩的坑

坑 1：改错目录

坑 2：改完没 reload

坑 3：新增属性后没显示

坑 4：玩家看不了别人

14. 推荐阅读