Smart Item Sort - 智能物品整理

帮助玩家终结“箱子怪物”，降低服务器卡顿！

本插件灵感来源于 Joseph Huckaby 为原版服务器设计的巧妙“魔法分类系统”数据包。本插件扩展了这一概念，使其运行更高效，并能更好地处理带有 NBT 数据的物品。

其核心机制是自动将特定位置的物品传送至理想的“目标”位置。目标由包含相似物品的水平物品展示框标识（后文称为传送目标）。插件提供两种启动传送的方式：一是定义一组方块作为掉落物品的传送垫，任何掉落在传送垫上方不足一格的物品，都会被传送至附近包含相同或相似物品的物品展示框处；二是通过在发射器上放置一个装有末影珍珠的物品展示框来创建“智能物品分类器”方块，放入其中的任何物品堆栈都会像前述传送垫一样，被自动传送至附近的物品展示框。智能物品分类器无需红石脉冲，它会持续自动传送物品直至清空。与传送垫不同，智能物品分类器还能自动卸载放入其中的潜影盒，先传送盒内物品，再传送潜影盒本身。

💡为什么选择这个插件？

• 低开销：许多农场使用复杂的漏斗或发射器链来将物品从生产点运输到存储区并进行分类。这些管道和分类器在拥有众多农场的服务器上可能造成显著卡顿。本插件旨在提供一种更高效（且便捷）的物品运输方式。开发过程中已投入大量精力来降低插件的开销，包括直接处理时间和可能导致更大垃圾回收压力的内存占用。
• 降低卡顿：通过减少掉落物品的停留时间，并允许物品被传送至装有堆肥桶的漏斗，可以降低大型农场和大型分类器造成的卡顿。
• 简化大规模分类系统：大规模物品分类对大多数玩家而言极具挑战性，即使是经验丰富的玩家也常感棘手。本插件能让分类系统对大多数玩家来说更易上手、更可靠，同时也不妨碍有经验的玩家继续尝试“原版”解决方案。
• 分类不可堆叠物品：虽然有许多巧妙的原版分类系统，但通过红石机制分类不可堆叠物品仍然非常困难且不完善。本插件的传送机制可以轻松区分不可堆叠物品，用于创建此类物品的分类器。

🎮核心功能

传送垫

• 任何掉落在传送垫上方不足一格的物品，都会被自动传送至附近匹配的物品展示框目标处。
• 提供了一种被动、自动化的物品收集与分类方式。

智能物品分类器

• 由“发射器 + 装有末影珍珠的物品展示框”构成。
• 放入其中的物品堆栈会被持续自动传送，无需外部红石时钟。
• 独特功能：可自动卸载放入其中的潜影盒，先传送盒内物品，最后传送空潜影盒本身。
• 非常适合作为集中处理点或手动分类站。

🔧工作机制

目标识别

• 传送目标由水平放置的物品展示框定义，框内放置你希望收集的物品样本。
• 当有物品需要传送时，插件会在一定范围内搜索匹配的物品展示框目标。

物品匹配规则

• 插件会智能匹配物品，不仅限于完全相同的物品，也能处理“相似”物品（例如，考虑NBT数据）。
• 这使得分类系统对带有附魔、耐久度等数据的物品同样有效。

✨开始使用

基本设置步骤

• 建立目标：在你希望物品最终抵达的存储位置附近，水平放置物品展示框，并在框内放入目标物品。
• 创建输入端：

- **方式一（传送垫）**：在物品掉落区域（如农场收集点）下方放置你定义的传送垫方块。

- **方式二（分类器）**：在任意位置放置一个发射器，在其侧面水平放置一个物品展示框，框内放入一个末影珍珠。

• 投入物品：将物品丢到传送垫上，或放入智能物品分类器（发射器）中。
• 观察传送：物品将被自动传送到对应的物品展示框目标附近。

注意事项

• 确保物品展示框是水平放置的。
• 传送范围可在插件配置中调整。
• 合理规划目标展示框的密度和位置，以提高匹配效率。

❓更多信息

如需完整的配置选项、权限设置、命令详解及高级用法，请查阅完整文档。

阅读完整文档请点击：此处 (请将此处替换为实际文档链接)

SmartItemSort 是一款强大的物品分类与传送插件，它允许玩家通过简单的方块组合和物品匹配机制，自动将物品从收集点（如刷怪塔）传送至指定的分类或处理位置，从而构建高效、整洁的自动化农场系统。

💡创建传送目标

