巨型堆疊聚合機制 (MC 26.2)
本文件对 Minecraft 26.2 下 Item Clumps 的地面掉落物聚合機制、搜索半径数学、64位算术溢位防護及零堆記憶體分配优化进行詳盡的技术与数学剖析。
📊 特性資訊框
| 属性 | 技术规格 |
|---|---|
| 系统名称 | 地面掉落物巨型堆疊聚合器 |
| 目標类 | net.minecraft.world.entity.item.ItemEntity |
| 默认聚合上限 | 9,999 个物品（最高可設定至 $2,147,483,647$） |
| 搜索半径 ($r$) | 水平 $1\text{ 至 }10\text{ 格}$（默认：$1\text{ 格}$） |
| Tick 额外開銷 | 静止物品为 $0.00\text{ ms}$（仅在 setItem() 时派发） |
| 記憶體分配 | 搜索与吸納阶段零对象分配 (copyWithCount(int)) |
| 控制性游戏規則 | item_clumps:enable_clumping, item_clumps:max_clump_size, item_clumps:merge_radius |
⚙️ 巨型堆疊聚合的工作原理
在原版 Minecraft 中，掉落物在每个 tick 会调用 mergeWithNeighbours() 搜索附近的同类物品。然而原版严格禁止目標實體的物品数量超过 itemStack.getMaxStackSize()（通常为 64，終界珍珠/雞蛋则为 16）。
Item Clumps 通过 ItemEntityMixin.java 拦截此检查，在彻底解除该人为限制的同时，维持严格的数据組件安全性。
┌──────────────────────────────┐
│ ItemEntity A Ticks In │
└──────────────┬───────────────┘
│
▼
┌──────────────────────────────┐
│ Fast-Path Validation │
│ - Matching player target? │
│ - Identical DataComponents? │
└──────────────┬───────────────┘
│ (Pass)
▼
┌──────────────────────────────┐
│ In-Flight Magnet Check │
│ (Is either item magnetized?) │
└──────────────┬───────────────┘
│ (No)
▼
┌──────────────────────────────┐
│ 64-Bit Arithmetic Sum │
│ S = (long) A + (long) B │
└──────────────┬───────────────┘
│
┌───────────────┴───────────────┐
│ │
S <= maxClumpSize S > maxClumpSize
│ │
▼ ▼
┌───────────────────┐ ┌───────────────────┐
│ Complete Merge │ │ Partial Merge │
│ Larger absorbs │ │ Fill entity A to │
│ smaller entity; │ │ maxClumpSize; │
│ Younger age kept. │ │ B keeps remainder.│
└───────────────────┘ └───────────────────┘📐 数学公式与高精度運算
1. 水平碰撞箱外扩膨脹運算
原版仅搜索微小的碰撞箱區域：$\text{AABB}_{\text{vanilla}} = \text{AABB}.\text{inflate}(0.5, 0.0, 0.5)$。
Item Clumps 使用零分配的 @Redirect 注入動態擴充水平碰撞箱：
$$\text{AABB}_{\text{clump}} = \text{boundingBox}.\text{inflate}(r, y, r)$$
其中：
- $r = \text{DynamicGameRuleManager}.\text{getInt}(\text{level}, \text{MERGE_RADIUS}) \in [1, 10]$ 格。
- $y = 0.0$（垂直搜索高度严格保持不变，防止不同樓層或不同漏斗上方的物品发生越层誤聚合）。
2. 64 位整數求和与算术溢位防護
在大服設定下（例如聚合上限设为 20 亿）两个巨大聚合体合併时，标准 32 位 int 加法可能溢位为负数 ($\text{Integer.MAX_VALUE} + 1 = -2,147,483,648$)，导致實體状态損壞。
Item Clumps 采用 64 位長整數高精度计算和：
$$S = (\text{long}),\text{thisCount} + (\text{long}),\text{otherCount}$$
- 完全吸收 ($S \le \text{maxClumpSize}$)： $$\text{count}_{\text{merged}} = (\text{int}),S$$
- 部分吸收 ($S > \text{maxClumpSize}$)： $$\Delta = \text{maxClumpSize} - \text{thisCount}$$ $$\text{thisCount}' = \text{maxClumpSize}, \quad \text{otherCount}' = \text{otherCount} - \Delta$$
3. 組件与状态严格匹配一致性
除非所有数据組件（附魔、耐久损耗、自定义名称、盔甲纹饰、药水效果）100% 位元級完全一致，否则物品絕不聚合：
$$\text{ItemStack}.\text{isSameItemSameComponents}(\text{stack}_A, \text{stack}_B) == \text{true}$$
💻 真實源码实现参考
源自 Minecraft 26.2 的 ItemEntityMixin.java：
java
@Inject(method = "tryToMerge", at = @At("HEAD"), cancellable = true)
private void item_clumps$customMerge(ItemEntity other, CallbackInfo ci) {
ItemStack thisStack = this.getItem();
ItemStack otherStack = other.getItem();
// Fast-path exit before GameRule lookups
if (!Objects.equals(this.target, ((ItemEntityMixin)(Object)other).target) ||
!ItemStack.isSameItemSameComponents(thisStack, otherStack)) {
return;
}
if (!DynamicGameRuleManager.getBoolean(this.level(), ItemClumpsFabric.ENABLE_CLUMPING)) return;
// Magnet mod in-flight protection
if (net.fabricmc.loader.api.FabricLoader.getInstance().isModLoaded("magnet")) {
try {
java.lang.reflect.Method isMagnetizedMethod;
try {
isMagnetizedMethod = this.getClass().getMethod("ig_magnet$isMagnetized");
} catch (NoSuchMethodException e) {
isMagnetizedMethod = this.getClass().getMethod("ig$isMagnetized");
}
if ((boolean) isMagnetizedMethod.invoke(this) || (boolean) isMagnetizedMethod.invoke(other)) {
ci.cancel();
return;
}
} catch (Throwable ignored) {}
}
int thisCount = thisStack.getCount();
int otherCount = otherStack.getCount();
int maxClump = (ItemClumpsFabric.MAX_CLUMP_SIZE == null)
? thisStack.getMaxStackSize()
: DynamicGameRuleManager.getInt(this.level(), ItemClumpsFabric.MAX_CLUMP_SIZE);
long sum = (long) thisCount + (long) otherCount;
if (sum > (long) maxClump) {
int spaceLeft = maxClump - thisCount;
if (spaceLeft > 0) {
ItemStack thisCopy = thisStack.copyWithCount(maxClump);
this.setItem(thisCopy);
ItemStack otherCopy = otherStack.copyWithCount(otherCount - spaceLeft);
other.setItem(otherCopy);
this.pickupDelay = Math.max(this.pickupDelay, ((ItemEntityMixin)(Object)other).pickupDelay);
this.age = Math.min(this.age, ((ItemEntityMixin)(Object)other).age);
}
ci.cancel();
return;
}
// Full Merge: larger stack absorbs the smaller stack
if (otherCount < thisCount) {
ItemStack thisCopy = thisStack.copyWithCount((int) sum);
this.setItem(thisCopy);
this.pickupDelay = Math.max(this.pickupDelay, ((ItemEntityMixin)(Object)other).pickupDelay);
this.age = Math.min(this.age, ((ItemEntityMixin)(Object)other).age);
other.discard();
} else {
ItemStack otherCopy = otherStack.copyWithCount((int) sum);
other.setItem(otherCopy);
((ItemEntityMixin)(Object)other).pickupDelay = Math.max(((ItemEntityMixin)(Object)other).pickupDelay, this.pickupDelay);
((ItemEntityMixin)(Object)other).age = Math.min(((ItemEntityMixin)(Object)other).age, this.age);
this.discard();
}
ci.cancel();
}