GUI 与玩家面板配置 | HN 系列 Wiki

这页专门讲 HNEconomy 当前版本的玩家 GUI 配置。

如果你想改：

/money 打开的个人经济面板
/pay 无参数时的目标选择页
转账时的货币选择页
快捷金额按钮显示什么金额
按钮放在哪个槽位、用什么材质、写什么文案

就看这页。

1. 当前有哪些 GUI 文件

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

plugins/HNEconomy/gui/player-economy.yml
plugins/HNEconomy/gui/pay-player-list.yml
plugins/HNEconomy/gui/pay-currency.yml
plugins/HNEconomy/gui/pay-amount.yml

它们分别对应：

`player-economy.yml`

控制 /money 无参数时打开的个人经济总览面板。

主要内容包括：

玩家头像信息
主货币展示
额外货币分页展示
打开转账流程按钮
切换拒收 / 接收状态按钮
分页按钮、刷新按钮、关闭按钮

`pay-player-list.yml`

控制 /pay 无参数时打开的在线玩家列表面板。

主要内容包括：

顶部汇总信息
在线玩家头像列表
返回按钮
翻页按钮
空列表提示

`pay-currency.yml`

控制选择目标玩家后打开的货币选择页。

主要内容包括：

目标玩家信息
当前可选货币数
货币列表
返回目标页按钮
翻页按钮

`pay-amount.yml`

控制选择货币后打开的快捷金额面板。

主要内容包括：

付款人信息
收款目标信息
快捷金额按钮
返回 / 刷新 / 关闭按钮
点击金额后的确认流程

2. 当前玩家转账 GUI 流程

当前版本的可视化转账流程是：

text

玩家执行 /pay
→ 目标玩家页（pay-player-list.yml）
→ 货币选择页（pay-currency.yml）
→ 金额选择页（pay-amount.yml）
→ 确认转账

这里要注意两点：

货币选择已经是独立一步，不是直接从目标页跳金额页。
确认页不是单独 yml 文件，而是金额页内部触发的确认对话逻辑。

3. 修改完后怎么生效

有两种方式：

方式一：重启服务器

最稳妥，但成本高。

方式二：执行重载命令

text

/hneco reload

当前版本会一起重载：

