秘境与钥石（Realm × Keystone）

所属：服主指南总览　·　上游：核心概念与架构　·　相关：词缀系统 · 战利品系统

秘境（Realm） 是 QR 的 endgame：把一座已生成、可激活的遗迹注入「层数（tier）+ 词缀（affix）」，让它怪重刷、规则改写、产出升级，反复打。钥石（Keystone） 是激活秘境的钥匙。本页讲清整套循环，并逐项拆解 config.yml 的 realm: 段。

🔑 架构红线：QR 不算属性 / 伤害。秘境让「怪变强」=刷怪时给怪附 level，由 MythicMobs 自己缩放 stat；玩家属性委托属性插件；QR 只编排数量 / 环境 / 规则 / 战利品。

1. 一句话循环

text

通关遗迹 → 掉落钥石(带天梯,有概率掉更高层)
        → (可选) /qr reroll 花货币重铸词缀,满意为止
        → 手持钥石右键遗迹「核心」激活秘境(注入 tier+affix)
        → 清光所有怪 = 净化
        → 私发独占战利品 + 货币 + (按概率)同层/更高层钥石
        → 拿着新钥石,回到第一步,层数越爬越高

净化掉的更高层钥石就是天梯发动机：玩家不停往上爬层，越高越肥也越危险。

🖼️ [图片占位] 秘境循环闭环示意图（通关→钥石→重铸→激活→净化→更高层钥石）· 建议 assets/realm-loop.png

2. 钥石怎么来、怎么用

2.1 拿到钥石

途径	说明
通关掉落	普通遗迹通关、或秘境净化后，按 `keystone-chance` / `next-tier-chance` 概率掉落（直接进背包）
管理员发放	`/qr keystone give <tier> [player]`（权限 `qinhruins.admin`），`tier` 自动夹在 `1..max`；省略 `player` 给自己
物品源 / 商店 / 战利品	钥石本质是一个带 `keystone_tier` NBT 的物品，可经任何掉落表或商店发放

2.2 激活秘境

玩家手持钥石右键遗迹核心（蓝图里 cores 段定义的交互块）即可激活。

已屏蔽末影眼飞天等原版右键行为（默认材质是末影眼也不会被扔出）。
右键空气无效，必须右键到核心块。
激活成功会扣 1 个钥石，注入该钥石上记录的层数与（若已重铸）词缀；若钥石没预存词缀，则在激活瞬间盲盒 roll。

也可以用 /qr activate 命令激活：它会先搜玩家脚下所在遗迹，再搜 activate-radius 半径内最近的可激活遗迹。搜不到会提示最近遗迹的距离。命令详见命令大全。

已是秘境、已通关（CLEARED）、或蓝图没有刷怪点的遗迹无法激活，会给出对应提示。

2.3 钥石外观（`realm.keystone`）

yaml

realm:
  keystone:
    # material 支持任意物品源（默认原版）：
    #   原版：材质名 / minecraft:xxx / vanilla:xxx
    #   其它插件（软依赖）：craftengine:xxx | itemsadder:xxx(ia-xxx) | nexo:xxx(nx-xxx)
    #     qinhitems:xxx(qi-xxx) | mmoitems:类型:id(mi-) | neigeitems:xxx(ni-) | mythicmobs:xxx(mm-xxx)
    material: minecraft:ender_eye
    # name/lore 只对【原版材质】生效；material 指向其它物品源时，
    # 完全保留该物品自带的 name/lore，不覆盖。
    name: "&dRealm Keystone &7T{tier}"   # {tier}=层数；留空 "" 则原版材质也不改名
    lore:
      - "&7Right-click a ruin core to activate a &dT{tier} &7realm"
    model-data: 0                        # 自定义模型数据（原版材质用）

关键规则：

{tier} 占位符会替换为该钥石的层数（仅原版材质的 name/lore 会替换）。
想在自定义物品（mi/ni/qi/ia/ce/mm…）做的钥石上显示层数，就在那件物品自己的 name/lore 里写占位符 %qinhruins_keystone_tier%（需装 PlaceholderAPI）。占位符全集见占位符。
激活前若已重铸过词缀，钥石 Lore 末尾会自动追加一段 — Affixes — 列表（&7• 词缀名）。

🖼️ [图片占位] 末影眼钥石的物品 tooltip（含 T 层数与 Affixes 列表）· 建议 assets/keystone-tooltip.png

3. 层数曲线（`realm.tiers`）

层数是秘境的强度刻度。四个表达式以 tier（当前层数）为变量，用 CoreLib 的表达式引擎求值。

yaml

