Container Fragment
The Container Placement fragment determines where an item is stored in the inventory. It handles the selection of a container and position, and stores the result in a fragment memory.
This fragment is fundamental for any item stored within a container, defining its position inside the inventory. While it is typically present in every item, it remains a separate fragment to allow flexible customization of storage behavior.
It's designed to work in conjunction with container layouts and can define preferred containers using a tag query. If no preferred container is available, the system selects the most appropriate option based on layout, compatibility, and priority.
Fragment Tags
This fragment does not add any traits to the item, but it relies on container tags and layout compatibility to work correctly.
Properties
This fragment has the following property.
Property | Description |
|---|---|
| Gameplay Tag Query used to filter/select preferred containers for this item. |
Operations
This fragment exposes the following operations.
Function | Description |
|---|---|
| Returns the default container for the item based on the fragment memory. |
| Returns the container where the item is currently placed. |
| Returns the position of the item in its current container. |
| Manually sets the item's container and position. |
| Tries to use memory/default/preferred container, or selects one dynamically. |
| Finds the best container for the item using the provided criteria. |
| Returns a valid position for the item in its current container. |
| Returns a valid position for the item in the provided container. |
| Adds an item to a container, in the provided position. |
| Moves an item to a new position. Swap items if needed. |
| Swaps two items in the container. |
Memory
This fragment uses InventoryItemFragmentContainerMemory to store the current container and position.
Event Payload
This fragment emits the following events, using InventoryItemContainerPlacementPayload as the payload structure.
Event | Description |
|---|---|
| The fragment is active and the placement was initialized. |
| The container storing the item has been changed. |
| The position of the item, in the container, has been changed. |
Placement vs. Change events
PlacementInitialized fires once when the fragment creates the initial container/position for the item, whether that comes from a fresh selection or a valid default memory.
ContainerChanged and PositionChanged fire only when the resolved container/position differ from the previous ones. On first initialization, these may also fire if the provided default memory had to be corrected (e.g., invalid container or out-of-range position).
In that case, the payload's PreviousContainer/PreviousPosition reflect the defaults and Container/Position reflect the final placement. If the defaults are already viable, you'll get PlacementInitialized and no change events.