How to use threshold transitions
Multiple thresholds crossed in one operation
When a single operation pushes a container past multiple thresholds at once, the result reports all of them. For example, if your “backpack” has a soft weight constraint of 100.0 with thresholds at 70% (“encumbered”) and 100% (“overloaded”), adding 11 “iron_ingot” items in exact mode will report both “encumbered” and “overloaded” as newly crossed in the same result.
Query slot threshold state for UI display
When you need to drive UI changes based on how full a container is, you can query its slot threshold state. For example, given a container “rack” with a soft slot count of 10 and two thresholds defined — “crowded” at 80% and “full” at 100% — adding 8 tokens and then querying the threshold state returns the current slot count (8), capacity (10), and ratio (0.8). At that point, the “crowded” threshold is exceeded while “full” is not, giving your UI the information it needs to show visual feedback like a color change or warning icon as the container approaches its limit.
Query threshold state for UI display
When you query the weight threshold state of a container, you get back everything needed to drive your UI: the current weight value, the total capacity, and the fill ratio, along with which named thresholds have been exceeded. For example, a “backpack” with a soft weight constraint of 100.0 and thresholds defined at 0.7 (“encumbered”) and 1.0 (“overloaded”) that holds 8 iron ingots will report a current weight of 80.0, a capacity of 100.0, and a ratio of 0.8 — meaning “encumbered” is exceeded but “overloaded” is not. This lets you update indicators like weight bars, warning icons, or movement penalties based on exactly where the container sits relative to each threshold.
Slot threshold cleared on remove
When a container has a threshold defined, removing items can clear a previously active threshold. If you set up a “rack” container with a soft slot count of 10 and a “crowded” threshold at 80% capacity, adding 8 tokens brings you to exactly that 80% mark, triggering the threshold. Removing one token drops the count to 7, which falls below the 0.8 ratio, and the result reports that the “crowded” threshold is cleared. This lets you react to state changes in both directions — knowing when a container becomes crowded and when it stops being crowded.
Slot threshold newly crossed on add
When a container has threshold ratios defined against a slot count constraint, adding items can trigger threshold crossing notifications. If you configure a container “rack” with a soft slot count of 10 and thresholds at 0.8 (“crowded”) and 1.0 (“full”), then add tokens one at a time, the eighth token pushes occupancy to 80% — exactly the “crowded” ratio. The result from that addition reports that the “crowded” threshold was newly crossed, while confirming the “full” threshold has not yet been exceeded. This lets you react to capacity milestones as they happen, such as warning the player that a container is getting full before it actually fills up.
Threshold newly crossed on add
When you configure a container with weight thresholds, the system tracks which thresholds are newly crossed after each operation. 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 contains 6 iron ingots, adding 2 more in exact mode will report that the “encumbered” threshold was newly crossed — meaning it wasn’t exceeded before but now is. At the same time, the result confirms that the “overloaded” threshold has not yet been exceeded. This lets you react precisely to state changes, such as showing a UI warning only at the moment a character becomes encumbered, rather than on every subsequent addition.
Generated from core/tests/features/thresholds.feature