How to transfer items between containers
Transfer best-effort — moves what fits
When you transfer items between containers in best-effort mode, the system moves as many as it can without violating hard constraints. For example, if you have 10 iron ingots in a backpack (which has a soft weight limit of 200.0) and attempt to transfer 8 of them to a chest with a hard weight limit of 50.0, only 5 will actually move — the most the chest can accept. The operation reports that 5 out of 8 requested items were transferred, leaving 5 iron ingots in each container. This lets you fill a container to capacity in a single call without needing to calculate available space yourself.
Transfer exact — succeeds when destination has room
When you transfer items between containers in exact mode, the system moves precisely the quantity you request — as long as the destination has room. For example, if your “backpack” (with unlimited capacity) holds 5 “iron_ingot” and you transfer 3 to a “chest” constrained to a hard weight limit of 100.0, the operation reports 3 transferred out of 3 requested. The backpack is left with 2 iron ingots and the chest now contains 3.
Transfer to a hard container that can’t fit — nothing moves
When you attempt to transfer items into a container with a hard constraint and the transfer would exceed that limit, nothing moves. For example, if you try to transfer 8 iron ingots from a backpack (soft weight limit of 200.0) into a chest with a hard weight limit of 50.0 using exact mode, the operation fails with a capacity exceeded error. The backpack retains all 10 iron ingots and the chest remains empty — hard constraints are strict, so partial transfers don’t happen in exact mode.
Transfer triggers threshold on destination
When you transfer items between containers, the destination container’s thresholds are evaluated against the incoming weight. If you set up a container like “chest” with a soft weight constraint of 50.0 and an “encumbered” threshold at 70%, then transfer 4 “iron_ingot” from your “backpack” to the “chest” in exact mode, all 4 items transfer successfully. The result also reports that the “encumbered” threshold was newly crossed, letting you react to the destination container reaching a significant capacity milestone as a direct consequence of the transfer.
Generated from core/tests/features/transfer.feature