UI、HUD 与按键

GTSkillView 的 UI 分为两层：

服务端逻辑：技能、槽位、MP、冷却、按键、动作。
客户端展示：PaiUI、ArcartX、KongCore、DragonCore 或原版 GUI。

客户端 UI 只负责显示和回传动作。释放、绑定、升级、扣蓝、冷却、权限、条件都由服务端统一处理。

文件位置

text

plugins/GTSkillView/client-ui/
  providers.yml
  ax/
    main.yml
    hud.yml
  dragoncore/
    main.yml
  kongcore/
    main.yml
  paiui/
    KeyConfig.yml
    webgui/gtskillview/
      main.html
      hud.html
      style.css
      ui.js

client-ui 下的模板用于服务器侧注册和同步客户端界面。
更新 UI 模板后，需要手动覆盖旧文件，或删除旧文件后重启生成。

providers.yml 路由顺序

yaml

routing:
  fallback-order:
    - paiui
    - ax
    - kongcore
    - dragoncore
    - vanilla

fallback-order 控制 ui.default: auto 时的选择顺序。

值	说明
`paiui`	PaiUI / PaiDaXing WebGui
`ax`	ArcartX
`kongcore`	KongCore
`dragoncore`	DragonCore
`vanilla`	原版箱子 GUI

只使用 AX：

yaml

routing:
  fallback-order:
    - ax
    - vanilla

只使用原版 GUI：

yaml

routing:
  fallback-order:
    - vanilla

providers 开关

yaml

providers:
  paiui:
    enabled: true
  ax:
    enabled: true
  kongcore:
    enabled: true
  dragoncore:
    enabled: true

关闭某个 UI：

yaml

providers:
  dragoncore:
    enabled: false

关闭后 auto 路由会跳过该 UI。

统一动作协议

客户端 UI 回传动作时使用逻辑动作，不直接绕过服务端。

常见动作：

text

key SLOT_1
cast 1
bind 1 thunder_slash
unbind 1
upgrade thunder_slash
reset
open

按键释放推荐走：

text

key SLOT_1

服务端会读取：

text

config.yml -> release.client.bindings.SLOT_1

再决定它对应哪个槽位或动作。

默认按键

yaml

release:
  client:
    bindings:
      SLOT_1:
        slot: 1
        keys:
          paiui: ["R"]
          ax: ["R"]
          kongcore: ["R"]
          dragoncore: ["R"]
      SLOT_2:
        slot: 2
        keys:
          paiui: ["T"]
          ax: ["T"]
          kongcore: ["T"]
          dragoncore: ["T"]
      SLOT_3:
        slot: 3
        keys:
          paiui: ["Z"]
          ax: ["Z"]
          kongcore: ["Z"]
          dragoncore: ["Z"]
      SLOT_4:
        slot: 4
        keys:
          paiui: ["X"]
          ax: ["X"]
          kongcore: ["X"]
          dragoncore: ["X"]
      SLOT_5:
        slot: 5
        keys:
          paiui: ["C"]
          ax: ["C"]
          kongcore: ["C"]
          dragoncore: ["C"]

默认键位：

槽位	键
1	`R`
2	`T`
3	`Z`
4	`X`
5	`C`

改键只改 release.client.bindings。不要在模板里把物理键写死。

PaiUI

yaml

providers:
  paiui:
    enabled: true
    channel: "gtskillview:update"
    action-channel: "gtskillview:action"
    data-route: "gtskillview.data"
    action-route: "gtskillview.action"
    mirror-webgui: true
    mirror-keyconfig: true
    mirror-keyconfig-overwrite: false
    mirror-keyconfig-merge-missing: true
    dynamic-items: true
    dynamic-item-namespace: ""
    dynamic-items-on-hud: false
    views:
      main: "layout/gtskillview/main.html"
      hud: "layout/gtskillview/hud.html"

字段	作用
`channel`	服务端推送数据频道
`action-channel`	客户端动作频道
`data-route`	WebGui 请求数据路由
`action-route`	WebGui 动作路由
`mirror-webgui`	是否同步 WebGui 文件
`mirror-keyconfig`	是否同步 KeyConfig
`dynamic-items`	是否启用 PaiUI 动态物品
`dynamic-item-namespace`	动态物品命名空间
`dynamic-items-on-hud`	HUD 是否使用动态物品
`views.main`	主界面路径
`views.hud`	HUD 路径

PaiUI 文件同步

WebGui 默认同步到：

text

plugins/PaiDaXingPlugins/advanced/WebGui/layout/gtskillview/

