向导与图鉴

所属：服主指南　·　相关：遗迹模板 · 战利品系统 · 占位符 · 命令大全

这两套系统服务玩家的探索体验：

向导（Guide）——玩家手持「指引物」右键，罗盘式地把他领到最近的同类遗迹；
图鉴（Codex）——玩家发现过的遗迹会记入一本攻略卡册，用 /qr codex 查看刷怪、战利品、坐标线索。

🖼️ [图片占位] 指引中的屏幕（标题 + 方向粒子指向远处遗迹）　·　建议 assets/guide-hud.png

一、向导（指引系统）

1.1 一次指引的完整流程

text

玩家右键指引物
   │
   ▼
弹出「确认 GUI」（是 / 否）
   │ 选「是」
   ▼
扣除 1 个指引物 → 开启指引
   │
   ▼
每隔几 tick 刷新：屏幕显示目标名 / 距离 / 方向 + 方向粒子
   │
   ├─ 走进 discover-radius ─→ 到达！记入图鉴、播放音效、指引结束（指引物永久扣除）
   │
   └─ 中途取消（换手键/丢弃键/换世界/掉线）─→ 返还那 1 个指引物

🔑 设计要点：到达才永久扣物；中途因任何原因结束都会把指引物还给玩家，不会让玩家白白损失。

1.2 指引物从哪来（QR 不内置 give）

指引物不由 QR 发放——它是带特殊标记的物品，标记 ID 为：

qinhruins:guide_<模板id>

由物品源给玩家（QinhItems 配方/掉落表/商店//qi give 等任意渠道引用这个 ID）。例如想让某遗迹的指引物从商店买、或作为任务奖励发放，就在那边引用 qinhruins:guide_ancient_tower。

指引物的外观（材质/名称/Lore/自定义模型）在模板 template.yml 的指引物配置里定义；右键时 QR 读取它身上的模板标记，去找该模板最近的实例指引。也支持绑定到具体某个遗迹实例（锚点）。

1.3 配置（config.yml 的 guide 段）

yaml

guide:
  display: title              # title=屏幕中上方标题 | actionbar=物品栏上方 | none=不显示(交给HUD插件)
  # 内置文字模板（占位符：{ruin} {distance} {direction} {world}）
  title: "§e◈ {ruin}"                                   # title 模式主标题
  subtitle: "§f{distance}m  §7{direction}"               # title 模式副标题
  actionbar: "§e{ruin} §f{distance}m  §7{direction}"     # actionbar 模式
  not-found: "§7Target ruin temporarily lost…"           # 指引途中目标临时解析不到
  other-world: "§e{ruin} §7is in another world"          # 目标在别的世界
  search-fail: "§cNo such ruin within {radius} blocks"   # 开启时范围内无目标
  search-radius: 10000        # 指引搜索半径(格)：太大搜图会卡服，按需调
  discover-radius: 48         # 进入此半径=到达：永久扣物、结束指引
  refresh-ticks: 10           # 距离/方向刷新间隔 tick（越大越省）
  exit-action: swap           # 游戏内退出指引的动作：swap | drop | none
  confirm:                    # 右键确认 GUI
    title: "Start guidance?"
    yes-name: "§a✔ Confirm"
    no-name: "§c✘ Cancel"
  particle:                   # 方向粒子（见 §1.6）
    enabled: true
    type: SOUL_FIRE_FLAME
    points: 6
    size: 1.0
    min-distance: 2
    near-distance: 32
    near-color: GOLD
    far-color: AQUA

1.4 显示方式 `display`

取值	效果
`title`（默认）	屏幕中上方标题 + 副标题，用 `title` / `subtitle` 模板
`actionbar`	物品栏上方一行，用 `actionbar` 模板
`none`	QR 不显示任何内置文字——交给你的 HUD 插件（BetterHud 等）用占位符自由排版

文字模板里可用 {ruin}（目标名）{distance}（剩余格数）{direction}（方向）{world}（目标世界）。

1.5 占位符（给 HUD 插件用）

把 display 设 none，用下列占位符（需装 PlaceholderAPI）在你的 HUD 里自定义排版：

占位符	含义
`%qinhruins_guide_active%`	是否正在指引（`true`/`false`）——HUD 据此显示/隐藏
`%qinhruins_guide_ruin%`	目标遗迹名
`%qinhruins_guide_distance%`	剩余距离（格）
`%qinhruins_guide_direction%`	方向（东/西南/…，8 方位）
`%qinhruins_guide_world%`	目标所在世界

完整占位符见占位符。

1.6 方向粒子 `particle`

在玩家视线方向朝目标喷一串粒子，作为「箭头」：

