跳到主要内容

配置文件

看不懂这些配置项？

本页是按配置文件组织的参考手册。如果你想要从零开始、一步一步跟着做的版本，请看 详细版教程。

TreasuresLite 有三类配置文件，分别控制不同层面的行为：

文件路径作用
config.ymlplugins/TreasuresLite/config.yml全局设置（显示、发包、掉落归属、预留数据库配置）
location.ymlplugins/TreasuresLite/location.yml坐标分组、刷新规则、生成器
treasures/*.ymlplugins/TreasuresLite/treasures/每个宝箱的独立配置（外观、奖励、钥匙、事件）

所有配置文件支持热重载，执行 /tsl reload 即可生效。config.yml 与 location.yml 还开启了自动重载，直接保存文件也会触发一次重载，并顺带重启内部周期任务、刷新在线玩家数据。

config.yml — 全局配置​

控制宝箱的显示行为、物品掉落规则和预留数据库配置。

view:
  refresh: 30000
  distance: 16
  # 兼容旧配置：该选项已停用，虚拟方块与动画固定按顺序同步发包
  async: false

  virtualize_ui: false

drop_owner: true


database:
  enable: true
  host: localhost
  port: 3306
  user: root
  password: root
  database: minecraft
  table: "lite_treasure"

view — 显示与发包​

配置项类型默认值说明
refresh整数 (毫秒)30000定时刷新宝箱显示的间隔。30000 毫秒 = 30 秒。除定时刷新外，玩家进服、传送、切换世界也会触发刷新
distance整数 (格)16宝箱显示距离。只有玩家在此范围内才会收到虚拟方块数据包。值越大客户端负担越重，建议 16~32
async布尔false已停用的兼容项。当前版本的虚拟方块与动画固定按顺序同步发包，填 true 不会改变行为，只会在启动时输出一条 view.async 已停用 告警
virtualize_ui布尔false是否虚拟化宝箱 GUI 界面。BungeeCord 子服环境下可能出现异常，遇到问题请关闭。另外该项只在宝箱未开启 lock_inventory 时才会实际生效
性能建议
  • refresh 值越小刷新越频繁，对大量在线玩家的服务器建议适当调大（如 60000）
  • distance 建议不超过 32，过大会增加不必要的发包量
  • 定时刷新走差集对账，只补发发生变化的坐标；玩家进服、传送、切换世界时才会强制全量重发

drop_owner — 掉落物归属​

配置项类型默认值说明
drop_owner布尔true当玩家背包满时，领取的奖励物品会掉落到地面。开启后掉落物只有该玩家能拾取，防止被其他人捡走

database — 数据库​

配置项类型默认值说明
enable布尔true预留开关。当前源码未读取该配置
host字符串localhost数据库地址
port整数3306数据库端口
user字符串root用户名
password字符串root密码
database字符串minecraft数据库名
table字符串lite_treasure数据表名
警告

数据库功能目前为预留配置，暂未启用；源码中没有读取 database 节点的实际逻辑。不要依赖这里的数据库连接项来判断当前版本的数据存储方式。

location.yml — 坐标与刷新规则​

这是 TreasuresLite 最核心的配置文件，决定了宝箱在哪里生成、多久刷新、谁能看到。

文件分为两大部分：location（坐标分组）和 generator（生成器规则）。

location — 坐标分组​

定义固定坐标点，供后续生成器引用。每个分组包含一组坐标，格式为 世界名, X, Y, Z, 朝向，五段都必须写全。

location:
  # 分组名可以自定义
  spawn_area:
    - 'world, 100, 65, 200, east'
    - 'world, 105, 65, 210, south'
  nether_area:
    - 'world_nether, 50, 40, 50, north'
    - 'world_nether, -30, 35, 80, random'
参数说明
世界名世界文件夹名称，如 world、world_nether。不能为空
X, Y, Z方块坐标（必须是整数）
朝向必填。只能是 north、south、east、west、random 五个值之一
五段缺一不可

固定坐标必须写满 世界名, X, Y, Z, 朝向 五段。少写朝向（如 'world, 0, 80, 0'）或填入其他朝向值，该行会解析失败并被跳过，控制台输出 无法解析坐标 location.<组名>[<序号>]='...'，这个刷新点不会生成宝箱。

固定坐标里的 random 只在配置加载时随机一次并固定下来，不会每次刷新都变。

提示

坐标分组只是定义"位置在哪"，具体哪个宝箱出现在哪个分组，由下方 generator 配置决定。

generator.normal — 固定坐标生成器​

将宝箱绑定到坐标分组，按周期刷新。

generator:
  normal:
    # 全局刷新周期（毫秒），1800000 = 30 分钟
    period: 1800000

    # 特定坐标组的独立刷新时间（覆盖全局 period）
    cooldown:
      spawn_area: 300000    # 5 分钟刷新一次
      nether_area: 3600000  # 1 小时刷新一次

    # 公共宝箱：一人领取后所有人都看不到，直到下次刷新
    public:
      def:
        - spawn_area

    # 宝箱与坐标组的绑定
    treasure:
      def:
        spawn_area: "true"
        nether_area: "check player level > 10"

逐项说明：

配置项类型说明
period整数 (毫秒)全局刷新周期。所有未配置独立 cooldown 的坐标组使用此值。填 0 或负数表示关闭这个全局周期任务，此时只有配了 cooldown 的坐标组还会自动刷新
cooldown.<组名>整数 (毫秒)为指定坐标组设置独立刷新时间，覆盖全局 period
public.<宝箱>列表公共宝箱。列出的坐标组中，宝箱被任意一个玩家领取后，所有玩家都看不到该坐标的宝箱，直到下次刷新
treasure.<宝箱>.<组名>Kether 条件将宝箱文件绑定到坐标组。值为 Kether 条件表达式，"true" 表示无条件显示
刷新机制细节
  • 周期任务使用服务端原生调度器，配置的毫秒值会按 50 毫秒一 tick 向上取整（最小 1 tick），启动时控制台会打印每个任务的实际周期
  • 刷新周期修改后，执行 /tsl reload 会重新加载配置并重启内部刷新任务；直接保存配置文件也会触发自动重载
  • 玩家退出服务器时会清理该玩家的缓存与显示记录
  • 玩家进服后普通坐标缓存需要先初始化完成才会显示，因此首次进服可能有短暂延迟
  • 如果同一物理坐标被多个来源占用，按 临时 > 固定 > 随机 的优先级只保留一个

条件表达式​

treasure 绑定支持 Kether 脚本作为条件。常见用法：

treasure:
  # 无条件显示
  daily_chest:
    spawn_area: "true"

  # 等级大于 10 才显示
  elite_chest:
    spawn_area: "check player level > 10"

  # 拥有特定权限才显示
  vip_chest:
    spawn_area: "check player perm vip.chest"

generator.random — 随机坐标生成器​

在指定区域内随机生成宝箱坐标，每个玩家的坐标独立随机。

generator:
  random:
    period: 1800000

    treasure:
      # 地表模式：从高处往下找到第一个实心方块
      - location: "world: 50,100 ~ -50,-100: ground#255: random"
        max: 5
        chest: def

      # 范围模式：在指定 Y 范围内随机
      - location: "world: 50,100 ~ -50,-100: range#0~40#air,stone,water"
        max: 4
        chest: def
        if: "check player level > 5"

location 格式​

世界名: X1,Z1 ~ X2,Z2: 随机规则: 朝向
部分说明
世界名生成区域所在的世界
X1,Z1 ~ X2,Z2矩形区域的两个对角坐标（只需 X 和 Z）
随机规则决定 Y 坐标的生成方式，见下表
朝向north/south/east/west/random。省略仍兼容为 random，但已弃用并会输出告警，建议始终显式写出

随机规则里的 random 会为每个最终采用的坐标单独随机一次，因此同一批宝箱的朝向可以各不相同。

随机规则​

规则格式说明
groundground#最大Y从指定高度往下扫描，找到第一个非空气方块，在其上方放置宝箱。适合地表生成
rangerange#最小Y~最大Y#方块类型在 Y 范围内随机选择坐标。方块类型可省略；填写后只接受当前位置材质在列表内的坐标。适合矿洞、地下城等场景

其他参数​

参数类型说明
max整数或范围该条规则尝试生成的宝箱数量，支持范围写法如 3~5
chest字符串宝箱文件名（不含 .yml 后缀）
ifKether 条件可选。满足条件的玩家才会生成该区域的宝箱，默认 "true"。默认配置中没有这一项，需要自己添加
多条规则如何合并

同一个 chest 配置多条规则时，结果按配置顺序合并而不是覆盖，因此上例的 def 最多会拿到 5 + 4 = 9 个坐标。

所有规则之间会按物理坐标去重，重复坐标不会占两个名额，插件会在剩余尝试次数内补抽。若地形不满足条件导致数量不足，控制台会输出实际生成数量和原因统计（重复、区块未加载、越界、材质不匹配、未找到支撑等）。

ground 规则和带材质过滤的 range 规则都需要读取方块，所在区块未加载时会直接跳过该候选坐标。

宝箱配置文件 — treasures/*.yml​

每个 .yml 文件定义一种宝箱类型，文件名即宝箱 ID。插件会递归加载 treasures/ 目录下所有 .yml 文件，子目录不构成命名空间，因此不同子目录下的同名文件会互相覆盖。启动时控制台会打印已加载的宝箱数量和 ID 列表，单个文件解析失败只会跳过该文件并输出告警。

首次启动只会自动释放 treasures/def.yml；源码里的 treasures/skull_test.yml 是头颅发包测试样例，不会自动生成到服务器配置目录。

完整结构概览​

# GUI 标题，支持颜色代码和 PlaceholderAPI
title: "奖励箱"

# GUI 字符布局
layout:
  - '#########'
  - ' 1111111 '
  - '#########'

# 宝箱设置（方块外观、钥匙、背包锁定）
settings:
  block: "CHEST"
  lock_inventory: true
  open_key: { ... }

# 事件脚本
events:
  open: |-
    tell "打开了宝箱"
  close: |-
    tsl-claim
  claim: |-
    tell "领取了奖励"
  spawn: |-
    tell "宝箱出现了"

# 可领取的奖励物品
claim:
  key: 1
  amount: 3~8
  layout: random
  generator: { ... }

# 装饰图标
icons:
  '#':
    material: "gray stained glass pane"
    name: " "

各节点的详细配置说明请参阅对应的功能文档：

节点详细文档
settings.block虚拟宝箱 — 方块外观配置
settings.open_key钥匙系统
layout / icons / eventsGUI 与动画
claim / generator奖励系统

settings — 宝箱设置​

配置项类型默认值说明
block字符串或对象—虚拟方块的外观。支持简化字符串（"CHEST"）、CraftEngine ID（"ce:xxx"）、头颅（"player_head:Notch"）或详细对象配置
type字符串—旧版方块外观写法。仅在没有 block 时才会被读取，两者同时存在时 block 生效
lock_inventory布尔false开启后玩家在宝箱 GUI 中无法点击自己背包内的物品
open_key对象—钥匙配置。不写此节点则无需钥匙即可开箱

claim — 奖励生成​

配置项类型默认值说明
key字符—对应 layout 中代表可领取槽位的字符
amount字符串"0"生成的奖励数量，支持范围写法如 3~8。不能超过布局里该字符的槽位总数
layout字符串"random"物品在槽位中的分布方式：random（随机）或 order（顺序）
generator对象—奖励物品定义，每个子键为一种奖励。详见 奖励系统
配置写错会导致宝箱打不开

claim 下的这几项有硬性校验，不满足时该宝箱的界面会构建失败，虚拟方块被还原成真实方块，控制台输出 构建宝箱 <ID> 的 GUI 失败：

  • amount 抽出的数量大于布局中可用奖励槽位数
  • generator 缺失或为空
  • 任意一个 generator 的 chance 不大于 0
  • 所有 generator 都是 unique: true，但 amount 超过了生成器个数
  • 单个 generator 的 amount 不在 1~2304 之间

events — 事件脚本​

事件触发时机常用场景
open钥匙检查通过后、GUI 打开前播放音效、发送提示。可用 tsl-cancel 取消开箱
closeGUI 关闭时自动领取剩余奖励（tsl-claim）
claim玩家点击领取单个奖励时发送领取提示。可用 &amount 获取数量
spawn—预留未生效。默认样例带有这一段，但当前版本不会执行它，&chest-* 变量也不存在
events.spawn 目前不会执行

默认 def.yml 里的 spawn 脚本和 {{ &chest-world }} 等变量属于预留配置，当前版本的开箱流程只会执行 open、close、claim 三个事件。写在 spawn 下的脚本不会有任何效果，也不会报错。

如果你需要在宝箱显示时做事情，只能通过插件提供的 Bukkit 事件 TreasureSpawnEvent 在其他插件里监听。

实战示例：从零配置一个每日宝箱​

下面演示如何创建一个每日刷新的宝箱，放在出生点附近，需要钥匙才能打开。

第一步：创建宝箱文件 treasures/daily.yml

title: "&6&l每日宝箱"

layout:
  - '#########'
  - ' 1111111 '
  - ' 1111111 '
  - '#########'

settings:
  block: "TRAPPED_CHEST"
  lock_inventory: true
  open_key:
    deny: |-
      tell "&c你需要一把每日钥匙才能打开"
    key:
      - check:
          material: "tripwire_hook"
          name: "每日钥匙"
        consume: true

events:
  close: |-
    tsl-claim

claim:
  key: 1
  amount: 3~5
  layout: random
  generator:
    diamond:
      chance: 20
      material: "diamond"
      amount: 1~3
      give: source
    iron:
      chance: 50
      material: "iron_ingot"
      amount: 3~8
      give: source
    gold:
      chance: 30
      material: "gold_ingot"
      amount: 2~5
      give: source

icons:
  '#':
    material: "gray stained glass pane"
    name: " "

第二步：配置坐标 在 location.yml 中添加：

location:
  daily_spots:
    - 'world, 100, 65, 200, east'
    - 'world, -50, 70, 150, south'

generator:
  normal:
    period: 86400000
    cooldown:
      daily_spots: 86400000  # 24 小时 = 86400000 毫秒
    treasure:
      daily:
        daily_spots: "true"

第三步： 执行 /tsl reload，然后用 /tsl open daily 测试效果。