智能拾取与背包分發系统 (MC 26.2)
本文件深入解析 Minecraft 26.2 下 Item Clumps 的单批次原生存放、容量模擬、纯原版物品堆建立及零 NBT 污染架構。
📊 特性資訊框
| 属性 | 技术规格 |
|---|---|
| 系统名称 | 智能批量背包分發器 |
| 目標类 | net.minecraft.world.entity.item.ItemEntity |
| 背包上限 | 严格對齊原版規則（普通物品为 $64$，終界珍珠/雞蛋为 $16$） |
| 数据純淨度 | $100%\text{ 纯原版物品堆}$（零自定义 NBT、標籤或組件） |
| 拾取动画 | 原生 player.take(this, added) 實體吸附动画与拾取音效 |
| 統計追蹤 | 触发原版 Stats.ITEM_PICKED_UP.get(item) |
| 部分拾取 | 完整支援（未拾取满的剩余物品留存在地面聚合体中） |
🎒 智能拾取完整生命週期
Item Clumps 的一项核心設計準則是零背包污染。尽管地面上的掉落物實體可容纳 $9,999$ 个物品，但玩家个人背包的堆疊上限絕不被篡改或擴充。
┌──────────────────────────────────────────────┐
│ Player Collides with Ground Clump (e.g. 500x)│
└──────────────────────┬───────────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ Pickup Validity & Target Check │
│ - pickupDelay == 0? │
│ - target == null || target == player? │
└──────────────────────┬───────────────────────┘
│ (Pass)
▼
┌──────────────────────────────────────────────┐
│ Single-Batch Native Inventory Dispatch │
│ player.getInventory().add(stack) │
└──────────────────────┬───────────────────────┘
│
┌─────────────────┴─────────────────┐
│ │
Inventory Has Space Inventory Becomes Full
│ │
▼ ▼
┌─────────────────────────┐ ┌─────────────────────────┐
│ Entire Clump Absorbed │ │ Partial Pickup │
│ - 500 items transferred │ │ - e.g. 192 items added │
│ - Clump entity removed │ │ - 308 items remain in │
│ - Sound & particles play│ │ ground clump entity │
└─────────────────────────┘ └─────────────────────────┘🛡️ 零 NBT 污染保證
地面上的物品会显示自定义名牌（如 Stone x500）以向玩家传达其实际数量。然而当这些物品进入玩家背包时：
- 名牌自動剝離：自定义名牌仅属于
ItemEntity實體本身，絕不附加在底层的ItemStack物品堆上。 - 原版無縫堆疊：由于进入玩家背包的
ItemStack毫无自定义組件附帶，因此可与箱子、界伏盒和原版工作台中的物品無縫自然合併。 - 零殘留幽靈数据：世界存档保持 100% 純淨且绝无損壞風險，即便日后从伺服器中彻底移除本模组也毫不受影響。
💻 真實源码实现参考
源自 Minecraft 26.2 的 ItemEntityMixin.java：
java
@Inject(method = "playerTouch", at = @At("HEAD"), cancellable = true)
private void item_clumps$smartPickup(Player player, CallbackInfo ci) {
if (!DynamicGameRuleManager.getBoolean(this.level(), ItemClumpsFabric.ENABLE_CLUMPING) ||
this.level().isClientSide()) return;
int count = this.getItem().getCount();
if (count <= 1) return; // Allow vanilla to handle normal 1-count items
if (this.pickupDelay == 0 && (this.target == null || this.target.equals(player.getUUID()))) {
ItemStack pickupStack = this.getItem().copy();
int originalCount = count;
// Native batch addition into player inventory
player.getInventory().add(pickupStack);
int added = originalCount - pickupStack.getCount();
if (added > 0) {
player.take(this, added);
player.awardStat(net.minecraft.stats.Stats.ITEM_PICKED_UP.get(pickupStack.getItem()), added);
ItemStack remainingStack = this.getItem().copyWithCount(pickupStack.getCount());
this.setItem(remainingStack);
if (pickupStack.getCount() <= 0) {
player.onItemPickup((ItemEntity) (Object) this);
}
}
ci.cancel(); // Prevent vanilla pickup interference
}
}