Ability: Hotbar

作者：AshuraNoYami

为 Tensura RPG 整合包添加一个可配置的快捷栏，用于使用各种战斗能力，包括 Tensura 技能与魔法，以及 Iron's Spells 的法术和战斗意志；它位于原版快捷栏旁边。

模组 NeoForge 冒险实用魔法

介绍

介绍由机器翻译自 CurseForge 原页面，仅供参考。

Ability Hotbar

Ability Hotbar 为 Tensura RPG 整合包提供了一条专属战斗能力栏：Tensura 技能与魔法、Iron’s Spells 的法术和战斗意志都能统一分配、选择并触发。它可配置快捷键，显示在原版快捷栏旁边，不会覆盖原版快捷栏。

功能介绍

（目前处于设计阶段，尚未发布。此仓库的开放议题中包含完整计划、调研表格和待定设计决策。）

九格能力栏 – 采用原版风格的槽位，显示动态能力图标、冷却和资源覆盖层，并可通过可配置按键直接激活指定槽位或激活当前选中槽位。
管理菜单 – 搜索、筛选、预览并重新分配能力；布局会按玩家保存。
Tensura 技能与魔法、ISS 法术和战斗意志通过同一套接口共用能力栏。如果某项能力或其提供方缺失，能力栏也能妥善处理。
可选法术书快捷栏 – 为已装备的 Iron’s Spells 法术书中的法术提供独立的快捷栏，可单独开关（需安装 ISS）。
不会影响原版控制：只有按住修饰键时，模组才会接管滚轮和数字键。

控制

所有按键都可在原版“控制”界面的 Ability Hotbar 分类下重新绑定。默认按键（来自 SPIKE-hot-3）：

操作	默认按键	说明
选择槽位	Ctrl + 滚轮	仅移动选中槽位的光标；普通滚轮仍控制原版快捷栏，只有按住 Ctrl 时才会接管滚轮。
激活槽位 1..9	Ctrl + 1..9	直接激活对应槽位。普通 1..9 仍用于切换原版快捷栏。
激活选中槽位	G	触发当前选中槽位中的能力。
打开能力菜单	K	打开管理菜单。
切换能力模式	Right Ctrl	与 Tensura 原生模式按键保持一致。

选择槽位不会触发能力。激活能力时会使用当前选中槽位，并保持选中状态不变。空槽位、受限制的能力、资源不足或仍在冷却中的能力均无法激活，且不会消耗资源。

我们不会抢占原版或聊天输入：打开任何界面时（聊天、物品栏或模组界面），都不会拦截按键；未按住修饰键时，普通滚轮和 1-9 的行为与未安装此模组时完全相同。游戏内验证矩阵见 docs/input-gating-matrix.md。

配置

能力栏外观属于 CLIENT 配置（display.*），仅控制显示，不影响规则；它不会同步到服务器，也无法放宽服务器规则。配置界面使用 NeoForge 自带的配置屏幕（此模组会绕过配置界面类模组，避免其编辑器重置你未修改的值）。槽位数量采用双层限制：客户端的偏好设置会被限制在服务器设定的上限内（见“持久化”）。

键	默认值	含义
`display.slotsPerBar`	`9`	首选槽位数（不得超过服务器的 `hotbar.maxSlots`，硬性上限为 10）。
`display.horizontal`	`true`	快捷栏方向：`true` = 从左到右，`false` = 从上到下。
`display.anchor`	`ABOVE_HOTBAR`	命名位置：`aboveHotbar`、`aboveXp`、`aboveStatus`、`leftEdge` 或 `rightEdge`。每种都是完整的二维摆放规则，因此所有选项都适用于两种方向。
`display.statusAnchorMode`	`DYNAMIC`	`aboveStatus`所用的高度：`DYNAMIC` 根据玩家的生命值、盔甲和氧气条调整；`FIXED` 使用原版基准高度，位置固定不变。仅供 `aboveStatus` 读取。
`display.opacity`	`1.0`	快捷栏不透明度（0.0–1.0）。
`display.showCooldowns`	`true`	在槽位上显示冷却覆盖层。
`display.showCosts`	`true`	在槽位上显示资源消耗标记。
`display.offsetX` / `display.offsetY`	`0`	相对于快捷栏锚点的像素偏移。
`display.scale`	`1.0`	统一渲染缩放比例（0.5–2.0）。
`display.showIcons`	`true`	显示能力图标（无法解析图标时会使用占位图）。

持久化

玩家的能力分配按玩家保存，存储在由服务器控制的附件数据中，并且死亡后保留。数据格式带有版本号，因此整合包更新不会破坏快捷栏。已存储的 NBT 键：

键	类型	含义
`schema_version`	int	格式版本（当前为 `1`）。若版本高于此模组支持的版本，则会作为有效的空快捷栏载入，而不会导致崩溃。
`slot_count`	int	槽位数量。显式写入，因此之后降低配置中的槽位数也不会截断已存储的槽位。
`selected_slot`	int	选中槽位的索引（载入时会限制在有效范围内）。
`slot_N`	string	槽位 `N`中的能力 ID。缺失时表示槽位为空。

升级与保留规则：

如果某个复合标签是在 schema_version / slot_count 引入前写入的，升级时会保留原有数据；槽位数根据现存的最高 slot_N 键推断。
如果某个 ID 对应的提供方缺失，该 ID 会以原始形式保留，因此槽位会显示为已诊断但不可用，而不会被丢弃（REQ-HOT-21）。
无法解析的 ID 会记录日志并留空，不会导致载入崩溃（REQ-HOT-15）。

依赖项

	模组	用途
必需	Minecraft / NeoForge	1.21.1 / 21.1.259
必需	Tensura Ability Core	能力栏读取并激活所需的能力接口
可选	Tensura: Reincarnated	安装后，技能与魔法会显示在能力栏中
可选	Iron’s Spells ‘n Spellbooks	安装后，法术和已装备法术书的快捷栏会显示
可选	Tensura Battlewills	安装后，战斗意志会显示在能力栏中