概览：QR 是什么、为什么要它
一句话定位
QinhRuins（QR）是一个把「结构」变成「活在世界里的玩法」的程序化引擎：你给它一座建筑（原理图 / NBT），它负责让这座建筑在合适的地方自然冒出来、和地形融为一体、装上怪物 / 机关 / 宝箱 / 目标，玩家走近就能探索，打通后还能用钥石升成层层加码的秘境。
QR 故意不做副本——它不把玩家拉进独立世界、不开倒计时、不做「进本 / 退本」。遗迹就长在你的主世界里，是地形的一部分。
一句话记住定位：别的副本插件把玩家送进结构；QR 把结构种进世界。
🖼️ [图片占位] 对比图：左「传统副本=独立房间+倒计时」 右「QR=长在山谷里的遗迹」 · 建议 assets/overview-vs-dungeon.png
它解决什么问题
你有一座漂亮的建筑（自己搭的 / 下载的原理图），想让它：
- 在玩家探索时随机、稀有地出现在世界各处，而不是手动一座座摆；
- 贴合地形——不要凭空一块平台浮在山坡上，而是有地基、边缘渐变、半埋进山体；
- 里面有怪物会激活、宝箱每人独立开、机关能踩、能触发、有通关目标；
- 打通后能循环利用——随时间消退，让世界不断长出新内容；
- 高玩还能反复刷——同一座遗迹注入「层数 + 词缀」，越打越难也越肥。
这些 QR 全包了，而且服主不用写代码，玩家不用记一堆命令（核心体验是「走着走着撞见遗迹」）。
四步生命周期 —— 一座遗迹的一生
理解这四步，你就理解了 QR 的全貌：
| 阶段 | 发生什么 | 谁驱动 |
|---|---|---|
| ① 生成 | 在世界某处选址、把结构粘进去、和地形融合 | 生成总控按权重 / 密度 / 过滤抽签 |
| ② 探索 | 玩家走近 → 怪物激活、机关待命、宝箱可开、目标计数 | 锚点激活 + 蓝图玩法层 |
| ③ 通关 | 完成分阶段击杀目标 → 解锁奖励、发放通关战利品 | 目标追踪器 + 战利品系统 |
| ④ 消退 / 升华 | 打通的遗迹随时间快照还原、腾名额；或被钥石注入词缀升成秘境反复刷 | 再生（regen）/ 秘境系统 |
🖼️ [图片占位] 四阶段循环示意图（生成→探索→通关→消退/秘境，箭头回到生成） · 建议
assets/overview-lifecycle.png
整个循环让世界自我更新：旧遗迹消退、新遗迹冒出，玩家永远有新东西可探。
它能做什么 —— 典型场景
这些都是 QR 开箱即可编排的玩法：
- 荒野古塔随机生成 —— 一座塔模板，配
generation.profile: surface_overworld+ 权重，玩家探索时稀有地撞见。 - 半埋沙漠墓室 —— 用「基岩标记块」让沙丘从结构里透出来，做出真正埋在沙下的入口。
- 分阶段清剿副本式遗迹 —— 蓝图里写「阶段 1 清前哨 → 阶段 2 击败首领」，全清才算通关、才解锁大奖箱。
- 踩机关开门 / 召唤伏兵 —— 红石触发器 +
FILL动作把门填成空气；区域触发器 +SPAWN动作进门刷伏兵。 - 每人独立开的宝箱 —— 容器战利品
per-player-once，每位玩家首次开各得一份，保留神秘感。 - 层数秘境 endgame —— 通关掉钥石 → 右键遗迹核心激活 T5 秘境（禁疗 + 限时 + 怪潮）→ 净化拿独占战利品 + 更高层钥石。
- 指引罗盘找遗迹 —— 玩家手持指引物右键 → 罗盘 HUD 指向最近的此类遗迹、到达消耗。
- 天空浮岛 / 海底沉船 / 下界要塞 —— 17 个内置放置档案覆盖地表 / 地下 / 天空 / 海面 / 海底 × 主世界 / 下界 / 末地。
每个场景背后都是同一句话：你提供结构与规则，QR 负责让它在世界里活起来。
它在秦淮生态里的位置
QR 是秦淮 RPG 生态的「世界内容引擎」。它本身不算属性、不结算伤害——这条红线和兄弟模块一致：
| 模块 | 角色 | 与 QR 的关系 |
|---|---|---|
| QinhCoreLib（QCL） | 统一底层库（物品解析 / 数据库 / 经济 / i18n / 脚本） | QR 硬依赖它，没装则 QR 不启用 |
| MythicMobs（MM） | 怪物引擎 | QR 刷怪首选 MM（mm-怪名），缺它降级原版实体 |
| QinhItems / NeigeItems / MMOItems… | 物品来源 | 战利品 / 钥石 / 指引物的 item: 引用经 QCL 解析到任意物品源 |
| QinhClass / MMOCore | 职业 / 成长度来源 | 进入门槛、战利品成长度缩放读它；缺则用内置降级 |
| AttributePlus 等 | 属性 / 伤害 | QR 不碰；词缀让「怪变强」是委托 MM 提 level，不是 QR 改 stat |
🖼️ [图片占位] 秦淮生态模块关系图（QCL 底座 · QR 世界内容 · MM 怪物 · QI 物品 · QC 职业） · 建议
assets/ecosystem-diagram.png
注意「硬依赖」和「软依赖」的区别：QCL 必须先装，否则 QR 直接不启用；其余（MM / 物品插件 / 职业插件 / 经济 / Citizens / PlaceholderAPI）都是软依赖，缺了也能启动，只是对应能力降级。具体降级表见下一页 安装。