Core concepts

Definition versus instance

An item definition (URicItemDefinition) is shared configuration: name, shape, icon, initial stats, and optional nested-container definitions.

An item instance (URicItemInstance) is runtime state: GUID, definition reference, stack statistics, owning container, and nested containers. Two stacks may reference the same definition but have different GUIDs and state.

A container definition selects a container implementation and tag. A container instance holds the actual items and occupied slots.

Fragments

Definitions compose behavior from instanced UObject fragments. Item fragments have native and Blueprint initialization hooks. Container fragments also initialize their runtime container.

Configuration fragments belong to the definition. Do not store per-item mutable state on shared definition objects; use the item instance, tags, or your own runtime state.

Ownership hierarchy

Replicated inventory owner actor
  └─ Container manager
      └─ Top-level container
          └─ Backpack item instance
              └─ Nested container
                  └─ Item instance

The manager owns the roots. Items can own containers, and those containers can hold more items. Use recursive queries when you need to include nested content.

Identity

• Managers use an FName ID, including for save restoration.
• Items and containers use FGuid IDs.
• Quick slots store item assignments and save them by GUID.

Keep GUIDs as references across client resynchronization. A predicted or transferred item can be represented by a different UObject pointer later.

Authority and presentation

Authoritative managers hold the inventory state replicated by the server. The predicted component provides a local view of owned and observed inventories, applies supported local operations, and reconciles with replicated state.

A widget should follow the appropriate source for its role. Read Networking and prediction before mixing authoritative and predicted references.