按键默认同步到：

text

plugins/PaiDaXingPlugins/advanced/KeyConfig/KeyConfig.yml

mirror-keyconfig-overwrite: false 时，只补缺失项，不覆盖已有同名按键。
如果旧按键残留，先备份 KeyConfig，再删除 GTSkillView 生成过的按键项。

PaiUI 页面约定

页面入口使用：

text

window.PaiDaXing
window.PDX

服务端通信使用：

text

PaiDaXing.server.request(...)
PaiDaXing.server.notify(...)

HUD 非交互区域保持不可点击，避免挡住玩家视角和鼠标操作。
动态物品和真实槽位不要每帧刷新。列表变化、打开界面、数据变化时刷新即可。

PaiUI 图标

技能图片优先读取：

yaml

texture: "textures/gtskillview/thunder_slash.png"

展示物品可使用动态物品。普通技能 HUD 更推荐使用 texture，减少动态物品刷新成本。

ArcartX

yaml

providers:
  ax:
    enabled: true
    register: true
    reload-on-open: true
    register-packet-callback: true
    sync-on-open: true
    mirror-keybind: true
    mirror-keybind-overwrite: true
    mirror-keybind-file: "GTSkillView.yml"
    packet-handler: update
    action-packet-handlers:
      - gtskillview
      - gtskillview:action
    views:
      main: "gtskillview_main"
      hud: "gtskillview_hud"
    files:
      main: "client-ui/ax/main.yml"
      hud: "client-ui/ax/hud.yml"

字段	作用
`register`	打开时向 AX 注册 UI
`reload-on-open`	打开时尝试重载 UI
`register-packet-callback`	注册 AX PACKET 回调
`mirror-keybind`	生成 AX 按键监听文件
`mirror-keybind-file`	生成的按键文件名
`packet-handler`	服务端向 UI 推送数据的 handler
`action-packet-handlers`	允许的动作标识
`views.main`	AX 主界面 ID
`views.hud`	AX HUD ID
`files.main`	主界面模板
`files.hud`	HUD 模板

AX 按键文件

GTSkillView 会按 release.client.bindings 生成：

text

plugins/ArcartX/key_bind/simple_key/GTSkillView.yml

示例：

yaml

GTSkillView_SLOT_1:
  keys:
    - "R"
  trigger:
    - "让玩家发送消息{message = /gtsv key SLOT_1 ax}"

AX 按键监听走 key_bind/simple_key。不要用 HUD 左键事件冒充物理按键监听。

AX 客户端图片

AX 客户端图片放在 AX 客户端资源目录。

示例路径：

text

.minecraft/resourcepacks/ArcartX/resource/gtskillview/skill/panel_base_940x560.png
.minecraft/resourcepacks/ArcartX/resource/gtskillview/hud/01_bar_shell_72x412.png
.minecraft/resourcepacks/ArcartX/resource/textures/gtskillview/thunder_slash.png

技能图标的 texture 路径按客户端资源包实际结构放置。
服务器只负责下发 slot_1_texture、skill_1_texture 等变量。

AX PACKET 安全

AX 客户端发包只接受明确标识：

text

gtskillview
gtskillview:action

Packet.send("gtskillview", "bind 1 thunder_slash", "main") 这类包可以处理。
空标识符包只有第一个参数明确是 gtskillview 时才处理。普通鼠标事件、槽位文本、数字不会被当成技能释放。

这样可以避免左键攻击、普通 UI 包、其他插件包误触发 GTSkillView。

AX 主界面绑定

AX 主界面支持：

点击技能卡选中技能。
点击左侧槽位绑定当前技能。
点击右侧绑定按钮绑定到 1 号槽。
按住技能卡拖到槽位松开，尝试走释放事件绑定。

不同 AX 版本对拖拽/松开事件支持不完全一致。点击选中再点击槽位是稳定链路。

KongCore

yaml

providers:
  kongcore:
    enabled: true
    action-channel: "gtskillview"
    data-identifier: "gtskillview:update"
    variable-prefix: "gtskillview_"
    views:
      main: "segment/gtskillview/main.yml"
      hud: "segment/gtskillview/hud.yml"
    files:
      main: "client-ui/kongcore/main.yml"
      hud: "client-ui/kongcore/main.yml"

字段	作用
`action-channel`	客户端动作频道
`data-identifier`	服务端数据推送标识
`variable-prefix`	变量前缀
`views`	KongCore 视图路径
`files`	模板文件

变量示例：

text

