Item Definition

Introduction

This article elucidates the process of creating and managing item definitions within GIS.

Creating and Managing Item Definitions

To create a new item, create a data asset of the type GIS_ItemDefinition within the editor. Within this definition, you can:

• DisplayName/Description/Icon:Specify the display information for the item as it appears in the UI.
• ItemTags: Associate a set of GameplayTags with the item via ItemTags, which can be utilized for item querying, categorization, and data validation.
• Unique: Designate the item as Unique, indicating its exclusivity; unique items cannot be stacked.
• Fragements: Forming simple to complex item data structures by adding various data fragments through Fragments.

Item Fragments

You can expand an item’s data by incorporating Fragments. GIS includes several built-in common item fragments:

• Fragment_Attributes: Enables the addition of initial attributes to an item. Upon the creation of an item instance, the specified attributes are assigned to it.
• Fragment_EquippableItem: Allows the item to be linked to an equipment definition. When the item is added to a "set for equipping," the equipment component creates the corresponding equipment instance based on this data.
• Fragment_Shoppable: Permits the definition of the currency type and quantity required for buying or selling the item in a shop (e.g., 10 stones, 3 pieces of wood).

Adding New Item Fragments

Users can create new fragment types by subclassing GIS_ItemFragment through Blueprints or C++. Newly added fragment types will automatically appear as options in the Fragments array.

Each Fragment can override the OnInstanceCreated function to perform initialization tasks, which is invoked when an item instance is created.

C++

Below is an implementation example of Fragment_Attributes.

1/**
2 * An item fragment which adding attributes to item instance.
3 */
4UCLASS(DisplayName="ItemFragment_Attributes")
5class GENERICINVENTORYSYSTEM_API UGIS_ItemFragment_SetAttributes : public UGIS_ItemFragment
6{
7	GENERATED_BODY()
8
9protected:
10	UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category=Attribute, meta=(TitleProperty="{Tag} -> {Value}"))
11	TArray<FGIS_GameplayTagFloat> InitialFloatAttributes;
12	UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category=Attribute, meta=(TitleProperty="{Tag} -> {Value}"))
13	TArray<FGIS_GameplayTagBool> InitialBoolAttributes;
14	UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category=Attribute, meta=(TitleProperty="{Tag} -> {Value}"))
15	TArray<FGIS_GameplayTagInteger> InitialIntegerAttributes;
16
17public:
18	virtual void OnInstanceCreated(UGIS_ItemInstance* Instance) const override;
19
20	float GetFloatAttributeByTag(FGameplayTag Tag) const;
21	bool GetBoolAttributeByTag(FGameplayTag Tag) const;
22	int32 GetIntegerAttributeByTag(FGameplayTag Tag) const;
23};

1void UGIS_ItemFragment_SetAttributes::OnInstanceCreated(UGIS_ItemInstance* Instance) const
2{
3	for (int32 i=0;i<InitialFloatAttributes.Num();i++)
4	{
5		Instance->SetFloatAttribute(InitialFloatAttributes[i].Tag,InitialFloatAttributes[i].Value);
6	}
7	for (int32 i=0;i<InitialIntegerAttributes.Num();i++)
8	{
9		Instance->SetIntegerAttribute(InitialIntegerAttributes[i].Tag,InitialIntegerAttributes[i].Value);
10	}
11	for (int32 i=0;i<InitialBoolAttributes.Num();i++)
12	{
13		Instance->SetBoolAttribute(InitialBoolAttributes[i].Tag,InitialBoolAttributes[i].Value);
14	}
15}

Blueprint

Accessing Item Definition Data

Every item instance, upon creation, retains a reference to its Definition, which is replicated over the network. The data within the Definition is strictly read-only.

Once you obtain a reference to an item instance, you can access all static information of the item via GetDefinition. GIS also offers convenient functions to access various Fragment data.

Managing a Large Number of Item Definitions

Since item definitions are data assets, each file represents a distinct item. When the number of items in a project becomes substantial, a well-organized folder structure is paramount for efficient data management.

It is advisable to group item definitions of the same type—those with identical data structure layouts—within the same folder. This allows you to leverage the property matrix editor provided by the UE editor to perform bulk edits on all items within that folder.

Data Validation

The combination of ItemDefinition and ItemFragment offers significant flexibility in the Generic Inventory System (GIS). However, as the number of items grows and item data structures become more standardized, you may want to uniformly constrain the data structure layout of certain item types to reduce human errors and simplify bulk data management via the property matrix editor.

Item Definition Schema

GIS provides the “Item Definition Schema” (ItemDefinitionSchema), a data asset containing a set of validation rules based on ItemTags to constrain the configuration of item definitions. You can:

• Specify required data fragment types, automatically adding missing fragments when saving the definition.
• Define the order of data fragments, automatically sorting them when saving.
• For definitions with specific ItemTags, mandate or prohibit certain data fragments.

Enabling Data Validation

In the GenericInventorySettings section of The Project Setting, you can:

• Specify different schemas based on project paths.
• Set a default schema. If no path-based schema is found, the system falls back to the default schema.

Once an ItemDefinitionSchema is enabled, saving an ItemDefinition triggers a check against the matching validation rules. If the item definition doesn’t meet the rules, the editor displays a warning to prompt the user to fix the errors.