How to use weight constraints

Containers with Weight constraint limit total weight of contained items. Items must have a “weight” field.

Add items within weight limit

When you configure a container with a hard Weight constraint — for example, a “pouch” with a maximum weight of 25.0 — the system enforces that limit as items are added. If you attempt to add 2 “heavy_item” entries to the pouch but their combined weight would exceed the capacity, only 1 item is actually stored. The hard constraint silently prevents the second item from being added rather than allowing the container to exceed its weight limit.

Item type missing weight field

If you try to add an item to a weight-constrained container but the item’s type doesn’t have a “weight” field, the operation will fail with a missing field error. For example, a “weightless” type that only defines a “name” field cannot be placed into a “pouch” with a hard Weight(100.0) constraint, because the system has no way to calculate how much weight the item would contribute.

Query current total weight

You can query the current total weight of a container at any time. If you create a container “pouch” with a hard weight capacity of 100.0 and add 2 “heavy_item” entries to it, you can check that the pouch reports a total weight of 20.0, reflecting the combined weight of its contents.

Reject item that exceeds weight limit

When your container enforces a hard weight capacity, adding items that would exceed the limit is rejected. If you configure a “pouch” with a hard Weight constraint of 15.0 and it already contains one “heavy_item,” attempting to add a second “heavy_item” will fail with a capacity exceeded error. This prevents containers from ever holding more weight than their defined maximum.

Generated from core/tests/features/weight_capacity.feature