巨型堆疊聚合機制 (MC 26.1.2)
本文件对 Minecraft 26.1.2 下 Item Clumps 的地面掉落物聚合、搜索半径数学计算与實體合併機制进行技术剖析与数学推导。
📊 特性資訊框
| 属性 | 技术规格 |
|---|---|
| 系统名称 | 地面掉落物巨型堆疊聚合器 |
| 目標类 | net.minecraft.world.entity.item.ItemEntity |
| 默认聚合上限 | 9,999 个物品（最高可設定至 $2,147,483,647$） |
| 搜索半径 ($r$) | 水平 $1\text{ 至 }10\text{ 格}$（默认：$1\text{ 格}$） |
| 半径注入点 | AABB.inflate(DDD) 上的 @ModifyArgs |
| 控制性游戏規則 | item_clumps:enable_clumping, item_clumps:max_clump_size, item_clumps:merge_radius |
⚙️ 巨型堆疊聚合的工作原理
在原版 Minecraft 中，掉落物在每个 tick 会调用 mergeWithNeighbours() 搜索附近的同类物品。然而原版严格禁止目標實體的物品数量超过 itemStack.getMaxStackSize()（通常为 64）。
Item Clumps 通过 ItemEntityMixin.java 拦截此检查，解除限制的同时維護严格的数据組件安全性。
┌──────────────────────────────┐
│ ItemEntity A Ticks In │
└──────────────┬───────────────┘
│
▼
┌──────────────────────────────┐
│ Feasibility Check │
│ - Matching player target? │
│ - Identical DataComponents? │
└──────────────┬───────────────┘
│ (Pass)
▼
┌──────────────────────────────┐
│ Combine Stacks Math Check │
└──────────────┬───────────────┘
│
┌───────────────┴───────────────┐
│ │
thisCount + otherCount <= maxClump thisCount + otherCount > maxClump
│ │
▼ ▼
┌───────────────────┐ ┌───────────────────┐
│ Complete Merge │ │ Partial Merge │
│ Larger absorbs │ │ Fill entity A to │
│ smaller entity; │ │ maxClumpSize; │
│ Younger age kept. │ │ B keeps remainder.│
└───────────────────┘ └───────────────────┘📐 数学公式与高精度運算
1. 水平碰撞箱膨脹计算 (@ModifyArgs)
$$\text{args.set}(0, r), \quad \text{args.set}(2, r)$$
其中：
- $r = \text{DynamicGameRuleManager}.\text{getInt}(\text{level}, \text{MERGE_RADIUS}) \in [1, 10]$ 格。
- 垂直高度索引 ($1$) 保持不变，严格保持不同樓層高度之间的垂直隔離。
2. 物品数量转移数学演算法
- 完全吸收 ($S \le \text{maxClumpSize}$)： $$\text{count}_{\text{merged}} = \text{thisCount} + \text{otherCount}$$
- 部分吸收 ($S > \text{maxClumpSize}$)： $$\Delta = \text{maxClumpSize} - \text{thisCount}$$ $$\text{thisCount}' = \text{maxClumpSize}, \quad \text{otherCount}' = \text{otherCount} - \Delta$$
💻 真實源码实现参考
源自 Minecraft 26.1.2 的 ItemEntityMixin.java：
java
@ModifyArgs(method = "mergeWithNeighbours", at = @At(value = "INVOKE", target = "Lnet/minecraft/world/phys/AABB;inflate(DDD)Lnet/minecraft/world/phys/AABB;"))
private void item_clumps$modifySearchRadius(Args args) {
if (DynamicGameRuleManager.getBoolean(this.level(), ItemClumpsFabric.ENABLE_CLUMPING)) {
double radius = DynamicGameRuleManager.getInt(this.level(), ItemClumpsFabric.MERGE_RADIUS);
args.set(0, radius);
args.set(2, radius);
}
}
@Inject(method = "tryToMerge", at = @At("HEAD"), cancellable = true)
private void item_clumps$customMerge(ItemEntity other, CallbackInfo ci) {
if (!DynamicGameRuleManager.getBoolean(this.level(), ItemClumpsFabric.ENABLE_CLUMPING)) return;
ItemStack thisStack = this.getItem();
ItemStack otherStack = other.getItem();
if (!Objects.equals(this.target, ((ItemEntityMixin)(Object)other).target) ||
!ItemStack.isSameItemSameComponents(thisStack, otherStack)) {
return;
}
int thisCount = thisStack.getCount();
int otherCount = otherStack.getCount();
int maxClump = DynamicGameRuleManager.getInt(this.level(), ItemClumpsFabric.MAX_CLUMP_SIZE);
if (thisCount + otherCount > maxClump) {
int spaceLeft = maxClump - thisCount;
if (spaceLeft > 0) {
thisStack.setCount(maxClump);
this.setItem(thisStack);
otherStack.setCount(otherCount - spaceLeft);
other.setItem(otherStack);
}
ci.cancel();
return;
}
// Full Merge: larger stack absorbs the smaller stack
if (otherCount < thisCount) {
thisStack.setCount(thisCount + otherCount);
this.setItem(thisStack);
this.pickupDelay = Math.max(this.pickupDelay, ((ItemEntityMixin)(Object)other).pickupDelay);
this.age = Math.min(this.age, ((ItemEntityMixin)(Object)other).age);
other.discard();
} else {
otherStack.setCount(thisCount + otherCount);
other.setItem(otherStack);
((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();
}