钥匙系统

概述

TreasuresLite 使用物品特征匹配作为钥匙系统。玩家需要手持符合条件的物品才能打开宝箱。钥匙检查基于手持物品的材质、名称、Lore、CustomModelData 等属性进行多维度匹配。

这不是虚拟钥匙，而是直接检查玩家手上的物品是否满足条件。

配置位置

钥匙配置在宝箱文件的 settings.open_key 节点下：

settings:
  open_key:
    deny: |-
      tell inline "没有足够的钥匙 {{ &has_amount }} / {{ &required_amount }}"
    key:
    # 特征检查
    - check:
        # 材质完全匹配
        material: "paper"
        # 名字判断包含
        name: "钥匙"
        # lore 列表中的每一项都需要匹配
        lore:
          - "这是个钥匙"
        # custom_model_data 仅支持 Minecraft 1.14+
        custom_model_data: 1
        amount: 10
      # 是否消耗，默认 true
      consume: true
    - check:
        custom_model_data: 10086
      consume: false

配置说明

deny

当玩家手持物品不满足任何钥匙条件时执行的 Kether 脚本。可用变量：

变量	说明
`&has_amount`	玩家手持物品的数量。手上没东西时为 `0`
`&required_amount`	本次需要的数量。没有任何条件匹配时，取所有钥匙条件中要求数量最小的那个
`&consume`	是否需要消耗

key 列表

key 是一个列表，每个条目定义一种可接受的钥匙。玩家手持物品只要匹配其中任意一个条目即可打开宝箱。

check 检查条件

配置项	匹配方式	说明
`material`	完全匹配	物品材质，如 `paper`、`diamond`
`name`	包含匹配	物品名称中包含指定文本即可，比较前会去掉颜色代码
`lore`	逐条包含匹配	你写的每一条 lore 都必须能在物品 Lore 的某一行里找到，比较前会去掉颜色代码
`custom_model_data`	完全匹配	CustomModelData 值。仅 Minecraft 1.14+ 有效
`amount`	数量检查	需要的最低数量，默认 1，必须是大于 0 的整数

所有 check 条件都是可选的，只填写需要检查的项即可。填写的所有条件必须同时满足。

lore 是"全部都要有"

如果你写了三条 lore 条件，物品必须同时满足这三条才算匹配，而不是命中任意一条就通过。物品自身有多余的 lore 行不影响匹配。

1.14 以下不要用 custom_model_data

在低于 1.14 的服务端上配置了 custom_model_data，插件启动时会输出告警说明该条件不会匹配，这个钥匙条件将永远无法通过。默认 def.yml 里这一行是注释掉的。

钥匙只认主手

钥匙检查只读取玩家主手的物品，副手无效。手上为空或数量为 0 时直接判定失败。

consume

是否消耗钥匙物品，默认 true。设为 false 则只检查不消耗。

检查与消耗的时机

理解这个顺序有助于排查"钥匙被吞了但没开箱"之类的问题：

玩家右键宝箱，插件检查主手钥匙。不通过就执行 deny 脚本，并立即把虚拟宝箱重新发给玩家
通过后执行 events.open 脚本和 TreasureOpenEvent
再检查一次钥匙，因为上一步的脚本可能改动了玩家手持物
构建并打开 GUI，确认玩家确实拿到了界面
再次确认该坐标仍然对玩家可见
以上全部通过后才扣除钥匙，然后移除该坐标的宝箱数据、播放开箱动画

任何一步失败都会还原虚拟宝箱且不扣钥匙。因此钥匙不足时宝箱不会消失，插件会立即重发一次、并在 1 tick 后再补发一次。

管理员命令也要带钥匙

/tsl open <宝箱ID> 同样会执行钥匙检查。测试配了钥匙的宝箱时，手上也需要拿着对应钥匙。

不配置钥匙

如果宝箱文件中不写 settings.open_key 节点，则该宝箱无需钥匙即可直接打开。

写了 open_key 但没有有效条件会锁死宝箱

如果 open_key 存在，但 key 列表为空、或所有条目都因为格式错误被跳过，插件会输出 该宝箱将拒绝开启，此时任何人都打不开这个宝箱。

配置写错时的控制台提示

启动或 /tsl reload 时，插件会逐条校验钥匙配置并输出可定位的告警：

控制台提示	原因
`open_key.key[N] 不是对象，已跳过`	该条目没写成 `- check:` 结构
`open_key.key[N].check 缺失或格式错误，已跳过`	缺少 `check` 子节点或格式不对
`open_key.key[N].check.custom_model_data 不是整数`	该值必须是整数
`open_key.key[N].check.amount 不是整数，已跳过`	`amount` 必须是整数
`open_key.key[N].check.amount 必须大于 0，已跳过`	`amount` 填了 0 或负数
`open_key.key[N].check 没有可识别条件，已跳过`	`check` 下没有任何一个有效检查项
`宝箱 X 已加载 N 个钥匙条件`	加载成功，N 就是实际生效的条件数

开启 /tsl debug 后，还能看到每次匹配的详细结果，包括命中的是第几个条件、持有数量、需要数量，以及扣除后主手剩余数量。

多钥匙示例

可以配置多种钥匙，满足任意一种即可开箱：

settings:
  open_key:
    deny: |-
      tell "你没有合适的钥匙"
    key:
    # 钥匙方案一：10 个纸质钥匙，消耗
    - check:
        material: "paper"
        name: "钥匙"
        amount: 10
      consume: true
    # 钥匙方案二：VIP 令牌，不消耗
    - check:
        custom_model_data: 10086
      consume: false

概述​

配置位置​

配置说明​

deny​

key 列表​

check 检查条件​

钥匙只认主手​

consume​

检查与消耗的时机​

不配置钥匙​

配置写错时的控制台提示​

多钥匙示例​

概述