传送目标由朝上放置的物品展示框（即水平放置，面朝上）构成。将代表目标物品类型的物品放入展示框即可。垂直放置的展示框将被忽略。

目标放置示例

• 最常见用法：将展示框放在漏斗上方。传送来的物品会被漏斗接住并正常输送。
• 销毁物品：将展示框放在装有熔岩的炼药锅上方。物品会掉入熔岩被快速销毁，适合处理农场产出的垃圾。
• 物品堆叠：将展示框放在蜘蛛网上方。单个物品有机会在蜘蛛网内合并成堆后再落下，便于后续处理。

匹配规则

插件按以下优先级寻找匹配的传送目标

精确匹配

传送的物品与展示框内的物品完全一致（包括类型、数据值等）。

物品标签匹配

利用 Minecraft 的“物品标签”系统。将一个命名牌在铁砧上重命名为某个标签名（例如 #candles），然后放入展示框。任何带有该标签的物品（如所有颜色的蜡烛）都会被传送到此目标。

• 支持的标签详见 Spigot API 标签文档。
• 可通过数据包创建自定义标签，并使用其完整名称（如 #b2c:potions）进行引用。

相似匹配

针对带有 NBT 数据的物品（如附魔书、装备）。如果找不到精确匹配的目标，插件会二次搜索展示框内含有同种基础物品（无任何 NBT）的目标。

• 例如，展示框里放着一个无附魔、无损耗的钻石胸甲，那么任何钻石胸甲（无论附魔或损耗）都会传送到此。

捆绑匹配

若想将多种物品传送到同一地点，可以将这些物品样本放入潜影盒，再将潜影盒放入展示框。传送的物品只要匹配潜影盒内任意一种物品，就会被送到此目标。服务器若支持，收纳袋也可实现类似功能。

默认（无匹配）目标

如果找不到任何匹配目标，插件会寻找内含胡萝卜钓竿（可在配置中更改）的展示框作为默认目标。若连默认目标也没有，物品将不会被传送。

匹配优先级顺序

当存在多个可能目标时，插件按以下优先级（数字越小优先级越高）选择最佳匹配：

• 与展示框内物品精确匹配。
• 与展示框内潜影盒中任意物品精确匹配。
• 与展示框内命名牌的物品标签匹配。
• 与展示框内潜影盒中命名牌的物品标签匹配。
• 与展示框内物品相似匹配。
• 与展示框内潜影盒中任意物品相似匹配。
• 展示框内含默认物品（通常是胡萝卜钓竿）。

注意：只有优先级最高（数字最小）的那一类目标会被纳入考虑范围。

选择具体目标

在确定了匹配等级后

• 如果该等级下只有一个目标，则使用它。
• 如果该等级下有多个目标，则会随机选择其中一个。这有助于高产量农场将物品均匀分配到大量漏斗中。

传送执行流程

插件对每个物品堆尝试传送三次

• 第一次尝试：仅寻找下方是容器方块（漏斗、箱子、潜影盒等）的目标。尝试将物品放入这些容器，直到物品放完或所有容器满为止。
• 第二次尝试：如果物品仍有剩余，则寻找下方是普通方块（如蜘蛛网、非熔岩炼药锅）的目标，并将剩余物品随机传送到其中一个目标。
• 第三次尝试：如果前两次都未找到合适目标，但找到了熔岩炼药锅目标，则将剩余物品全部丢入熔岩销毁。

💡创建传送垫

传送垫是位于刷怪处（击杀层）的一种结构，用于自动拾取并传送掉落的物品。它由特定方块的垂直堆叠构成（定义于插件配置中）。

默认传送垫类型

• 哭泣的黑曜石 + 镶金黑石：将镶金黑石放在底层，哭泣的黑曜石放在其上。掉落在哭泣的黑曜石上方一格空间内的物品会被传送。
• 岩浆块 + 哭泣的黑曜石 + 镶金黑石：在第一种结构顶部再加一个岩浆块。

设计用意：哭泣的黑曜石生存获取略有难度，且抗爆炸、耐剑/斧反复劈砍，适合作为击杀层表面。带岩浆块的全自动击杀层效果更佳。

💡创建智能物品分类器

智能物品分类器由发射器构成。

• 在发射器上放置一个物品展示框。
• 在展示框内放入一个末影之眼（可在配置中更改）。
• 此后，分类器会每秒自动从其库存中传送一个物品堆，无需任何外部红石信号。

此方块使得构建大规模物品分类器变得非常简单。

❓物品去哪了？（故障排查）

