快速开始

本页按“先能用，再深入调”的顺序说明 SakuraBind 的基础使用。

1. 安装并启动

1. 关闭服务端。
2. 安装必需依赖 NBTAPI。
3. 将 SakuraBind.jar 放入 plugins 目录。
4. 启动服务端，等待 plugins/SakuraBind 配置目录生成。
5. 确认控制台没有数据库或依赖下载报错。
6. 打开 settings.yml，删除或改写默认的 example 演示匹配器。

不要热加载

首次启动会下载运行库并初始化配置。热加载容易导致依赖、监听器或数据库状态异常。

2. 手动绑定一个物品

给玩家 Steve 手上拿着的物品绑定：

/sakurabind bind item Steve

解绑 Steve 手上的物品：

/sakurabind unBind item Steve

绑定时不写入 lore，只写入 NBT：

/sakurabind bind item Steve -noLore

3. 让玩家领取遗失物品

玩家默认拥有下面两个命令权限：

/sakurabind getLost
/sakurabind callback

getLost 会从插件暂存箱数据库取回物品到背包。callback 会切换个人召回模式，扫描器发现属于他的绑定物品时会尝试送回。

getLost 有 1 秒冷却。背包空间不足时，只会取出能放下的数量，剩余物品仍保留在暂存箱中，玩家腾出空间后再次执行即可。

callback 是内存中的开关，不是永久配置；重启服务端后需要玩家重新开启。

4. 自动绑定某类物品

不要用 OP 测试自动绑定

OP 默认拥有 sakurabind.bypass.all。拥有该权限的玩家会被大多数绑定监听和扫描器跳过，因此点击、捡起、丢弃、扫描器等自动绑定触发点可能不会生效。

测试自动绑定时，请使用非 OP 玩家账号，或在权限插件中对测试玩家显式取消 sakurabind.bypass.all。

编辑 plugins/SakuraBind/settings.yml，添加匹配器：

matchers:
  auto_swords:
    match:
      material: '.*_SWORD'
    settings:
      auto-bind:
        enable: true
        onClick: true
        onScanner: true
      item-deny:
        drop@: true
        click@: true

保存后执行：

/sakurabind reload settings.yml

效果：

• 玩家点击剑或被扫描器扫描到剑时自动绑定。
• 非物主不能丢弃或从容器拿走该绑定剑。
• 物主因 @ 规则会读取相反值，所以可以正常操作。

不要全局自动绑定

通常不要在 global-setting.yml 里直接开启 auto-bind.enable。全局开启后，普通物品也可能在点击、扫描、捡起等触发点被批量绑定。

5. 开启方块或实体绑定

默认只启用物品绑定。若要使用方块或实体绑定，编辑 config.yml：

block-listener: true
entity-listener: true

保存后重启服务端。

绑定玩家前方方块：

/sakurabind bind block Steve

绑定玩家前方实体：

/sakurabind bind entity Steve

实体绑定命令只在 Minecraft 1.13+ 可用。

6. 调整遗失物品送回顺序

默认顺序：

send-back-queue:
- player
- ender-chest
- database

推荐至少保留 database，否则背包和末影箱都满或玩家离线时，剩余物品可能无法保存。

7. 什么时候需要重启

可以直接 /sakurabind reload 的内容：

• 大多数 config.yml 普通键
• global-setting.yml
• settings.yml
• lang.yml
• 日志格式和过滤项

需要重启的内容：

• block-listener
• entity-listener
• send-back-database
• 模块总开关，例如 modules/bind-item.yml enable
• 日志文件路径
• 部分缓存大小

配置文件注释写了“重启生效”的，以配置注释为准。