PLUGIN DOCS

CySoulbound

灵魂绑定：把主手物品绑定给玩家，禁止丢弃、他人拾取/使用、容器转移和死亡掉落。

免费 v1.1.4 Paper 1.21.11

简介

CySoulbound 把主手物品绑定到玩家名下。绑定后的物品不能被主人丢弃，不能被其他玩家拾取、使用、装备、合成、附魔、铁砧、砂轮或锻造，死亡也不会掉落。

核心功能

/csl bind 绑定主手物品
/csl unbind 解绑主手，或按 ID 解绑
/csl list 查看自己的绑定物品，支持点击解绑
绑定 lore 标记，可配置格式
支持金币/点券收费与权限绕过
SQLite 持久化，支持离线玩家查询

支持环境

项目	要求
服务端	Paper 1.21.11
Java	Java 21
数据库	SQLite，插件自带
数据文件	`plugins/CySoulbound/data.db`
软依赖	Vault、PlayerPoints（收费时需要）
硬依赖	无

安装

把 CySoulbound-1.1.4.jar 放进 plugins/。
重启服务器，生成 config.yml 和 SQLite 数据库。
按需修改绑定上限、收费、保护开关。
执行 /cysoulbound reload，部分设置需要重启。

玩家命令

命令	作用
`/cysoulbound bind` / `/csl bind`	绑定主手物品
`/cysoulbound unbind` / `/csl unbind`	解绑主手物品
`/cysoulbound unbind <ID>` / `/csl unbind <ID>`	按绑定 ID 解绑
`/cysoulbound list` / `/csl list`	查看自己的绑定列表
`/cysoulbound list <页码>`	翻页
`/cysoulbound help`	查看帮助

list 里的「解绑」按钮可以直接解除对应绑定。

管理命令

需要 cysoulbound.admin。

命令	作用
`/csl admin bind <玩家>`	把主手物品强制绑定给指定在线玩家
`/csl admin unbind <玩家>`	强制解绑指定在线玩家主手物品
`/csl inspect`	查看主手物品的绑定信息
`/csl list <玩家> [页码]`	查看任意玩家的绑定列表
`/csl admin reload` / `/csl reload`	重载配置

权限

权限	默认	说明
`cysoulbound.use`	所有人	绑定、解绑、查看自己的列表
`cysoulbound.admin`	OP	管理他人绑定、重载
`cysoulbound.bypass`	OP	绕过所有灵魂绑定保护
`cysoulbound.economy.bypass`	关闭	只跳过绑定/解绑收费
`cysoulbound.limit.<数量>`	无	提高绑定上限，例如 `cysoulbound.limit.5`
`cysoulbound.limit.unlimited` / `*`	无	不限制绑定数量

配置

主配置在 plugins/CySoulbound/config.yml。

绑定规则

字段	默认	说明
`bind.max-per-player`	`1`	每人最多绑定件数，`-1` 不限制
`bind.allowed-materials`	空	允许绑定的材质；空表示全部
`bind.denied-materials`	空	禁止绑定的材质，优先级高于允许列表

bind:
  max-per-player: 1
  allowed-materials: []
  denied-materials: []

收费

economy:
  bind:
    enabled: true
    pay: money       # money / points
    amount: 10000
  unbind:
    enabled: false
    pay: money
    amount: 10000

保护开关

protect:
  drop: true
  pickup: true
  container: true
  use: true
  equip: true
  shulker: true
  item-frame: true
  armor-stand: true
  craft: true
  anvil: true
  enchant: true
  smithing: true
  grindstone: true
death:
  keep: true

关闭某一项就允许对应行为；death.keep: true 表示绑定物品死亡不掉落。

数据库与日志

database:
  file: "data.db"
logs:
  enabled: true
  retention-days: 7
  cleanup-time: "00:00"

界面/提示

绑定后在物品 lore 追加：

lore:
  enabled: true
  format: "&b[ 已绑定: {owner} ]"
  marker: "已绑定:"

marker 用于解绑时识别并删除本插件追加的 lore 行。

变量与 API

CySoulbound 当前版本没有公开 API，也没有注册独立的 PlaceholderAPI 变量。

许可证验证

本插件启用前会校验许可证：插件把 license.yml 里的许可证号发送到授权服务器，服务器用私钥签名，插件用内置公钥验证签名。校验不通过时插件不会启用。

首次启动

必须联网：第一次启动没有缓存，联网校验失败会直接停止加载。
首次启动会在插件目录生成 license.yml。
控制台出现「许可证验证通过」表示正常。

license.yml

# 插件目录下的 license.yml
license:
  key: "CYP-XXXX-XXXX-XXXX"

许可证号在网站用户中心查看，一个账号只有一个许可证，所有插件共用。

免费插件与付费插件

类型	是否需要填许可证	说明
免费插件	不需要	留空即可，插件仍会联网确认「免费」状态
付费插件	需要	先用兑换码在网站开通，再填入许可证号

心跳与缓存

运行期间每小时向服务器发一次心跳。
服务器临时无法连接时，有 7 天宽限期，期间插件继续可用。
服务器明确返回「许可证无效 / 已被禁用」时，立即停止，没有宽限。
插件被禁用后，需要到网站解绑或联系作者处理。

常见问题

控制台提示「无法连接验签服务器」

检查服务器能否访问 https://license.mc33.top，以及是否只启用了 IPv6（授权站仅支持 IPv4）。

提示「当前许可证未开通本插件」

到网站兑换码页面输入兑换码开通，或确认购买的是这个插件。

提示「IP 数量已达上限」

每个插件最多绑定 2 个 IP，到用户中心解绑旧服务器后再启动。

更换服务器后无法启动

旧 IP 仍占用名额，先在网站解绑，再在新服务器启动。

常见问题

绑定后还能交易吗？

不能。其他玩家无法拾取、使用、装备、合成、附魔、铁砧、砂轮或锻造；主人也不能丢弃。

为什么绑定收费失败？

检查 Vault 或 PlayerPoints 是否安装、economy.bind.pay 是否对应、余额是否足够。cysoulbound.economy.bypass 可跳过收费，但不会绕过保护。

绑定数量上限怎么改？

改 bind.max-per-player，或给玩家 cysoulbound.limit.<数量> 权限；多个节点取较高值。

解绑后 lore 会删掉吗？

会。插件按 lore.marker 找到自己追加的行并删除，不会动其他 lore。

数据库能手动改吗？

不建议。先备份 plugins/CySoulbound/data.db，再操作。

更新日志

按时间倒序，最新的在最上面。当前版本是 1.1.3。

1.1.3（2026-10-22 · 当前版本）

当前构建版本；完整记录见项目根目录 更新日志.md。

1.1.0（2026-10-19）

灵魂绑定主流程、保护开关、收费和列表解绑。

1.0.0（2026-10-19 · 首发）

主手绑定、SQLite 持久化、死亡保留和基础保护。

获取插件全部文档