config.yml
currencies.yml
gui/*.yml

也就是说，改完 GUI 文件后，通常直接 /hneco reload 就够了。

4. 当前 GUI 文件的结构长什么样

当前版本的 GUI 配置不是旧式的 fill / slots / slot-lists 平铺结构，而是更接近下面这种：

yml

gui:
  title: '&6标题'
  size: 54
  cancel-click: true

  layout:
    content-slots:
      - 19
      - 20
      - 21

  items:
    border-fill:
      fill-slots:
        - 0
        - 1
      material: BLACK_STAINED_GLASS_PANE
      name: ' '

    refresh:
      slot: 47
      material: CLOCK
      name: '&b刷新'
      lore:
        - '&7重新读取当前页面'

而 pay-amount.yml 还会额外带一段快捷金额配置：

yml

quick-amounts:
  values:
    - 10
    - 100
    - 1000

也就是说：

面板元信息在 gui.*
列表槽位在 gui.layout.content-slots
单个按钮通常用 slot
填充物品通常用 fill-slots
金额页的快捷金额在顶层 quick-amounts.values

5. `gui.title`

yml

gui:
  title: '&6个人经济面板 &8[{page}/{total_pages}]'

控制面板标题。

常见占位符

{page}：当前页
{total_pages}：总页数
{target_name}：目标玩家名

6. `gui.size`

yml

gui:
  size: 54

必须满足：

是 9 的倍数
范围在 9 ~ 54

通常玩家列表、货币选择、金额面板都建议保持 54，比较容易排版。

7. `gui.cancel-click`

yml

gui:
  cancel-click: true

控制是否阻止玩家在 GUI 中进行普通背包点击行为。

通常建议保持：

yml

true

避免玩家误拿面板物品。

8. `gui.layout.content-slots`

yml

gui:
  layout:
    content-slots:
      - 19
      - 20
      - 21

用于定义列表区域。

当前主要有几类实际用途：

player-economy.yml：额外货币展示位
pay-player-list.yml：在线玩家展示位
pay-currency.yml：货币展示位
pay-amount.yml：快捷金额按钮位

注意

槽位数量越多，一页能显示的内容越多
如果槽位数量比实际数据少，多出来的数据会分页
如果槽位数量比实际数据多，空位会保持填充物品

9. `gui.items`

gui.items 下每个 key 对应一个可渲染物品模板。

常见字段如下：

yml

items:
  refresh:
    slot: 47
    material: CLOCK
    name: '&b刷新'
    lore:
      - '&7重新读取信息'

  border-fill:
    fill-slots:
      - 0
      - 1
    material: BLACK_STAINED_GLASS_PANE
    name: ' '

`slot`

单个固定按钮的位置。

例如：

头像信息
返回按钮
刷新按钮
关闭按钮

`fill-slots`

批量填充槽位。

通常用于：

外圈边框
内容空白区

`material`

物品材质。

`name`

显示名，支持颜色代码和占位符。

`lore`

Lore 列表，支持多行文本和占位符。

10. `pay-amount.yml` 里的 `quick-amounts.values`

金额面板里最常改的是：

yml

quick-amounts:
  values:
    - 10
    - 100
    - 1000

你可以改成：

yml

quick-amounts:
  values:
    - 5
    - 50
    - 500
    - 5000

这里有两个要点

1）金额数量最好和 `content-slots` 数量对应

比如：

yml

gui:
  layout:
    content-slots:
      - 28
      - 30
      - 32
      - 34

就很适合配 4 个金额。

2）金额仍然会受业务规则限制

即使你在 GUI 里写了很大的金额，也不代表玩家一定能点成功。

它仍然会受这些规则影响：

pay.min-amount
pay.max-amount
货币精度
货币是否允许玩家转账
玩家余额是否足够
收款目标是否拒收
手续费与总支出校验

如果不符合规则，金额按钮会显示成“不可用金额”。

11. 当前模板里常见的占位符

下面这些是当前 shipped GUI 文件里真正常见的占位符。

A. HNCore 经济命名空间占位符

这类占位符在 GUI 模板中通常写成：

{economy.pay_receive_text}
{economy.currency_display}
{economy.balance_formatted}
{economy.rank}

它们由 HNCore 的 economy 占位符命名空间提供。

B. 页面流程类占位符

{page}
{current_page}
{total_pages}
{target_page}

C. 玩家 / 目标类占位符

{player_name}
{target_name}
{target_count}
{receive_status}
{back_target}
{back_description}

D. 货币 / 余额类占位符

{currency_name}
{currency_id}
{currency_count}
{balance}
{description}
{scale}
{allow_negative}
{max_balance}
{extra_currency_count}
{pay_currency_count}

E. 转账 / 金额类占位符

{amount}
{receiver_amount}
{fee}
{total_cost}
{quick_amount_count}
{availability_hint}
{min_amount}
{max_amount}
{pay_status}
{message}

如果某个占位符在当前物品场景下没有值，通常会显示为空或默认文本，所以改文案时尽量沿用现有模板里已经出现过的占位符组合。

12. 一个比较实用的改法示例

比如你想把金额页的快捷金额从：

yml

10 / 100 / 1000

改成更适合生存服的：

yml

50 / 200 / 500 / 2000

你可以这样改：

yml

quick-amounts:
  values:
    - 50
    - 200
    - 500
    - 2000

gui:
  layout:
    content-slots:
      - 28
      - 30
      - 32
      - 34

然后执行：

text

/hneco reload

这样玩家进入金额面板时，就会看到新的 4 档金额。

13. 服主改 GUI 时最容易踩的坑

坑 1：还按旧结构去写 `fill / slots / slot-lists`

当前版本推荐直接按照 gui.layout.content-slots、items.*.slot、items.*.fill-slots 这一套实际结构来改。

坑 2：忘了 `pay-currency.yml`

如果你只改了目标页和金额页，却没改货币页，玩家中间这一步的体验会显得很割裂。

坑 3：只改了 `quick-amounts.values`，没改 `content-slots`

如果内容槽位只有 3 个，就算你写了 5 个金额，也只会显示前 3 个。

坑 4：把“可用金额”写得太大

金额按钮能显示，不代表一定能转出去。

坑 5：重载后发现没变化

优先检查：

文件是不是改在 plugins/HNEconomy/gui/ 下，而不是源码资源目录
有没有执行 /hneco reload
配置键名是否写错
材质名是否拼错
你是否改错了页面文件

14. 推荐的修改顺序

如果你第一次动这套 GUI，建议按顺序来：

先只改文案和材质
再改固定按钮槽位
再改列表内容区
再改快捷金额数量
最后再做大规模布局调整

这样一旦出问题，你比较容易知道是：

文案问题
材质问题
固定按钮槽位问题
列表内容区问题
分页布局问题

新功能：自定义金额输入与玩家搜索

自定义金额输入（v1.0.0+）

功能说明：

在金额选择页面（pay-amount.yml）新增"自定义金额"按钮，允许玩家输入任意金额，不再局限于预设的快捷金额。

配置示例：

yaml

# gui/pay-amount.yml
custom-amount:
  slot: 49
  material: WRITABLE_BOOK
  name: "&a自定义金额"
  lore:
    - "&7点击输入任意金额"
    - "&7不受预设金额限制"
    - ""
    - "&e左键点击 &7→ 打开输入界面"

使用流程：

玩家执行 /pay 进入转账流程
选择目标玩家和货币
在金额选择页面，点击"自定义金额"按钮
在铁砧界面输入金额（例如：123.45）
确认后自动进入转账确认流程

输入验证：

自动验证金额格式（必须是有效数字）
检查金额是否大于 0
检查是否在配置的最小/最大转账额范围内
自动转换为货币精度（根据 scale 配置）

错误提示：

如果输入无效，会显示相应的错误消息：

pay.input-amount-invalid：无效的金额格式
pay.input-amount-too-small：金额低于最小转账额
pay.input-amount-too-large：金额超过最大转账额

优势：

无需关闭 GUI，在铁砧界面直接输入
实时验证，即时反馈
支持小数点精度
体验流畅

注意事项：

铁砧输入框有长度限制（约 35 字符）
输入取消后会返回金额选择页面
输入超时（60 秒）会自动取消

玩家搜索功能（v1.0.0+）

功能说明：

在玩家列表页面（pay-player-list.yml）新增"搜索玩家"按钮，支持快速搜索在线/离线玩家。

配置示例：

yaml

# gui/pay-player-list.yml
search-player:
  slot: 22
  material: COMPASS
  name: "&a搜索玩家"
  lore:
    - "&7点击搜索玩家"
    - "&7支持模糊匹配"
    - ""
    - "&e左键点击 &7→ 输入玩家名"

使用流程：

玩家执行 /pay 进入转账流程
在玩家列表页面，点击"搜索玩家"按钮
在聊天中输入玩家名关键词（例如：Steve）
查看搜索结果：
- 如果只有 1 个结果，自动选择该玩家
- 如果有多个结果，显示匹配的玩家列表

搜索特性：

模糊匹配：输入部分名称即可匹配
大小写不敏感：steve 和 Steve 效果相同
支持离线玩家：可以搜索到曾经登录过的玩家
即时反馈：搜索结果立即显示

搜索结果：

显示匹配的玩家数量
列出前 10 个匹配的玩家
单个结果自动选择并进入下一步

优势：

不再需要翻页查找玩家
快速定位目标玩家
支持搜索离线玩家
搜索结果高亮显示

注意事项：

搜索关键词通过聊天输入，会暂时关闭 GUI
输入取消后会返回玩家列表页面
输入超时（60 秒）会自动取消
搜索无结果时会显示提示消息

禁用新功能

如果不需要这些新功能，可以：

方法 1：删除按钮配置

直接删除或注释掉对应的按钮配置：

yaml

# gui/pay-amount.yml
# custom-amount:  # 注释掉即可禁用
#   slot: 49
#   ...

方法 2：移除按钮槽位

将 slot 设置为 -1 或移除 slot 字段：

yaml

custom-amount:
  slot: -1  # 不显示按钮
  ...

1. 当前有哪些 GUI 文件 ​

player-economy.yml ​

pay-player-list.yml ​

pay-currency.yml ​

pay-amount.yml ​

2. 当前玩家转账 GUI 流程 ​

3. 修改完后怎么生效 ​

方式一：重启服务器 ​

方式二：执行重载命令 ​

4. 当前 GUI 文件的结构长什么样 ​

5. gui.title ​

常见占位符 ​

6. gui.size ​

7. gui.cancel-click ​

8. gui.layout.content-slots ​

注意 ​

9. gui.items ​

slot ​

fill-slots ​

material ​

name ​

lore ​

10. pay-amount.yml 里的 quick-amounts.values ​

这里有两个要点 ​

1）金额数量最好和 content-slots 数量对应 ​

2）金额仍然会受业务规则限制 ​

11. 当前模板里常见的占位符 ​

A. HNCore 经济命名空间占位符 ​

B. 页面流程类占位符 ​

C. 玩家 / 目标类占位符 ​

D. 货币 / 余额类占位符 ​

E. 转账 / 金额类占位符 ​

12. 一个比较实用的改法示例 ​

13. 服主改 GUI 时最容易踩的坑 ​

坑 1：还按旧结构去写 fill / slots / slot-lists ​

坑 2：忘了 pay-currency.yml ​

坑 3：只改了 quick-amounts.values，没改 content-slots ​

坑 4：把“可用金额”写得太大 ​

坑 5：重载后发现没变化 ​

14. 推荐的修改顺序 ​

新功能：自定义金额输入与玩家搜索 ​

自定义金额输入（v1.0.0+） ​

玩家搜索功能（v1.0.0+） ​

相关消息配置 ​

禁用新功能 ​

推荐阅读 ​

1. 当前有哪些 GUI 文件

`player-economy.yml`

`pay-player-list.yml`

`pay-currency.yml`

`pay-amount.yml`

2. 当前玩家转账 GUI 流程

3. 修改完后怎么生效

方式一：重启服务器

方式二：执行重载命令

4. 当前 GUI 文件的结构长什么样

5. `gui.title`

常见占位符

6. `gui.size`

7. `gui.cancel-click`

8. `gui.layout.content-slots`

注意

9. `gui.items`

`slot`

`fill-slots`

`material`

`name`

`lore`

10. `pay-amount.yml` 里的 `quick-amounts.values`

这里有两个要点

1）金额数量最好和 `content-slots` 数量对应

2）金额仍然会受业务规则限制

11. 当前模板里常见的占位符

A. HNCore 经济命名空间占位符

B. 页面流程类占位符

C. 玩家 / 目标类占位符

D. 货币 / 余额类占位符

E. 转账 / 金额类占位符

12. 一个比较实用的改法示例

13. 服主改 GUI 时最容易踩的坑

坑 1：还按旧结构去写 `fill / slots / slot-lists`

坑 2：忘了 `pay-currency.yml`

坑 3：只改了 `quick-amounts.values`，没改 `content-slots`

坑 4：把“可用金额”写得太大

坑 5：重载后发现没变化

14. 推荐的修改顺序

新功能：自定义金额输入与玩家搜索

自定义金额输入（v1.0.0+）

玩家搜索功能（v1.0.0+）

相关消息配置

禁用新功能

推荐阅读