Concept: Entries, Instances and Definitions
Three objects describe one thing in an inventory, each with a different lifetime.
| Layer | Type | Lifetime | Holds |
|---|---|---|---|
| Definition | UCrimsonInventoryItemDefinition (a Blueprint class) | Asset | DisplayName, ItemType, Fragments (shared static data), StateFragments (templates for per-instance state). |
| Instance | UCrimsonInventoryItemInstance | While the item exists anywhere - inventory, pickup, in transit | ItemDef, StatTags / FloatStatTags (replicated tag stacks), live StateFragments (replicated subobjects). |
| Entry | FCrimsonInventoryEntry | While the instance sits in this inventory | EntryId, Instance, StackCount, SlotIndex, GridPosition, Rotation, LayoutGroupId, LockFlags. |
Why entries have ids
Array indices shift when entries are removed or sorted and replicate out of order. EntryId is a server-assigned int64 that never changes for the life of the entry, so UI, RPCs, and messages address entries by id and survive any reorder. Every routed request takes an EntryId; every StackChanged message carries one.
Stacking and splitting
UCrimsonInventoryItemFragment_Data decides whether instances of a definition may share an entry (bStackable, MaxStackSize) or must be unique (bUnique). Placement policies (ECrimsonPlacementPolicy: MergeFirst, FirstFree, LastFree, MergeOnly, ExplicitTarget) choose whether an add tops up an existing entry before taking a new slot. SplitStackByEntry and MergeStacksByEntry move counts between entries; the item instance is cloned for a split so both halves keep their state.
Lock flags
LockFlags is a bit mask of ECrimsonInventoryLockFlags. User is the player's own lock: sort, quick-merge, and definition-based consume skip it. Equipped is mirrored from the equipment host and additionally blocks drop, consume, transfer, and split. FCrimsonInventoryEntryView exposes both as bLocked and bEquipped.
Fragments vs state fragments
A fragment is read-only data on the definition's CDO - every instance of ID_Sword shares one Visuals fragment. A state fragment is instantiated per item instance, replicated as a subobject, and serialized per entry. If a value differs between two swords, it belongs in a state fragment (or in StatTags).
Views
GetEntryViews, GetCapacityViews, and GetCurrencyViews return flat, Blueprint-friendly snapshots (FCrimsonInventoryEntryView, FCrimsonInventoryCapacityView, FCrimsonInventoryCurrencyView) built from replicated state. UI reads views; it never touches FCrimsonInventoryList directly.