跳到主要内容

配置文件

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

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

所有配置文件支持热重载，执行 /tsl reload 即可生效。

config.yml — 全局配置​

控制宝箱的显示行为、物品掉落规则和数据库连接。

view:
  refresh: 600
  distance: 16
  async: true
  virtualize_ui: false

drop_owner: true

code:

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

view — 显示与发包​

配置项类型默认值说明
refresh整数 (tick)600定时刷新宝箱显示的间隔。600 tick = 30 秒。除定时刷新外，玩家进服、传送、切换世界也会触发刷新
distance整数 (格)16宝箱显示距离。只有玩家在此范围内才会收到虚拟方块数据包。值越大客户端负担越重，建议 16~32
async布尔true是否异步发送数据包。开启可减轻主线程压力。网易服（基岩版互通）必须关闭，否则可能导致发包异常
virtualize_ui布尔false是否虚拟化宝箱 GUI 界面。BungeeCord 子服环境下可能出现异常，遇到问题请关闭
性能建议
  • refresh 值越小刷新越频繁，对大量在线玩家的服务器建议适当调大（如 1200）
  • distance 建议不超过 32，过大会增加不必要的发包量

drop_owner — 掉落物归属​

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

database — 数据库​

配置项类型默认值说明
enable布尔true是否使用 MySQL。关闭则使用本地 SQLite
host字符串localhost数据库地址
port整数3306数据库端口
user字符串root用户名
password字符串root密码
database字符串minecraft数据库名
table字符串ce_treasure数据表名
警告

数据库功能目前为预留配置，暂未启用。当前版本数据存储使用本地文件。

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'
参数说明
世界名世界文件夹名称，如 world、world_nether
X, Y, Z方块坐标（整数）
朝向可选。north、south、east、west，不填则随机朝向
提示

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

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

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

generator:
  normal:
    # 全局刷新周期（tick），36000 = 30 分钟
    # 设为 0 则只有配置了 cooldown 的坐标组生效
    period: 36000

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

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

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

逐项说明：

配置项类型说明
period整数 (tick)全局刷新周期。所有未配置独立 cooldown 的坐标组使用此值。设为 0 则只有 cooldown 中列出的坐标组会刷新
cooldown.<组名>整数 (tick)为指定坐标组设置独立刷新时间，覆盖全局 period
public.<宝箱>列表公共宝箱。列出的坐标组中，宝箱被任意一个玩家领取后，所有玩家都看不到该坐标的宝箱，直到下次刷新
treasure.<宝箱>.<组名>Kether 条件将宝箱文件绑定到坐标组。值为 Kether 条件表达式，"true" 表示无条件显示
刷新机制细节
  • 刷新周期修改后，需要重启服务器才能生效（不是 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: 36000

    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

随机规则​

规则格式说明
groundground#最大Y从指定高度往下扫描，找到第一个非空气方块，在其上方放置宝箱。适合地表生成
rangerange#最小Y~最大Y#方块类型在 Y 范围内随机选择坐标。适合矿洞、地下城等场景

其他参数​

参数类型说明
max整数或范围该区域内生成的最大宝箱数量，支持范围写法如 3~5
chest字符串宝箱文件名（不含 .yml 后缀）
ifKether 条件可选。满足条件的玩家才会生成该区域的宝箱，默认 "true"

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

每个 .yml 文件定义一种宝箱类型，文件名即宝箱 ID。插件会递归加载 treasures/ 目录下所有 .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"）或详细对象配置
lock_inventory布尔false开启后玩家在宝箱 GUI 中无法点击自己背包内的物品
open_key对象—钥匙配置。不写此节点则无需钥匙即可开箱

claim — 奖励生成​

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

events — 事件脚本​

事件触发时机常用场景
open钥匙检查通过后、GUI 打开前播放音效、发送提示。可用 tsl-cancel 取消开箱
closeGUI 关闭时自动领取剩余奖励（tsl-claim）
claim玩家点击领取单个奖励时发送领取提示。可用 &amount 获取数量
spawn宝箱方块发包显示时发送发现提示。可用 &chest-world/&chest-x/&chest-y/&chest-z

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

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

第一步：创建宝箱文件 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: 0
    cooldown:
      daily_spots: 1728000  # 24 小时 = 1728000 tick
    treasure:
      daily:
        daily_spots: "true"

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