realm:
  tiers:
    max: 16                          # 最高层（钥石/天梯封顶在此）
    affix-count:   "1 + tier / 3"    # 每层词缀数量（取整）
    mob-level:     "tier * 5"        # 刷怪基础 level（再加词缀的等级加成；交给 MM 缩放）
    loot-bonus:    "1 + tier * 0.1"  # 净化战利品「卷数」倍率，随层缩放
    danger-budget: "40 + tier * 10"  # 难度预算上限（词缀 danger 之和封顶）

键	含义	默认效果举例
`max`	钥石层数上限，天梯爬到此封顶（至少为 1）	16
`affix-count`	该层注入几个词缀（结果取整，夹在 0~32）	T3 → `1+3/3=2` 个
`mob-level`	刷怪基础等级（再叠加「等级」类词缀的加成），交给 MM 缩放怪 stat	T5 → 25 级
`loot-bonus`	净化掉落的数量倍率，与「贪婪」词缀倍率叠乘。写 `"1"` 关闭按层加成	T1→1.1×，T16→2.6×
`danger-budget`	词缀危险预算上限，见下文与词缀系统	T1 → 50

mob-level 与「等级」类词缀（百战 +2 / 霸主 +5）相加后，作为刷怪 level 传给 MythicMobs；QR 不直接改任何数值。

4. 词缀注入与危险预算

激活时 QR 按层数 roll 出 affix-count 个词缀（若钥石已重铸则用预存的那批）。两条约束保证体验：

危险预算（danger-budget）：所有词缀的 danger 之和不得超过该层预算，防止低层地狱叠加（比如 T1 不可能凑齐「禁疗 + 限时 + 怪潮」）。首个词缀始终保底（无视预算），保证每个秘境至少有一个词缀。高层预算高，才凑得齐重型组合。
同组互斥（group）：同 group 的词缀（如 mob-count 组的精英成群 / 怪潮）一次只会出现一个。

词缀全表、effect 类型与内置 13 个词缀见词缀系统。

5. 净化奖励（`realm.reward`）

清光秘境内所有怪即「净化」。净化对每位参与者私发独占战利品和货币（不是地上掉落，按人结算）。

yaml

realm:
  reward:
    loot-table: realm           # 独占战利品表名（loottables/<名>.yml）
    per-tier-table: false       # true 时优先用 realm_t{tier}，缺则回退 loot-table
    growth-scaled: true         # 个人掉落数量按「成长度」缩放
    currency-base: "tier * 100" # 每位参与者基础货币（表达式，变量 tier；0=关闭）
    currency-provider: ""       # 经济后端：留空=auto | vault | excellenteconomy(ee) | playerpoints
    currency-id: ""             # 货币ID（ExcellentEconomy 必填，如 money/silver；Vault/PP 留空）

键	含义
`loot-table`	净化发的独占战利品表，对应 `loottables/<名>.yml`（默认 `realm`）
`per-tier-table`	开启后优先找 `realm_t<层数>` 表（如 `realm_t12`），找不到回退 `loot-table`。适合给高层单独配更肥的表
`growth-scaled`	个人掉落数量按玩家成长度（QinhClass/MMOCore 等级或原版替代）缩放
`currency-base`	每位参与者的基础货币额（表达式），再与「鎏金」词缀倍率叠乘。需装经济插件，否则跳过
`currency-provider`	经济后端选择。留空自动探测；`vault`/`ee`/`playerpoints` 显式指定
`currency-id`	ExcellentEconomy 的货币 ID（EE 必填）；Vault / PlayerPoints 留空

战利品表 loottables/realm.yml 写法（item 走 CoreLib 解析任意来源、weight/amount/min-growth/unique）见战利品系统。unique: true 的条目受「秘藏」词缀加权。

/qr reward（净化老虎机领奖）：净化后，玩家用 /qr reward 打开就近的老虎机界面领取产出（一种带动画的开奖 UI）。老虎机机制详见战利品系统。

🖼️ [图片占位] 净化老虎机开奖界面 · 建议 assets/reward-slotmachine.png

6. 重铸赌博（`realm.reroll`）

不满意钥石上 roll 出的词缀？花货币重 roll，满意了再去激活。

yaml

realm:
  reroll:
    enabled: true              # 关闭则 /qr reroll 不可用，词缀只在激活瞬间盲盒 roll
    cost-base: "tier * 50"     # 单次重铸花费（表达式，变量 tier；需装经济插件）
    currency-provider: ""      # 同 reward：留空=auto | vault | ee | playerpoints
    currency-id: ""            # 货币ID（ExcellentEconomy 必填）

玩家手持（主手或副手）钥石执行 /qr reroll：

按 cost-base 算出本次花费；
若花费 > 0 且没装经济插件，提示不可用；余额不足会报出花费 / 余额并提示充值；
扣费成功后按钥石层数重新 roll 词缀，直接写回手上的钥石（更新其 Lore 的 Affixes 列表）；
把新词缀逐条回报给玩家。