gtskillview_player
gtskillview_mana
gtskillview_max_mana
gtskillview_points
gtskillview_slot_1_name
gtskillview_slot_1_texture
gtskillview_slot_1_cooldown_percent
gtskillview_key_slot_1

模板按钮回传：

text

key SLOT_1

DragonCore

yaml

providers:
  dragoncore:
    enabled: true
    action-channel: "GTSkillView"
    legacy-action-channel: "GTSkillView"
    variable-prefix: "gtskillview_"
    views:
      main: "gtskillview/main"
      hud: "gtskillview/hud"
    files:
      main: "client-ui/dragoncore/main.yml"
      hud: "client-ui/dragoncore/main.yml"

字段	作用
`action-channel`	新版动作频道
`legacy-action-channel`	兼容动作频道
`variable-prefix`	变量前缀
`views`	DragonCore 视图路径
`files`	模板文件

DragonCore 默认模板只保留按钮点击。物理按键监听需要按服务器当前 DragonCore 版本的按键系统配置，不在模板里猜。

原版 GUI

原版 GUI 使用 gui.yml。

yaml

title: "&0GTSkillView &8| &6技能视图"
rows: 6
skill-slots:
  - 10
  - 11
  - 12
bound-slots:
  1: 37
  2: 38
  3: 39
  4: 40
  5: 41

操作：

操作	效果
左键技能	学习或升级
右键技能	准备绑定
点击下方槽位	绑定已选择技能
Shift + 左键技能	直接释放
左键已绑定槽位	释放
右键已绑定槽位	解绑

原版 GUI 不需要客户端 Mod。
没有 PaiUI、AX、KongCore、DragonCore 时，仍可使用 /gtsv open。

HUD 数据变量

服务端推送给客户端 UI 的常用变量：

text

player
mana
max_mana
mana_percent
points
slots_json
skills_json
slot_1_name
slot_1_texture
slot_1_cooldown_text
slot_1_cooldown_percent
key_slot_1
skill_1_id
skill_1_name_plain
skill_1_level
skill_1_max_level
skill_1_description

HUD 只读取当前绑定槽位，不负责判断技能是否能释放。
冷却遮罩使用 slot_x_cooldown_percent，倒计时文字使用 slot_x_cooldown_text。

资源更新注意

GTSkillView 使用默认资源保存机制：

text

文件不存在 -> 生成默认资源
文件已存在 -> 不覆盖

更新插件后，如果客户端 UI 模板没有变化，检查：

text

plugins/GTSkillView/client-ui/ax/main.yml
plugins/GTSkillView/client-ui/ax/hud.yml
plugins/GTSkillView/client-ui/paiui/webgui/gtskillview/

处理方式：

备份旧文件。
删除旧模板。
重启服务器让插件重新生成。
或直接用新模板覆盖旧模板。

排查流程

按键不生效：

检查 config.yml -> release.client.enabled。
检查 release.client.allow-providers 是否包含当前来源。
检查 release.client.bindings 是否有对应绑定 ID。
PaiUI 检查 advanced/KeyConfig/KeyConfig.yml。
AX 检查 key_bind/simple_key/GTSkillView.yml。
用 /gtsv key SLOT_1 ax 直接测试服务端解析。

HUD 挡鼠标：

确认打开的是 HUD 文件，不是主界面文件。
AX 检查 ui.isHud: true。
PaiUI HUD 非交互区域使用不可点击样式。
主界面和 HUD 不要共用同一个交互模板。

图标不显示：

原版 GUI 检查 icon。
客户端 UI 检查 texture。
检查客户端资源包是否有对应图片。
检查路径大小写。
AX 图片检查客户端资源目录。

UI、HUD 与按键 ​

文件位置 ​

providers.yml 路由顺序 ​

providers 开关 ​

统一动作协议 ​

默认按键 ​

PaiUI ​

PaiUI 文件同步 ​

PaiUI 页面约定 ​

PaiUI 图标 ​

ArcartX ​

AX 按键文件 ​

AX 客户端图片 ​

AX PACKET 安全 ​

AX 主界面绑定 ​

KongCore ​

DragonCore ​

原版 GUI ​

HUD 数据变量 ​

资源更新注意 ​

排查流程 ​

UI、HUD 与按键

文件位置

providers.yml 路由顺序

providers 开关

统一动作协议

默认按键

PaiUI

PaiUI 文件同步

PaiUI 页面约定

PaiUI 图标

ArcartX

AX 按键文件

AX 客户端图片

AX PACKET 安全

AX 主界面绑定

KongCore

DragonCore

原版 GUI

HUD 数据变量

资源更新注意

排查流程