🏷️ PlaceholderAPI 占位符
QS 通过 PlaceholderAPI（PAPI）把技能运行时数据暴露给 HUD、计分板、BetterHud 等消费方。标识符前缀统一是 qinhskills。本章列全占位符并给用法示例。本文档对应 QS 1.0.22。
PAPI 是可选软依赖。没装 PlaceholderAPI 时 QS 不注册占位符（
PapiBridge.isEnabled()为假即跳过），其他功能照常。
1. 全局占位符
无需技能 id，反映玩家整体状态：
| 占位符 | 返回 | 说明 |
|---|---|---|
%qinhskills_skill_count% | 整数 | 服务器已定义的技能总数 |
%qinhskills_unlocked_count% | 整数 | 该玩家已解锁的技能数 |
%qinhskills_mana% | 整数 | 该玩家当前法力（取整） |
%qinhskills_mana_max% | 整数 | 法力上限（config resources.max_mana，默认 100） |
⚠️
mana/mana_max是 QC 接管前的临时占位。资源池最终归 QinhClass；QC 接管后这两个占位符的数据来源会切到 QC，键名不变。详见 数据存储。
2. 单技能占位符
格式：
%qinhskills_<技能id>_<后缀>%例如技能 fire_wave 的冷却剩余秒：%qinhskills_fire_wave_cooldown%。
| 后缀 | 返回 | 说明 |
|---|---|---|
_level | 整数 | 玩家该技能等级（默认 1） |
_unlocked | true/false | 是否已解锁 |
_ready | true/false | 当前是否可放（综合冷却/充能等） |
_cooldown | 秒（1 位小数） | 冷却剩余秒，如 2.4 |
_cooldown_ms | 毫秒 | 冷却剩余毫秒 |
_charges | 整数 | 当前充能层数 |
_max_charges | 整数 | 充能上限 |
_toggled | true/false | toggle 技能是否处于开启态 |
_channeling | true/false | 是否正在吟唱读条 |
_channel_progress | 整数 0–100 | 吟唱进度百分比 |
📌 后缀从尾部匹配（
_cooldown_ms先于_cooldown匹配，避免歧义）。技能 id 本身不要带这些后缀同名片段。
解析逻辑：
_level直接读档案，其余从内部skillStatus(uuid, skillId)取实时状态。null 行为：当某技能在玩家档案里没有状态记录、或技能 id 根本不存在时，
skillStatus返回null，则对应的 per-skill 占位符返回null（PAPI 通常渲染为空串）。其余 per-skill 后缀（_cooldown/_ready/_charges等）在无状态时同样为空。_level例外：技能有定义但无记录时按1处理。
3. 用法示例
计分板 / Actionbar
yaml
# 某计分板插件
lines:
- "&6火焰波 &7Lv.%qinhskills_fire_wave_level%"
- "&7冷却：&e%qinhskills_fire_wave_cooldown%s"
- "&7充能：&b%qinhskills_dash_charges%/%qinhskills_dash_max_charges%"
- "&9法力 &b%qinhskills_mana%&7/&b%qinhskills_mana_max%"BetterHud 吟唱读条
channel.bar_type: none 的技能把读条交给 HUD 自己画，正好用进度占位符：
yaml
# BetterHud 组件（伪配置）
condition: "%qinhskills_demo_slash_charged_channeling% == true"
progress: "%qinhskills_demo_slash_charged_channel_progress%" # 0-100解锁态做按钮置灰
yaml
# 菜单插件
icon:
material: "DIAMOND_SWORD"
glow: "%qinhskills_fire_wave_unlocked%" # true 时发光
lore:
- "%qinhskills_fire_wave_ready% 可用状态"4. 注意事项
- 大小写：技能 id 在 QS 内部统一小写。占位符里写技能 id 建议也用小写以免匹配不上。
- 离线玩家：占位符回调在
player == null时返回null；离线玩家数据取决于 PAPI 是否提供 OfflinePlayer。 - 刷新频率：占位符是拉取式，由消费方（计分板/HUD）按自己的刷新节奏调用。
_cooldown想要平滑倒计时，让 HUD 高频刷新即可。 - QS 不负责画 UI。占位符只是数据出口，UI/HUD 归消费方。
5. 速查（来自 SKILL_REFERENCE）
单技能：%qinhskills_<skill>_cooldown%(剩余秒) _cooldown_ms _charges _max_charges
_ready(true/false) _unlocked _toggled _channeling _channel_progress(0-100) _level
全局： %qinhskills_skill_count% %qinhskills_unlocked_count%
%qinhskills_mana% %qinhskills_mana_max%（QC 接管前的占位）