Механика объединения в мега-стаки (MC 26.2)
Этот документ содержит подробный технический и математический разбор объединения предметов, расчета радиуса поиска, защиты от 64-битного переполнения и оптимизации выделения памяти в куче для Minecraft 26.2.
📊 Информационный блок функции
| Свойство | Спецификация |
|---|---|
| Имя системы | Агрегатор мега-стаков предметов на земле |
| Целевой класс | net.minecraft.world.entity.item.ItemEntity |
| Лимит по умолчанию | 9 999 предметов (настраивается до $2,147,483,647$) |
| Радиус поиска ($r$) | По горизонтали $1\text{–}10\text{ блоков}$ (по умолч.: $1\text{ блок}$) |
| Нагрузка за тик | $0.00\text{ мс}$ на неподвижных предметах (вызов только при setItem()) |
| Выделение памяти | Ноль аллокаций объектов при поиске и слиянии (copyWithCount(int)) |
| Управляющие GameRules | item_clumps:enable_clumping, item_clumps:max_clump_size, item_clumps:merge_radius |
⚙️ Как работает объединение в мега-стаки
В ванильном Minecraft выброшенные предметы в своем тике вызывают метод 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. Расширение горизонтального хитбокса (Bounding Box)
Ванильный поиск охватывает лишь крошечную область: $\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-битное сложение и защита от арифметического переполнения
При слиянии гигантских скоплений на серверах (например, с лимитом в 2 миллиарда) стандартное 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}$$
💻 Исходный код реализации на Java
Из ItemEntityMixin.java в Minecraft 26.2:
@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();
}