重铸把词缀预存进钥石，激活时直接采用，不再盲盒。enabled: false 时玩家只能接受激活瞬间的随机结果。

7. 失败、放弃与限时

yaml

realm:
  failure:
    consume-keystone: false   # 失败是否消耗钥石（高层建议 true 增刺激；激活时钥石已扣，此项影响失败后是否返还）
  activate-radius: 48         # /qr activate 搜索附近遗迹的半径
  abandon-seconds: 120        # 秘境周围无玩家多久判定放弃（清怪重置，防持久怪堆积）
  time-limit: "0"             # 秘境全局限时，0=无限时（更像世界结构，不像副本倒计时）

键	含义
`failure.consume-keystone`	默认 `false`：秘境失败（限时到 / 被放弃）后，会在原地掉回一枚同层钥石让玩家重来；设 `true` 则失败不返还，钥石打水漂，增加爬层刺激
`activate-radius`	`/qr activate` 命令搜索可激活遗迹的半径
`abandon-seconds`	秘境范围内持续无玩家超过这么多秒就判定放弃：清掉刷出的怪、状态回 `DORMANT`，防野外怪堆积
`time-limit`	秘境全局限时（支持 `5m`/`300` 等写法），`0` = 不限时。注意：「时之沙」等限时词缀会就近取更短的限时，优先级高于此项

失败（非通关结束）只对结果分流：通关才发奖；放弃 / 超时按 consume-keystone 决定是否返还钥石。

8. 天梯概率（`realm.keystone-chance` / `realm.next-tier-chance`）

净化后对每位参与者掷骰，决定掉不掉钥石——这是整套 endgame 的天梯发动机。

yaml

realm:
  keystone-chance: 0.5      # 净化后掉「同层」钥石的概率（直接进背包，0~1）
  next-tier-chance: 0.2     # 净化后额外掉「更高一层」钥石的概率（爬层引擎，封顶 max）

键	含义
`keystone-chance`	净化后掉同层钥石的概率（`0`=从不掉、`1`=必掉）。维持玩家手里有钥石可循环
`next-tier-chance`	额外掉更高一层钥石的概率，层数已达 `tiers.max` 则不再升。这是往上爬层的核心驱动

两者独立判定：一次净化可能同时掉同层 + 更高层钥石。掉落直接进背包，背包满则掉落脚下。

9. Bossbar 与外观

yaml

realm:
  bossbar-color: PURPLE                 # PINK/BLUE/RED/GREEN/YELLOW/PURPLE/WHITE
  bossbar-style: SEGMENTED_10           # SOLID/SEGMENTED_6/10/12/20

秘境激活期间，范围内玩家头顶显示 Bossbar，标题含层数、遗迹名与词缀列表，进度条 = 剩余怪 / 总怪。

10. 相关占位符

需装 PlaceholderAPI（详见占位符）：

占位符	含义
`%qinhruins_realm_active%`	玩家是否身处秘境
`%qinhruins_realm_tier%`	当前秘境层数
`%qinhruins_realm_name%`	秘境遗迹名
`%qinhruins_realm_affixes%`	当前秘境词缀列表
`%qinhruins_realm_affix_count%`	词缀数量
`%qinhruins_realm_mobs%` / `%qinhruins_realm_total%`	剩余 / 总怪数
`%qinhruins_realm_time%`	剩余限时
`%qinhruins_keystone_tier%`	玩家手持钥石的层数（做自定义钥石外观用）

下一步

配词缀、读懂 11 种 effect 与危险预算 → 词缀系统
配净化战利品表与老虎机 → 战利品系统
查 /qr 命令 → 命令大全

秘境与钥石（Realm × Keystone） ​

1. 一句话循环 ​

2. 钥石怎么来、怎么用 ​

2.1 拿到钥石 ​

2.2 激活秘境 ​

2.3 钥石外观（realm.keystone） ​

3. 层数曲线（realm.tiers） ​

4. 词缀注入与危险预算 ​

5. 净化奖励（realm.reward） ​

6. 重铸赌博（realm.reroll） ​

7. 失败、放弃与限时 ​

8. 天梯概率（realm.keystone-chance / realm.next-tier-chance） ​

9. Bossbar 与外观 ​

10. 相关占位符 ​

下一步 ​

秘境与钥石（Realm × Keystone）

1. 一句话循环

2. 钥石怎么来、怎么用

2.1 拿到钥石

2.2 激活秘境

2.3 钥石外观（`realm.keystone`）

3. 层数曲线（`realm.tiers`）

4. 词缀注入与危险预算

5. 净化奖励（`realm.reward`）

6. 重铸赌博（`realm.reroll`）

7. 失败、放弃与限时

8. 天梯概率（`realm.keystone-chance` / `realm.next-tier-chance`）

9. Bossbar 与外观

10. 相关占位符

下一步