How to use enforcement modes
Containers support hard, soft, and report-only enforcement.
Best-effort add at exact slot capacity reports 0 added
When a container has already reached its hard slot limit, attempting to add more items in best-effort mode gracefully reports the shortfall instead of failing. If you configure a container “rack” with a hard SlotCount(3) constraint and fill it with three weapons, a best-effort attempt to add one more weapon will report 0 added out of 1 requested, and the container remains at 3 items. This lets you attempt bulk additions without risking errors, while still knowing exactly how many items couldn’t fit.
Best-effort add at exact weight capacity reports 0 added
When a container is already at its exact weight limit, a best-effort add correctly reports that nothing was added. If your “chest” has a hard weight constraint of 100.0 and already contains 10 “iron_ingot” totalling that limit, attempting to add 5 more in best-effort mode results in 0 added out of 5 requested, and the chest remains at a total weight of 100.0.
Exact add landing at exact slot capacity succeeds
When a container has a hard SlotCount(3) constraint and already holds 2 items, adding 1 more weapon in exact mode succeeds — the operation reports 1 added out of 1 requested, bringing the container to its full capacity of 3 items. Exact mode requires that the entire requested quantity can be accommodated, and since the third slot is available, the add completes without issue.
Exact add landing at exact weight capacity succeeds
When you add items to a container using exact mode, the operation succeeds as long as the total weight doesn’t exceed the constraint. If you have a “chest” with a hard weight limit of 100.0 and it already contains 9 iron ingots, adding 1 more iron ingot in exact mode succeeds — the operation reports 1 added out of 1 requested, and the chest sits at exactly 100.0 total weight, right at its capacity.
Hard + best-effort — add as many as fit
When a container uses hard enforcement, you can still attempt to add items using best-effort mode, which fits as many items as possible rather than rejecting the entire operation. If you set up a “chest” with a hard weight limit of 100.0 and it already contains 8 iron ingots, attempting to add 5 more in best-effort mode will add only the 2 that fit within the weight budget. The operation reports back that 2 out of 5 requested items were added, and the chest sits exactly at its 100.0 weight limit.
Hard + exact — reject add that would exceed capacity
When a container uses hard enforcement, it strictly prevents any operation that would violate its constraints. If you have a “chest” with a hard weight constraint of 100.0 and it already contains 8 iron ingots (weighing 80.0 total), attempting to add 5 more iron ingots in exact mode will fail with a capacity exceeded error. The chest remains unchanged at 80.0 weight — hard enforcement ensures the invalid addition is fully rejected rather than partially applied.
Hard slot + best-effort — report 0 added when full
When a container has a hard SlotCount constraint, it strictly enforces its capacity limit. If you create a “belt” container with a hard SlotCount of 2 and fill both slots with weapons, any further additions in best-effort mode won’t error out — instead, the operation completes gracefully and reports that 0 items were added out of the 1 requested, letting you handle the overflow in your game logic.
Hard slot + exact — reject when all slots full
When a container uses hard enforcement with a SlotCount constraint, it strictly prevents overfilling. If you create a “belt” container with a hard SlotCount(2) constraint and add two weapons to fill both slots, any further attempt to add another weapon in exact mode will fail with a capacity exceeded error. The belt remains unchanged at 2 items — hard enforcement guarantees the constraint is never violated.
Report-only — always succeeds, reports state
When you configure a container with report-only enforcement, additions always succeed regardless of whether constraints are violated. Instead of blocking the operation, the system tells you which thresholds have been crossed. For example, if you set up an “equipment” container with a report-only Weight constraint of 70.0 and define thresholds at 0.3 (“light_roll”), 0.7 (“medium_roll”), and 1.0 (“heavy_roll”), adding 8 “iron_ingot” items will go through successfully. The result then reports that all three thresholds — “heavy_roll”, “medium_roll”, and “light_roll” — have been exceeded, giving you full visibility into the container’s state without preventing the action.
Report-only slot — always succeeds
When a container uses report-only enforcement, constraint violations are logged but never prevent operations from succeeding. If you configure a “belt” container with a report-only SlotCount(2) constraint and then add four weapons to it, all four additions succeed and the belt contains all four items — even though the slot count of 2 was exceeded after the second weapon. This mode is useful for monitoring how often constraints would be hit without actually blocking gameplay.
Soft + best-effort — same as soft exact
When a container uses soft enforcement with a best-effort add, the behavior is the same as a regular soft add. If your “backpack” has a soft weight constraint of 100.0 and already holds 8 iron ingots, adding 5 more in best-effort mode succeeds fully — the operation reports all 5 added out of 5 requested, bringing the total weight to 130.0. Since soft constraints allow overflow, best-effort mode has no partial-fill behavior to trigger; every requested item is accepted.
Soft + exact — allow add beyond capacity, report thresholds
When a container uses soft enforcement, items are never rejected — but you still get threshold reports so your game can react. If you configure a “backpack” with a soft weight constraint of 100.0 and define thresholds at 0.7 (“encumbered”) and 1.0 (“overloaded”), adding 11 iron ingots that push the total weight to 110.0 will succeed fully. The operation confirms all 5 requested items were added, but the result flags that both the “encumbered” and “overloaded” thresholds have been exceeded. This lets you allow the action while still triggering gameplay consequences like movement penalties or warning UI.
Soft slot + exact — allow beyond slot capacity
When a container uses a soft SlotCount constraint, items can exceed the slot limit rather than being rejected. If your “belt” container has a soft SlotCount(2) constraint and already holds 2 weapons, adding a third weapon in exact mode still succeeds — the operation reports 1 added out of 1 requested, and the belt now contains 3 items. Soft constraints track violations without blocking the operation, letting you decide how to handle over-capacity situations in your game logic.
Generated from core/tests/features/enforcement.feature