灵魂绑定

所属：服主指南　·　相关：物品定义 · 配置文件

灵魂绑定（Soulbound）让物品绑定到某个玩家后，只有归属者能用、不可丢弃 / 交易 / 死亡掉落，连放进潜影盒里的绑定物都受保护。

1. 绑定怎么触发

方式	说明
拾取自动绑定	物品 `options.bind_on_acquire: true` 且 `soulbound.auto-bind-on-pickup: true`，无主物品被玩家拾取时自动绑定
命令	`/qi soulbind [level]` 绑定主手物品到自己；`/qi unsoulbind` 解绑
API	`QinhItemsAPI.bindSoulbound(item, player, level)`

绑定状态存在物品实例数据：soulbound_owner（UUID 串）、soulbound_level（整数等级）。

yaml

my_legendary:
  options:
    bind_on_acquire: true      # 拾取即绑

2. 保护规则

SoulboundProtectionListener 拦截以下行为（非归属者）：

行为	事件	拦截条件
丢弃绑定物	PlayerDropItemEvent	归属者不符 → 拒绝
丢弃含绑定物的容器	PlayerDropItemEvent	容器内有绑定物 → 拒绝
拾取他人绑定物	EntityPickupItemEvent	归属者不符 → 拒绝
背包移动绑定物	InventoryClickEvent	归属者不符 → 拒绝并刷新背包
拖拽绑定物	InventoryDragEvent	同上
破坏含绑定物的容器方块	BlockBreakEvent	容器内有绑定物 → 拒绝
死亡掉落	PlayerDeathEvent	归属者的绑定物从掉落中移除，存入待归还
重生归还	PlayerRespawnEvent	把绑定物还回背包，溢出自然掉落

绕过权限：持有 qinhitems.bypass.soulbound（默认值见 config）的玩家跳过所有限制。

3. 容器深扫描

SoulboundContainerScanner 会递归扫描嵌套容器（潜影盒），最深 8 层，防止「把绑定物塞进潜影盒再丢 / 破坏」绕过保护。死亡时抽出归属者的绑定物，重生时归还。

由 soulbound.scan-containers: true 控制（默认开）。

4. 配置项

config.yml 的 soulbound 段：

yaml

soulbound:
  enabled: true                          # 总开关
  lore-format: "&7{owner}的物品"          # 绑定 Lore 模板，占位 {owner} {level}
  auto-bind-on-pickup: true              # 拾取自动绑定（需物品 bind_on_acquire）
  scan-containers: true                  # 深扫容器
  bypass-permission: "qinhitems.bypass.soulbound"
  message-cooldown-ticks: 20             # 拒绝提示冷却（tick），20×50=1000ms
  messages:
    drop: "&c该物品已被灵魂绑定，无法丢弃。"
    pickup: "&c该物品属于 {owner}，你无法拾取。"
    move: "&c该物品属于 {owner}，你无法移动。"
    container: "&c该容器内存放着已绑定的物品，无法破坏。"
    container-drop: "&c「{container}」中存有绑定物品，不可丢弃。"

键	默认	含义
`enabled`	true	总开关
`lore-format`	`&7{owner}的物品`	绑定 Lore 行（`{owner}` 玩家名、`{level}` 等级）
`auto-bind-on-pickup`	true	拾取自动绑定
`scan-containers`	true	深扫嵌套容器
`bypass-permission`	`qinhitems.bypass.soulbound`	绕过权限
`message-cooldown-ticks`	20	重复拒绝提示间隔
`messages.*`	见上	各场景拒绝提示

5. Lore 显示

绑定后，物品 Lore 会追加一行（按 lore-format）：

§7Steve的物品

由结构化 Lore 的「灵魂绑定」段渲染，读取变量 soulbound.owner / soulbound.level。

🖼️ [图片占位] 绑定物品 hover，底部显示「xxx 的物品」　·　建议 assets/soulbound-lore.png

6. 开发者 API

kotlin

QinhItemsAPI.isSoulbound(item): Boolean
QinhItemsAPI.getSoulboundOwner(item): UUID?
QinhItemsAPI.bindSoulbound(item, player, level = 0)
QinhItemsAPI.clearSoulbound(item)

💡 给市场 / 邮件插件作者：上架 / 邮寄前应检查 isSoulbound，绑定物品不应被交易。详见 API 参考。

下一步

附魔上限
API 参考：绑定相关 API

灵魂绑定 ​

1. 绑定怎么触发 ​

2. 保护规则 ​

3. 容器深扫描 ​

4. 配置项 ​

5. Lore 显示 ​

6. 开发者 API ​

下一步 ​