道具实例

介绍

道具实例是通用库存系统（GIS）的核心类。道具实例位于道具栈中，并在向道具集合添加道具定义时生成。

每个道具实例是一个轻量的 UObject，用于引用道具的静态数据（通过道具定义）并管理运行时数据。

主要字段

• ID：道具的全局唯一标识符（FGuid），在道具生成时创建。
• Definition：每个道具实例始终持有其引用的道具定义（Definition），通过它可获取所有静态数据。
• IntegerAttributes：一组 Tag->int32 数组，用于动态设置/获取整型数据。
• FloatAttributes：一组 Tag->float 数组，用于动态设置/获取浮点型数据。
• FragmentStates：一组多态的 InstancedStruct 数组，允许为静态的 ItemFragment 附加动态运行时数据。

属性管理

除了在道具定义中添加静态属性外，还可以通过 IntegerAttributes和 FloatAttributes 在道具实例中管理动态属性。关于动态属性系统的技术细节，可参考：动态属性系统。

为道具定义添加动态属性

为使道具支持动态属性，可在道具定义中添加 “Dynamic Attribute Settings” 片段。片段中指定的属性会在道具实例创建时添加到实例状态，并可作为属性的默认值。

持有 ItemInstance 引用时，也可通过 API 直接设置对应类型的属性。

状态管理

除了通过道具片段为道具添加静态数据外，还可以为片段附加动态运行时数据。关于状态管理系统的技术细节，可参考：数据混入系统。

使用场景

• 当动态属性系统过于灵活，不希望管理大量标签时。
• 当简单的 int 或 float 属性无法满足需求时。

使用案例

• Enhanceable Settings：道具片段，定义装备强化相关的静态设置，如最大强化次数、所需材料等。
• Enhanceable State：结构体，存储片段的运行时状态，如已强化次数、强化过的属性等。

简而言之，片段代表静态数据，片段状态代表动态数据。

为道具片段附加运行时状态

为每个道具片段类型重载以下函数，以添加运行时状态：

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：返回自定义结构体，定义片段的运行时状态。
• MakeDefaultState：为该状态提供默认值。
• IsStateSerializable：决定状态是否仅为运行时，或需随道具保存。若返回 true，保存道具时会包括该运行时状态。

为支持序列化，自定义结构体的字段需标记 SaveGame 属性，且字段类型需为虚幻引擎支持的可序列化类型。

案例：

API

所有道具实例的可用 API 可通过 GIS|ItemInstance 分类过滤。