Item Instance

Introduction

The ItemInstance class is the core of the Generic Inventory System (GIS). Item instances reside within item stacks and are created when adding item definitions to collections.

Each ItemInstance is a lightweight UObject that references static data (via item definitions) and manages runtime data.

Key Fields

• ID: A globally unique identifier (FGuid) generated when the item is created.
• Definition: The item definition referenced by the instance, providing access to all static data.
• IntegerAttributes: A Tag->int32 array for dynamically setting/retrieving integer data.
• FloatAttributes: A Tag->float array for dynamically setting/retrieving floating-point data.
• FragmentStates: An array of polymorphic InstancedStruct objects, allowing dynamic runtime data to be attached to static ItemFragment components.

Attribute Management

In addition to static attributes defined in the item definition, you can manage dynamic attributes via IntegerAttributes and FloatAttributes on the item instance. For technical details on the dynamic attribute system, refer to: Dynamic Attribute System.

Adding Dynamic Attributes to Item Definitions

To enable dynamic attributes, add the "Dynamic Attribute Settings" fragment to the item definition. Attributes specified here are added to the instance’s state upon creation and can serve as default values.

When holding an ItemInstance reference, you can also directly set attributes of the corresponding type via API.

State Management

Beyond adding static data through item fragments, you can optionally attach dynamic runtime data to fragments. More details about dynamic state management, see: Data Mixin System。

When to Use

• When the dynamic attribute system feels too flexible, and you prefer to avoid managing numerous tags.
• When simple int or float attributes don’t meet your needs.

Use Case

• Enhanceable Settings: An item fragment defining static settings for equipment enhancement, such as maximum enhancement levels or required materials.
• Enhanceable State: A struct storing the fragment’s runtime state, tracking data like the number of enhancements applied or which attributes were upgraded.

In essence, fragments represent static data, while fragment states represent dynamic data.

Attaching Runtime State to Item Fragments

To add runtime state to item fragments, override the following functions for each fragment type:

1	/**
2	 * Returns the struct type for runtime data serialization or replication.
3	 * 返回运行时数据序列化或复制的结构类型。
4	 * @return The compatible runtime data struct type. 兼容的运行时数据结构类型。
5	 */
6	UFUNCTION(BlueprintNativeEvent, BlueprintPure, Category="ItemFragment")
7	const UScriptStruct* GetCompatibleStateType() const;
8
9	/**
10	 * Provide default values for fragment's runtime data type.
11	 * 针对运行时数据类型提供默认值。
12	 * @param DefaultState The default data. 默认数据
13	 * @return If has default value. 是否具备默认值。
14	 */
15	UFUNCTION(BlueprintNativeEvent, BlueprintPure, Category="ItemFragment")
16	bool MakeDefaultState(FInstancedStruct& DefaultState) const;
17
18	/**
19	 * Determines if the fragment's runtime data supports serialization to disk.
20	 * 确定片段的运行时数据是否支持序列化到磁盘。
21	 * @details Runtime data is replicated over the network, but serialization to disk is optional.
22	 * @细节 运行时数据通过网络复制，但序列化到磁盘是可选的。
23	 * @return True if the data supports serialization, false otherwise. 如果数据支持序列化则返回true，否则返回false。
24	 */
25	UFUNCTION(BlueprintNativeEvent, BlueprintPure, Category="ItemFragment")
26	bool IsStateSerializable() const;

• GetCompatibleStateType: Returns a custom struct defining the fragment’s runtime state.
• MakeDefaultState: Provides default values for the state.
• IsStateSerializable: Determines if the state is runtime-only or should be saved with the item. If true, the runtime state is included when saving the item.

For serialization support, fields in your custom struct must be marked with the SaveGame property, and their types must be serializable by Unreal Engine.

Example

API

All available APIs for ItemInstance can be accessed under the GIS|ItemInstance category.