战利品系统（loottables）

所属：服主指南　·　相关：秘境与钥石 · 词缀系统 · 蓝图与目标 · 占位符 · 命令大全

QR 的产出由一张张战利品表（loottables/*.yml）驱动，通过三种发放渠道送到玩家手里：

渠道	触发方式	谁来分	成长度缩放	详见
① 容器战利品	结构里摆原版箱子/木桶/熔炉…，右键开	每人独立 / 全服共享	是（per-player 时）	§3
② 蓝图奖励箱	通关解锁后右键宝箱方块	每人独立	是	§4
③ 净化老虎机	秘境净化后 /qr reward 摇奖	按参与者私发	是	§5

🔑 一张表可以同时服务多个渠道——它只是一份「滚什么、滚几次」的配方，由模板/蓝图指定谁来引用它。

🖼️ [图片占位] 三渠道发放流程总览图（表 → 容器/奖励箱/老虎机 → 玩家）　·　建议 assets/loot-overview.png

---

一、战利品表放在哪、怎么加载

所有表都是 plugins/QinhRuins/loottables/ 下的 .yml 文件，文件名（去掉 .yml）就是表名。例如 loottables/vault.yml 的表名是 vault，在模板里写 loot.container-table: vault 即可引用。

QR 自带三张示例表：

文件	表名	典型用途
default.yml	default	编辑器标记宝箱的兜底表（防「奖励表缺失」）
vault.yml	vault	容器战利品 + 条件分组演示
realm.yml	realm	秘境净化独占大奖（config.yml 默认引用）

改完 /qr reload 生效。

---

二、表结构全解

一张完整的战利品表可以用到以下字段（除 entries 外都可选）：

# loottables/vault.yml
rolls: 2                              # 主条目掷几次（每次按权重抽一个条目）
containers: [CHEST, BARREL]           # 仅作容器表时生效：限定哪些容器类型吃这张表（留空=全部）
# vanilla: minecraft:chests/simple_dungeon   # 可选：先掷一份原版战利品表，再叠加下面 entries
entries:                             # 主条目池
  - { item: "vanilla:DIAMOND",            weight: 10, amount: "1-3" }
  - { item: "vanilla:GOLD_INGOT",         weight: 20, amount: "2-5" }
  - { item: "vanilla:EXPERIENCE_BOTTLE",  weight: 15, amount: "2-6" }
groups:                             # 条件分组：满足 condition 才参与掷奖
  rich:
    condition: "%player_level% >= 5"  # 走 PlaceholderAPI；不装 PAPI 则此条件恒真
    rolls: 1
    entries:
      - { item: "vanilla:EMERALD", weight: 1, amount: 2 }

2.1 rolls —— 掷几次

rolls 决定这张表「掷几次」，每次都从条目池里按权重随机抽一个条目产出。rolls: 2 = 产出大约 2 件（同一条目可能被抽中多次）。最小为 1。

净化老虎机渠道不看 rolls——它把整张表（含分组）摊成一个奖池，从中只摇一个作为大奖（见 §5）。

2.2 entries —— 条目池

每个条目是一行 { ... }，字段如下：

字段	必填	说明
item	✅	物品来源串，见 §2.6
weight		权重（越大越常出），不写默认 1，最小 1
amount		数量，可写定值 2 或区间 "2-5"（每次在区间内随机），不写默认 1
min-growth		成长度门槛：玩家成长度低于此值则该条目不参与本次掷奖，见 §6.2
unique		true 时受秘境「秘藏」词缀加权（掉率 ×倍数），见 §6.4

entries:
  - item: "vanilla:NETHERITE_SCRAP"
    weight: 8
    amount: "1-2"
    min-growth: 30        # 成长度 ≥30 才可能掉
    unique: true          # 受「秘藏」词缀加权的独占好物

提示

amount 区间写反（如 "5-2"）会被自动纠正为 2-5，不必担心。

2.3 groups —— 条件分组

groups 是「满足条件才开」的额外条目池。每个分组有自己的 condition、rolls、entries。主 entries 永远掷；分组只在 condition 为真时才追加掷一轮。

groups:
  rich:                                 # 分组名任意（仅作标识）
    condition: "%player_level% >= 5"    # 见下方条件规则
    rolls: 1                            # 这一组单独掷几次
    entries:
      - { item: "vanilla:EMERALD", weight: 1, amount: 2 }
  vip:
    condition: "%vault_eco_balance% >= 10000"
    rolls: 1
    entries:
      - { item: "qi-legendary_chest", weight: 1 }

condition 规则（与 秘境词缀脚本 / QS 条件 同源思路）：

• 写成 左值 比较符 右值，左右两侧先经 PlaceholderAPI 解析再比较。
• 比较符支持：>=　<=　==　!=　>　<。
• 两侧都能转成数字 → 数值比较；否则按字符串比较（仅 == / != 有意义，大小写不敏感）。
• 留空或解析不出比较符 = 恒真——所以没装 PlaceholderAPI 时 condition 一律视为通过，分组照常发放。

condition: "%player_level% >= 5"       # 等级≥5
condition: "%player_world% == world"   # 在主世界（字符串相等）
condition: ""                          # 恒真（等价于不写 condition）

2.4 vanilla —— 叠加一份原版战利品表

填一个原版战利品表 ID，QR 会先掷一份原版战利品，再把上面的 entries / groups 叠加上去。适合「复用原版地牢/要塞掉落，再加自定义好物」：

vanilla: minecraft:chests/simple_dungeon   # 先掷一份地牢箱原版掉落
rolls: 2                                    # 再额外叠加 2 次自定义条目
entries:
  - { item: "qi-rune_shard", weight: 5, amount: "1-2" }

常用原版表 ID：minecraft:chests/simple_dungeon（地牢）、minecraft:chests/desert_pyramid（沙漠神殿）、minecraft:chests/end_city_treasure（末地城）等。

2.5 containers —— 限定容器类型（仅容器渠道）

只在作容器表时生效：声明这张表对哪些容器类型生效。留空 = 遗迹范围内所有容器都吃这张表；列出则只有这些类型生效。

containers: [CHEST, BARREL]     # 只有箱子和木桶生效；遗迹里的发射器/漏斗不掉

类型名是原版材质名（大写）：CHEST TRAPPED_CHEST BARREL FURNACE BLAST_FURNACE SMOKER BREWING_STAND DISPENSER DROPPER HOPPER SHULKER_BOX 等。 配合模板的 loot.container-tables（按类型分表）可做到「箱子掉宝、酿造台掉药水」，见 §3.3。

2.6 item —— 物品来源（任意插件）

item 走 QinhCoreLib 的 ItemManagerAPI 解析，支持任意已接入的物品源——一行就能从别的插件取物品：

前缀写法	来源
vanilla:DIAMOND / minecraft:diamond / DIAMOND	原版物品
qi-<id> / qinhitems:<id>	QinhItems
ni-<id> / neigeitems:<id>	NeigeItems
mi-<类型>:<id> / mmoitems:<类型>:<id>	MMOItems
ia-<id> / itemsadder:<id>	ItemsAdder
ce-<id> / craftengine:<id>	CraftEngine
nx-<id> / nexo:<id>	Nexo
mm-<id> / mythicmobs:<id>	MythicMobs 物品

entries:
  - { item: "qi-flame_saber",        weight: 3 }          # QinhItems 武器
  - { item: "mi-SWORD:cutlass",      weight: 2 }          # MMOItems
  - { item: "vanilla:DIAMOND",       weight: 10, amount: "1-3" }

解析失败（物品 ID 写错、对应插件没装）的条目会被静默跳过——这一次掷奖就少出一件，不会报错刷屏。

---

三、渠道① 容器战利品

在结构里摆原版容器（箱子/木桶/熔炉…），玩家右键打开即自动出战利品，不需要单独标记。容器是否属于某座遗迹，由该遗迹结构的占地范围（外接包围盒，结构的最小长方体边界）自动判定——容器落在结构包围盒内即归它，无需配半径。

总开关与界面在 config.yml 的 vessel 段：

vessel:
  enabled: true                  # 容器战利品总开关
  refresh-mode: per-player-once  # per-player-once=每人仅一次 | timed=冷却后可再开重滚
  refresh-cooldown: 30m          # timed 模式的重滚冷却（30m / 1h / 2h…）
  rows: 3                        # 打开的容器界面行数（1-6）

模板侧要指定用哪张表和模式（在 templates/<id>/template.yml）：

# template.yml 片段
loot:
  mode: per-player          # 见 §3.1
  container-table: vault    # 容器统一用 vault 表
  # container-tables:       # 或按容器类型分表，见 §3.3
  #   CHEST: vault
  #   BREWING_STAND: potion_table

3.1 loot.mode —— 每人独立 vs 全服共享

模式	行为	成长度	适合
per-player（默认）	每人首次开各得一份自己的战利品，开过记账、剩下的留在界面里不变	✅ 按成长度缩放数量	多人服公平产出，人人有份
shared	直接往真实容器里塞一份战利品，全服共享、先到先得	❌ 中性发放（不吃成长度、不受 min-growth 门槛）	想要「抢箱子」竞争感、单人服

注意

关键差异：per-player 是 QR 给每位玩家开一个独立的虚拟界面（互不影响，关闭时自动保存未拿走的东西）；shared 是把物品真的填进世界里那个箱子，谁先拿谁得，且为公平起见不做成长度缩放、忽略 min-growth。

3.2 refresh-mode —— 能不能再开

• per-player-once（默认）：每位玩家对每个容器只能开一次，之后再右键就是上次留下的内容。
• timed：过了 refresh-cooldown 冷却后可再次开启并重新掷奖，做「定时刷新的补给点」。

3.3 按容器类型分表

loot.container-tables 让不同容器类型用不同的表，没列到的类型回退到 loot.container-table：

loot:
  mode: per-player
  container-table: vault        # 兜底：未单列的容器都用 vault
  container-tables:
    CHEST: treasure_table       # 箱子掉宝
    BREWING_STAND: potion_table # 酿造台专出药水（熔炉/酿造台会智能填入燃料/药水槽）

熔炉/高炉/烟熏炉/酿造台在 shared 模式下，QR 会把掉落智能填进对应槽位（燃料→燃料槽、药水→瓶位…），塞不下的掉落在容器上方。

---

四、渠道② 蓝图奖励箱（loot-chests）

蓝图里的解锁式宝箱：通关到指定阶段才能开，每人各开一次。在 blueprint.yml 的 loot-chests 段配置（坐标相对结构原点），详见 蓝图与目标。

# blueprint.yml 片段（坐标是相对结构原点的 x/y/z，直接写在条目上，不是 pos 子表）
loot-chests:
  - id: vault_main
    x: 8
    y: 3
    z: 8
    loot-table: vault          # 引用哪张表
    unlock-stage: 2            # 需推进到第 2 阶段才解锁（默认 1）
    per-player-once: true      # 每人仅开一次（默认 true）
    growth-scaled: true        # 数量按成长度缩放（默认 true）

字段	默认	行为
unlock-stage	1	当前有效阶段 ≥ 此值才解锁；未到则提示「宝箱尚未解锁」
per-player-once	true	开过记账，再开提示「你已开启过此宝箱」
growth-scaled	true	true 时数量按成长度缩放

奖励箱直接把战利品塞进背包（满了掉地上），并播放升级音效。它不经过 vessel 那套界面，是独立的解锁奖励逻辑。

---

五、渠道③ 净化老虎机（reward）

秘境净化（通关）后的独占大奖，以老虎机摇奖形式发放。玩家输入 /qr reward 打开转盘，点杠杆摇一次，从奖池里只摇出一件大奖。

工作流程

1. 秘境/遗迹被净化时，QR 给附近 48 格内每位玩家授予一次摇奖资格，并提示「通关大奖已就绪」。
2. 玩家 /qr reward 打开转盘 → 点击杠杆 → 动画滚动 → 定格出一件大奖直接进背包。
3. 资格一次性消耗，已领过提示「该奖励已领取」。

配的是哪张表

老虎机用的是模板的通关奖池表——在 template.yml 写 reward.clear-table（也是 vault.yml 注释里提到的用法）：

# template.yml 片段
reward:
  clear-table: vault     # 净化老虎机的奖池表

而秘境层（Realm）净化的独占战利品走的是另一套 config.yml 的 realm.reward（默认表 realm，按参与者私发、可叠加按层加成与货币），详见 秘境与钥石。两者都属于「净化产出」，但配置位置不同：

• template.yml 的 reward.clear-table → /qr reward 老虎机
• config.yml 的 realm.reward.loot-table → 秘境层独占私发

老虎机怎么选奖

老虎机把表的 entries + 所有满足条件的分组 entries 摊成一个奖池（受 min-growth 门槛过滤），按权重摇出一个，并按成长度缩放数量。奖池里没有适合该玩家成长度的条目时，提示「当前没有适合你成长度的奖励」。

---

六、成长度缩放与词缀联动

6.1 成长度（Growth）是什么

「成长度」是 QR 对玩家强度档位的统一读数，由 GrowthProvider 决定：

• 装了 QinhClass → 读职业等级；
• 否则装了 MMOCore → 读 MMOCore 等级；
• 都没装 → 回退原版经验等级。

它用在两处：战利品的 min-growth 门槛、以及数量缩放。

6.2 min-growth 门槛

条目的 min-growth 是「准入线」：玩家成长度低于它，这个条目就不参与本次掷奖（也不出现在老虎机奖池里）。用来锁住高级好物，逼玩家先成长。

例外：shared 模式容器忽略 min-growth（中性发放，见 §3.1）。

6.3 数量按成长度缩放

当渠道启用 growth-scaled（per-player 容器、奖励箱默认开、老虎机、秘境私发）时，掉落基础数量会按成长度放大：

缩放公式：数量 = 基础数量 × (1 + 成长度 / 200)，且保底不低于基础数量。 例：基础 4 个、成长度 100 → 4 × (1 + 0.5) = 6 个；成长度 200 → 8 个。

min-growth 控制「能不能掉」，growth-scaled 控制「掉多少」，两者配合让高成长玩家产出更肥。

6.4 词缀联动（greed / 秘藏）

秘境层的产出还会被 词缀 二次放大（仅作用于秘境净化私发那一路，见 秘境与钥石）：

词缀类	作用于	效果
贪婪 / 鎏金（greed）	全表数量	提高掷奖卷数 / 数量倍率
秘藏（hidden-trove）	unique: true 条目	把独占条目的权重 ×倍数，更容易摇到稀有

这些倍率与 config.yml 的 realm.loot-bonus（按层倍率，默认 1 层 1.1 倍 → 16 层 2.6 倍）叠乘：

# config.yml 片段
realm:
  tiers:
    loot-bonus: "1 + tier * 0.1"   # 按秘境层数放大数量；写 "1" 关闭按层加成

即：最终数量 ≈ 基础 × 成长度缩放 × 按层 loot-bonus × 贪婪倍率，独占条目额外吃秘藏权重加成。

---

七、占位符

战利品/进度相关占位符（需装 PlaceholderAPI），可用于 HUD、groups.condition、聊天等：

占位符	含义
%qinhruins_ruin%	当前所在遗迹名
%qinhruins_stage% / %qinhruins_max_stage%	当前阶段 / 总阶段
%qinhruins_stage_name%	当前阶段名
%qinhruins_completed%	是否已通关
%qinhruins_objective% / %qinhruins_progress%	当前目标 / 进度
%qinhruins_kills_<mob>%	对某怪的击杀数

完整列表见 占位符。

---

八、按需求快速配方

我想要…	怎么做
箱子里掉自定义物品	摆箱子 + loot.container-table 指一张含 qi- 等条目的表
人人有份、不抢	loot.mode: per-player
抢箱子竞争感	loot.mode: shared
高级好物锁等级	条目加 min-growth: 30
复用原版地牢掉落再加料	表里写 vanilla: minecraft:chests/simple_dungeon + 自定义 entries
VIP/高等级额外掉落	groups + condition: "%占位符% >= N"
通关大奖摇奖	template.yml 的 reward.clear-table + 玩家 /qr reward
酿造台专出药水	loot.container-tables: { BREWING_STAND: potion_table }

---

下一步

• 秘境与钥石：秘境层净化的独占私发、按层加成、货币
• 词缀系统：贪婪 / 秘藏等战利品词缀
• 向导与图鉴：图鉴里查看每座遗迹的战利品攻略卡
• 命令大全：/qr reward / /qr reload