原创 工具 经济 MCBinding —— 让绑定物品自动归位吧 | 物品绑定 | 轻量化 | 自动上绑 | 绑定召回 | 手动绑定 1.5.2

[MD] # MCBinding｜让绑定物品自动归位的安全回收插件 > **拿错的物品自动收回，真正的主人随时取回。** > 支持 NBT / Lore 识别、拾取与物品栏自动绑定、SQLite / MySQL 持久化，以及箱子式取回界面。 ## 插件信息 | 项目 | 说明 | | -------- | ------------------------------------------------------------ | | 当前版本 | **1.5.2** | | 服务端 | **Paper 1.12.2 及以上** | | Java | 遵循对应服务端要求，最低 Java 8 | | 存储 | SQLite（默认） / MySQL 8.0+ | | 前置依赖 | **无**；NBT-API、FastInv 与 MySQL Connector/J 均已内嵌隔离 | | 获取方式 | QQ 群**1090296532** | ## 为什么需要 MCBinding？ RPG、生存、职业与副本服务器经常会给装备写入“绑定玩家”。但只有绑定标记还不够：物品仍可能因交易、容器、插件发放或误操作落到其他玩家手中。 MCBinding 会持续守住这一层边界： - 普通物品：不处理； - 属于当前玩家的绑定物品：正常使用； - 属于其他玩家的绑定物品：自动收走并安全保存； - 真正的绑定玩家：输入 `/bounditems`，从箱子界面领回。 即使服务器重启，尚未领取的物品也会保留。 ## 核心功能 ### 🔐 NBT 与 Lore 双重识别 既可读取物品自定义 NBT，也可按固定 Lore 模板识别绑定玩家。正式服推荐以 **UUID** 作为身份标识，避免玩家改名后失配。 ### ♻️ 错持物品自动回收 插件会检查主背包、快捷栏、副手和盔甲栏。物品一旦落入非绑定玩家手中，就会被收回并写入持久化存储，不直接丢弃，也不掉落到地面。 ### ⚡ 自动绑定覆盖更多场景 1.5.2 不只支持拾取绑定，还能处理点击、拖拽、换手、关闭界面、登录等物品栏变化；其他插件直接放入背包的物品，也有每秒一次的扫描兜底。 ### 📦 箱子式取回 绑定玩家执行 `/bounditems` 即可打开取回箱。普通左键领取；如果背包空间不足，记录会继续保留，不会吞物品。 ### 💾 SQLite / MySQL 持久化 单服可开箱即用 SQLite，也可切换 MySQL 8.0+。驱动已经内嵌，无须安装数据库前置或额外配置 JVM 参数。 ### 🚀 面向在线服优化 每秒兜底扫描按玩家 UUID 分散到 20 个 tick，同一玩家短时间内的多次扫描请求会合并。300 份满背包等价负载测试中，两轮 spread p99 均低于 1 ms、TPS 保持 20。 > 上述数据是等价负载测试结果，不等同于 300 个真实网络连接的整服压测。 ## 快速安装 1. 停止服务器，并备份现有的 `plugins/MCBinding` 目录。 2. 将 `MCBinding-1.5.2.jar` 放入服务端 `plugins` 目录。升级时请先删除旧版 JAR，避免同时加载两个版本。 3. 启动服务器。首次启动将生成 `plugins/MCBinding/config.yml`，默认使用 SQLite，并创建 `database.db`。 4. 按服务器实际使用的绑定格式修改配置，然后执行 `/bounditems reload`。 5. 手持一件测试用绑定物品，执行 `/bounditems inspect`，确认插件识别到正确的玩家 UUID。 ## 配置示例 ```yaml binding: # 若绑定信息保存的是玩家名，请改为 NAME identifier-type: UUID strategies: - type: NBT enabled: true path: "PublicBukkitValues.myplugin:bound_player" - type: LORE enabled: true match-mode: FIXED_TEMPLATE templates: - "&7绑定玩家：{player_id}" auto-bind: enabled: true trigger-on: - PICKUP - INVENTORY_UPDATE trigger-lore: - "&7拾取后绑定" bound-lore: "&7绑定玩家：{player_id}" ``` `{player_id}` 会按 `identifier-type` 写入 UUID 或玩家名。Lore 匹配采用整行精确匹配；已经绑定的物品不会被重新绑定。 ## 命令与权限 | 命令 | 权限 | 用途 | | ------------------------------------- | --------------------- | -------------------------- | | `/bounditems` | `bounditems.retrieve` | 打开自己的取回箱 | | `/bounditems help` | 无 | 查看版本与可用命令 | | `/bounditems reload` | `bounditems.admin` | 重载并检查普通配置 | | `/bounditems inspect` | `bounditems.admin` | 检查主手物品的绑定识别结果 | | `/bounditems list <player>` | `bounditems.admin` | 查看指定玩家的待领取物品 | | `/bounditems delete <记录ID> confirm` | `bounditems.admin` | 永久删除一条待领取记录 | `bounditems.retrieve` 默认对玩家开放，`bounditems.admin` 默认仅管理员可用。`bounditems.bypass` 会让玩家跳过全部检查，除非确有需要，请勿授予。 ## 服主须知 - 数据库类型、地址、端口或账号等连接配置变更后，必须**完整重启服务器**；`/bounditems reload` 不会热切换数据库连接。 - SQLite 与 MySQL **不会自动迁移历史记录**，切换前请自行迁移或保留备份。 - 当前 MySQL 模式适用于单个逻辑 Paper 服务端，不是跨服共享库存方案。 - 末影箱扫描默认关闭；如无明确需求，建议保持 `scan.include-ender-chest: false`。 - 每次更换绑定插件或修改物品格式后，都应使用 `/bounditems inspect` 做一次实物验证。 ## 常见问题 ### 绑定物品没有被识别 执行 `/bounditems inspect`，检查 NBT 路径或 Lore 模板是否与实际物品完全一致，再执行 `/bounditems reload`。 ### 自己的物品被收走 检查物品保存的 UUID 是否属于当前玩家。若仍使用玩家名识别，建议改为 UUID。 ### 玩家看得到物品，但无法领出 让玩家至少腾出一个能够完整容纳该物品的背包位置，再用普通左键领取。 ### 修改 MySQL 配置后没有生效 数据库连接配置只能在服务器完整重启后生效。插件已经内嵌驱动，无须另装数据库插件或添加 JVM 参数。 ### 服务器提示加载了两个 MCBinding 停止服务器，删除 `plugins` 中的旧版 JAR，只保留一个版本后重新启动。 ## 下载与交流 当前版本：**MCBinding 1.5.2** 加入 QQ 群下载并反馈问题：**1090296532** 反馈时建议同时提供： - 服务端核心与具体版本； - Java 版本； - MCBinding 版本； - `/bounditems inspect` 的识别结果； - 经脱敏处理的相关配置与报错日志。 ## 详细文档 飞书wiki: [https://tcns9wenbxfk.feishu.cn/wiki/GeAcwFaz8i1YYRkChJPc3HkXnLb?from=from_copylink](https://tcns9wenbxfk.feishu.cn/wiki/GeAcwFaz8i1YYRkChJPc3HkXnLb?from=from_copylink) --- 如果 MCBinding 帮你减少了误拿装备、跨玩家流转或人工补发的麻烦，欢迎在帖子下留下使用反馈。 [/MD]