键	说明
`enabled`	总开关
`type`	粒子类型：`SOUL_FIRE_FLAME` / `FLAME` / `END_ROD` / `HAPPY_VILLAGER` / `DUST`（用下面的颜色）/ …任意原版粒子名
`points`	方向粒子点数（越少越省）
`size`	粒子大小（仅 `DUST` 生效）
`min-distance`	小于此距离不再画方向粒子（已经很近了）
`near-distance`	小于此距离用 `near-color`（仅 `DUST`）
`near-color` / `far-color`	接近 / 远离时的粒子颜色（仅 `DUST`）：`GOLD` `AQUA` `RED` `GREEN` `BLUE` `YELLOW` `ORANGE` `PURPLE` `LIME` `WHITE`

想要「越近越金、越远越蓝」的渐变提示，把 type 设为 DUST 并配 near-color / far-color。

1.7 取消指引 `exit-action`

游戏内主动退出指引的方式：

取值	对应按键
`swap`（默认）	换手键（默认 F）
`drop`	丢弃键（默认 Q）
`none`	不绑定任何手势键

想用任意键（如 K）取消：把该键在客户端键位 / HUD 插件里绑定到命令 /qr guide cancel 即可——这条命令在任何 exit-action 下都有效。

此外这些情况会自动取消并返还指引物：换世界、掉线重连。指引途中目标实例临时找不到（被回收/卸载）时显示 not-found 文案，等目标重新可达即恢复。

1.8 相关命令

命令	权限	作用
`/qr guide cancel`	`qinhruins.use`	玩家自己取消当前指引（返还指引物）
`/qr guide clear <玩家>`	`qinhruins.admin`	管理员强制清除某玩家的指引（在线则返还指引物）

注意

QR 没有 /qr guide give 之类的发放命令——指引物一律由物品源引用 qinhruins:guide_<模板id> 给出（见 §1.2）。

二、图鉴（Codex）

2.1 是什么

玩家发现过的遗迹会自动记入一本图鉴。/qr codex 打开一个 54 格的卡册：已发现的遗迹显示攻略卡，未发现的显示「❓ 未知遗迹」。

「发现」的触发点：玩家被指引到达某遗迹时，自动把该模板和该实例记入图鉴（见 §1.1 的到达环节）。

2.2 攻略卡上有什么

每张已发现的卡（鼠标悬停看 Lore）汇总该遗迹的关键情报：

位置线索：维度（主世界/下界/末地或具体世界）+ 生成层（地表/地下/天空/海面/海底/固定 Y）；
刷怪情报：总刷怪数、刷新冷却，以及可能出现的怪及其概率，按占比标注稀有度（普通 ≥35% / 稀有 ≥20% / 精英其余）；
战利品攻略：分「容器 / 奖励箱 / 通关」三栏，各列出前几样产出物（取自该模板引用的战利品表）。

🖼️ [图片占位] 图鉴 GUI（已发现卡 + 未知遗迹格 + 底部进度书）　·　建议 assets/codex-gui.png

底部中央的「遗迹图鉴」书显示总收集进度 已发现 X / 全部 Y。模板超过 45 个时只展示前 45 个（GUI 容量限制）。

2.3 跨服共享

单机/单服：图鉴发现记录存本地 YAML，零配置即用。
群组服（BungeeCord/Velocity）想跨服共享图鉴：把 config.yml 的 storage.type 设为 database，并让各后端的 QinhCoreLib 指向同一个 MySQL，玩家的图鉴发现自然在各子服间共享。

注意

只有图鉴发现（按玩家）会进数据库；锚点、宝箱领取记录、老虎机资格等绑具体服世界坐标的数据仍各服本地 YAML（本就该本地）。详见数据存储。

2.4 相关命令

命令	权限	作用
`/qr codex`	`qinhruins.use`	打开自己的遗迹图鉴

下一步

遗迹模板：配指引物外观、生成层（决定图鉴上的位置线索）
战利品系统：攻略卡上的战利品来自这里
组队与会话：进入提示、组队共享进度
占位符：guide / 探索全部占位符

向导与图鉴 ​

一、向导（指引系统） ​

1.1 一次指引的完整流程 ​

1.2 指引物从哪来（QR 不内置 give） ​

1.3 配置（config.yml 的 guide 段） ​

1.4 显示方式 display ​

1.5 占位符（给 HUD 插件用） ​

1.6 方向粒子 particle ​

1.7 取消指引 exit-action ​

1.8 相关命令 ​

二、图鉴（Codex） ​

2.1 是什么 ​

2.2 攻略卡上有什么 ​

2.3 跨服共享 ​

2.4 相关命令 ​

下一步 ​