How to change capacity at runtime

Decreasing capacity triggers a threshold

When you reduce a container’s capacity at runtime, existing items may suddenly push past thresholds that weren’t previously exceeded. For example, if your “backpack” has a soft weight constraint of 100.0 with thresholds at 0.7 (“encumbered”) and 1.0 (“overloaded”), and it already holds 6 iron ingots, dropping the capacity to 50.0 causes both thresholds to be exceeded immediately. The capacity change result tells you exactly which thresholds were newly crossed, so you can react accordingly — such as slowing the player or blocking further pickups.

Increasing capacity clears a threshold

When you increase a container’s capacity at runtime, any thresholds that were previously exceeded are automatically re-evaluated. For example, if your “backpack” has a soft weight constraint of 100.0 with an “encumbered” threshold at 70% and contains 8 iron ingots pushing it past that threshold, raising the weight capacity to 150.0 drops the fill ratio below 0.7 — clearing the “encumbered” state. The capacity change result will report that the “encumbered” threshold was newly cleared, so you can react accordingly (e.g., restoring the player’s movement speed).

Reducing slot capacity displaces excess stacks

When you reduce a container’s slot capacity at runtime, any items that no longer fit are displaced rather than silently destroyed. For example, if your “belt” container holds 3 coins across 5 slots and you shrink its capacity to 2, the system reports 1 displaced item — a single coin — and the belt retains only 2 items. This lets you safely resize containers (e.g., when a buff expires or equipment changes) while giving you full control over what happens to the overflow.

Generated from core/tests/features/dynamic_capacity.feature