PlaceholderAPI 占位符
所属：开发者 · 同组：QinhRuinsAPI · 数据存储 相关：向导与图鉴 · 秘境与钥石
QR 通过 PlaceholderAPI 暴露遗迹 / 秘境 / 向导 / 进度状态，供计分板、Tab、BossBar、HUD 等使用。占位符标识符 qinhruins，统一格式：
%qinhruins_<占位符>%实现见 RuinPlaceholders（identifier = "qinhruins"）。所有占位符基于 玩家当前所处 / 附近的遗迹（多数取「最近的 / 所在的」那一座），离线玩家返回空串。
1. 钥石
| 占位符 | 含义 | 返回值 |
|---|---|---|
%qinhruins_keystone_tier% | 当前钥石层数 | 正在重铸时返回构建中的层数；否则读 主手 / 副手 钥石层数；都没有返回空串 |
2. 秘境（realm_*）
读 玩家附近的活跃秘境。无活跃秘境时按下表返回默认值。
| 占位符 | 含义 | 无秘境时 |
|---|---|---|
%qinhruins_realm_active% | 附近是否有活跃秘境 | false（有则 true） |
%qinhruins_realm_tier% | 秘境层数 | 0 |
%qinhruins_realm_name% | 秘境所属遗迹显示名（取模板 display，无则模板 id） | 空串 |
%qinhruins_realm_affixes% | 词缀名列表（空格分隔） | 空串 |
%qinhruins_realm_affix_count% | 词缀数量 | 空串 |
%qinhruins_realm_mobs% | 当前存活怪数 | 0 |
%qinhruins_realm_total% | 该秘境总刷怪数 | 0 |
%qinhruins_realm_time% | 剩余时间 分:秒（如 4:05）；无限时返回 ∞ | 0 |
3. 向导（guide_*）
读玩家当前激活的向导指引（手持向导物右键后，罗盘指向最近同类遗迹）。详见 向导与图鉴。
| 占位符 | 含义 | 无向导时 |
|---|---|---|
%qinhruins_guide_active% | 是否有激活的向导 | false（有则 true） |
%qinhruins_guide_ruin% | 目标遗迹名 | 空串 |
%qinhruins_guide_distance% | 到目标距离（格） | 0 |
%qinhruins_guide_direction% | 方向（如 N/E/S/W 等文本） | 空串 |
%qinhruins_guide_world% | 目标所在世界 | 空串 |
4. 最终BOSS门（boss_*）
下列占位符读 玩家附近最近遗迹的「最终BOSS门」进度（见 蓝图与目标 · boss-gate）。附近没有启用 boss-gate 的遗迹时：boss_active / boss_unlocked 返回 false，其余计数返回 0。
| 占位符 | 含义 | 返回值 |
|---|---|---|
%qinhruins_boss_active% | 附近是否有启用最终BOSS门的遗迹 | false（有则 true） |
%qinhruins_boss_unlocked% | 最终BOSS是否已解锁（已登场） | true / false |
%qinhruins_boss_kills% | 已累计击杀的指定怪物数 | 整数 |
%qinhruins_boss_required% | 解锁所需的累计击杀阈值 | 整数 |
%qinhruins_boss_remaining% | 距解锁还差多少（已封底 0） | 整数 |
HUD 进度条示例：
&c最终BOSS &7%qinhruins_boss_kills%/%qinhruins_boss_required%（解锁后%qinhruins_boss_unlocked%变true，可据此切换显示「BOSS已降临」）。
5. 遗迹进度（基于最近遗迹）
下列占位符读 玩家附近最近的遗迹进度（ObjectiveTracker.nearestProgress）。附近无遗迹进度时：stage 与 kills_* 返回 0，其余返回空串。
| 占位符 | 含义 | 返回值 |
|---|---|---|
%qinhruins_ruin% | 遗迹显示名 | 模板 display（无则模板 id） |
%qinhruins_stage% | 当前阶段序号 | 整数（无遗迹时 0） |
%qinhruins_max_stage% | 总阶段数 | 整数 |
%qinhruins_stage_name% | 当前阶段名 | 阶段名 / 空串 |
%qinhruins_completed% | 是否已通关 | true / false |
%qinhruins_objective% | 当前阶段目标文本 | 各击杀项 怪名 已杀/需杀，以 · 连接；已通关显示通关文案 |
%qinhruins_progress% | 进度（首个目标的 已完成/需要） | 如 2/5；已通关 100% |
%qinhruins_kills_<怪key>% | 玩家对某怪的击杀数 | 整数（无则 0） |
kills_<怪key>里的<怪key>是蓝图刷怪点里的怪物 key（如kills_zombie）。它读 该玩家 在当前遗迹的个人击杀计数。
6. HUD / 计分板用例
计分板（探索进度条）
# 某计分板插件的配置示意
lines:
- "&6遗迹: &f%qinhruins_ruin%"
- "&e阶段: &f%qinhruins_stage%/%qinhruins_max_stage% &7(%qinhruins_stage_name%)"
- "&a目标: &f%qinhruins_objective%"
- "&b进度: &f%qinhruins_progress%"秘境 BossBar / Tab
&c秘境 T%qinhruins_realm_tier% &7| 词缀 %qinhruins_realm_affixes% &7| 剩余 %qinhruins_realm_time% &7| 存活 %qinhruins_realm_mobs%/%qinhruins_realm_total%向导 HUD
&6指引中 &7→ &f%qinhruins_guide_ruin% &7(%qinhruins_guide_distance%格 %qinhruins_guide_direction%)想做条件显示（如「仅当
%qinhruins_realm_active%为true时显示秘境行」），用计分板插件自带的条件语法配合本占位符即可。