How to split and merge stacks
Best-effort merge — merge up to max stack, leave remainder
When you merge two stacks in best-effort mode, the system combines as many items as possible into one stack without exceeding its maximum size, and any excess remains in the original stack. For example, if your “quiver” container holds a stack of 20 arrows and a stack of 15 arrows, a best-effort merge will fill one stack to its max and report that 5 items were merged, leaving 15 remaining in the other stack.
Exact merge — reject if combined exceeds max stack
When you attempt an exact merge of two stacks in a container, the operation enforces the item’s maximum stack size. If you have a “quiver” containing one stack of 20 arrows and another of 15 arrows, trying to merge them in exact mode will fail with a max stack exceeded error, since the combined 35 arrows would surpass the allowed limit. Exact mode is strict — it either merges the full quantities or rejects the operation entirely.
Merge clears a slot threshold
When you merge stacks, Sidequest Hero tracks whether the merge causes the container to cross any configured thresholds. For example, if your “pouch” container has a soft slot count limit of 5 and a “crowded” threshold at 75% capacity, splitting a stack of 20 gems repeatedly can push you over that threshold by creating 4 occupied slots. Merging two of those gem stacks back together reduces the container to 3 items, dropping below the 75% mark — and the merge result explicitly reports that the “crowded” threshold was newly cleared. This lets you react to capacity changes in your UI or game logic whenever a merge frees up enough space to cross a threshold boundary.
Split a stack
When you split a stack, the operation creates a new stack with the requested quantity while reducing the original. For example, if you add 10 “arrow” to a “quiver” with unlimited capacity and then split 4 from that stack, the result reports an original stack of 6 and a new stack of 4. The total quantity of “arrow” in the quiver remains 10, but the container now holds 2 separate item stacks.
Split in a full slot container — hard enforcement rejects
When you try to split a stack inside a container that’s already full, the operation is rejected if the container uses hard enforcement. For example, a “quiver” with a hard SlotCount(2) constraint that already holds 10 “arrow” in one slot and 1 “iron_sword” in another has no room for the new stack that a split would create. Attempting to split 4 from the “arrow” stack fails with a capacity exceeded error, because the split would require a third slot that the constraint doesn’t allow.
Split in a full slot container — soft enforcement allows
When a container uses a soft slot constraint, splitting is still allowed even if the container is already at capacity. If your “quiver” has a soft SlotCount(2) constraint and already holds a stack of 10 “arrow” and 1 “iron_sword” (filling both slots), splitting 4 from the “arrow” stack succeeds — the quiver now contains 3 items (two arrow stacks and the sword), and the total arrow quantity remains 10. Soft constraints permit temporary violations, so the extra slot created by the split is not blocked.
Split triggers a slot threshold
When you split a stack inside a container that has capacity thresholds, the split result tells you if any threshold was newly crossed. For example, if your “pouch” container has a soft slot count of 5 and a “crowded” threshold at 80%, and it currently holds three full stacks of 10 gems each (occupying 3 of 5 slots), splitting 5 gems off one of those stacks creates a fourth stack — pushing occupancy to 4 out of 5 slots. The split result reports that the “crowded” threshold was newly crossed, letting you react accordingly (e.g., warning the player their pouch is getting full).
Generated from core/tests/features/split_merge.feature