有时物品可能被传送到意想不到的地方（例如其他玩家的建筑区）。可按以下步骤诊断：

诊断方法

手持一根木棍（默认工具，可在配置中更改）在主手，另一待查物品在副手。用木棍右键点击：

• 智能物品分类器，或
• 传送垫的顶层方块。

插件会在聊天栏告知你，副手物品将会被传送至的坐标。

解决方案

• 调整你的分类器、传送垫或目标的位置，避免与其他玩家的系统冲突。
• 在服务器配置文件 config.yml 中调整搜索目标的最大范围（默认128格）。
• 若服务器使用领地管理插件（如 GriefPrevention、WorldGuard），可使用对应的配套插件进行集成，确保物品只在同一领地内传送。

🎮配置 (config.yml)

插件启动时，会在配置目录 SmartItemSort 中创建 config.yml（如果不存在）。插件不会修改已存在的 config.yml，以防管理员添加的注释丢失。

每次启动时，插件都会生成/覆盖 config.example.yml 文件。切勿修改此文件，它仅用作当前版本支持的所有配置项及其默认值的文档。

✨插件集成

本插件可与其他插件集成，特别是领地管理插件，以确保物品只在同一领地或权限区域内传送。

已知集成

• SmartItemSort-GriefPrevention：强制遵循 GriefPrevention 的领地规则。
• SmartItemSort-WorldGuard：强制遵循 WorldGuard 的区域规则。

集成开发

插件作者愿意为流行的领地管理插件添加集成。即使作者不开发，也可参考公开的示例代码（如 SmartItemSort-GriefPrevention）自行集成。

✨通过权限控制使用

插件本身不通过权限节点强力控制智能分类器的使用。若需严格控制，可在配置中将其激活物品（末影之眼）改为一种不可合成、难以获取的自定义物品。然后，服务器管理员可通过其他方式控制该自定义物品的发放。

配置自定义激活物品

在 config.yml 中，可以设置 activationItem 为一个序列化的 ItemStack 数据。以下是一个示例，它要求使用一个带有特定描述和插件专用 NBT 数据的末影之眼：

activationItem:
  ==: org.bukkit.inventory.ItemStack
  v: 2730
  type: ENDER_EYE
  meta:
    ==: ItemMeta
    meta-type: UNSPECIFIC
    display-name: '"smart item sort activator"'
    lore:
    - '{"text":"activates one smart item sorter","color":"yellow","italic":false}'
    PublicBukkitValues:
      smartitemsort:valid: 1i

注意：上述示例基于 Spigot 1.17 生成，序列化格式可能随服务端版本变化。

推荐配置流程

• 在游戏中，使用其他插件或铁砧准备好你想要的物品（名称、描述）。
• 手持该物品，执行 /smartitemsort item mark 命令，为其添加插件专用 NBT。
• 执行 /smartitemsort item show 命令，在聊天栏获取该物品的序列化数据。
• 复制此数据到 config.yml 的 activationItem 项下。
• 重载插件配置。

此后，只有通过 /smartitemsort item give 命令（受权限控制）获得的特定物品才能激活智能分类器。

🔧命令与权限

所有命令均为 /smartitemsort 的子命令。

基础命令

• /smartitemsort

- 权限：`smartitemsort.commands.use`

- 说明：无参数时无效果，但拥有此权限是使用所有子命令的前提。

物品管理命令

• /smartitemsort item give

- 权限：`smartitemsort.command.item-give`

- 说明：给予玩家一个配置文件中定义的激活物品。

• /smartitemsort item mark

- 权限：`smartitemsort.command.item-mark`

- 说明：为手中物品添加 SmartItemSort 专用元数据，使其成为唯一物品。

• /smartitemsort item show

- 权限：`smartitemsort.command.item-show`

- 说明：显示手中物品的序列化形式，用于配置 `activationItem`。

管理与查询命令

• /smartitemsort reload

- 权限：`smartitemsort.command.reload`

- 说明：重载插件配置并重新搜索所有活动的智能物品分类器。

• /smartitemsort show [玩家名]...

- 权限：`smartitemsort.command.show`

- 说明：显示所有（或指定玩家的）已加载区块内的活动智能物品分类器。

• /smartitemsort tag [标签名]

- 权限：`smartitemsort.command.tag`

- 说明：显示指定标签名所选中的所有方块或物品。

• /smartitemsort tags

- 权限：`smartitemsort.command.tags`

- 说明：显示插件支持的、可用于命名牌机制的所有标签名称。