GearFlow

Overview

GearFlow is a modular inventory, equipment, and crafting framework for Unreal Engine 5. Items are UGearItemDefinition data assets, a small set of flat fields (name, description, icon) plus an opt-in Fragments array. Each fragment owns one concern: stacking lives on UGearStackFragment, equipment slot data on UGearEquipmentFragment, purchase cost on UGearCostFragment, world pickup visuals on UGearPickupFragment, and inventory category on UGearCategoryFragment. An item carries only the fragments it needs.

Three storage components, Inventory, Equipment, and Wallet, extend a shared UGearStorageComponent base that owns the replicated slot array and the full Add/Remove/Query API. Crafting supports both immediate execution and a timed queue. A save library serializes and restores all three component types. A world-facing layer of pickup actors and loot tables covers every item-movement pattern without custom code. GAS is optional.

Getting Started

A working inventory is up and running in five steps. The fastest path requires no C++ beyond adding the module dependency.

Item Definition

UGearItemDefinition extends UPrimaryDataAsset and is the immutable template for an item type. It is never modified at runtime, all runtime state lives on the UGearItemInstance. A small set of flat fields is present on every item; all optional behaviour is added via the Fragments array.

Fragments

UGearItemFragment is the base class for all item fragments. Every fragment declares a policy that controls how the fragment is owned and replicated at runtime. Add your own fragment subclasses in Blueprint or C++ to attach custom per-item data without modifying the definition asset itself.

// Declare a replicated, per-instance durability fragment
UCLASS()
class UDurabilityFragment : public UGearItemFragment
{
    GENERATED_BODY()
public:
    UPROPERTY(EditDefaultsOnly)
    float MaxDurability = 100.f;

    UPROPERTY(Replicated)
    float CurrentDurability = 100.f;

    virtual EGearFragmentPolicy GetPolicy() const override
    { return EGearFragmentPolicy::InstancedReplicated; }

    virtual void OnCreated(UGearItemInstance* Instance) override
    { CurrentDurability = MaxDurability; }
};

Item Instance

UGearItemInstance is the runtime handle for an item occupying a slot. It holds a pointer to the immutable definition and the per-instance copies of any Instanced or InstancedReplicated fragments. Stackable items share one instance per slot; non-stackable items get one instance per unit so each can carry individual state. Instances are owned and replicated by the storage component, never construct one manually. Subclass in Blueprint or C++ via the definition's InstanceClass override.

Storage Component

UGearStorageComponent is the abstract base shared by Inventory and Equipment. It owns the replicated slot array (FastArray via FGearContainerSlot) and exposes the full Add/Remove/Query/Move API. All mutating functions are server-authoritative, calling them on a client has no effect.

Inventory Component

UGearInventoryComponent extends UGearStorageComponent and acts as the player bag, chest, or loot container. Slots can be configured uniformly or split into named categories, each category owns a fixed slice of the slot array and accepts only items whose UGearCategoryFragment tag matches the category's ItemTypeFilter.

Equipment Component

UGearEquipmentComponent extends UGearStorageComponent and manages named gear slots, one item per slot, identified by Gameplay Tag. Only items carrying a UGearEquipmentFragment can be equipped; the fragment's AcceptedSlotTypes must overlap with the target slot tag. When an item is equipped, the component iterates the fragment's EquippedVisuals array and spawns each visual actor server-side, attaching it to the specified socket on VisualAttachTarget. All visual actors replicate to clients. Unequipping destroys them.

Wallet Component

UGearWalletComponent is a tag-keyed currency store with FastArray replication. Any number of currency types are supported, each identified by a Gameplay Tag. Multi-currency cost checks and atomic payment are first-class, CanAfford and PayCost operate on a whole cost map, making vendor transactions and recipe costs a single call. GearFlow ships built-in currency tags: GearFlow.Currency.Gold, GearFlow.Currency.Silver, and GearFlow.Currency.Premium.

Crafting Component

GearFlow provides two crafting components. UGearCraftingComponent executes recipes immediately, ingredients are consumed and outputs are delivered in the same frame. UGearTimedCraftingComponent extends it with a queued model: each craft takes CraftingTime seconds, multiple crafts can be queued up to MaxQueueSize, and progress is queryable at any time. Both components can be placed on a player character or a workbench actor, the caller supplies the source and output storage, so the component is agnostic about where items come from and go.

// Start a timed craft on the server
TimedCraftingComp->StartCraft(SwordRecipe, PlayerInventory, PlayerInventory);

// Bind progress for UI (safe on client after replication)
TimedCraftingComp->OnCraftingProgress.AddDynamic(this, &AMyHUD::OnCraftProgress);

// Poll progress directly if needed
float Progress = TimedCraftingComp->GetCraftingProgress();

Recipes

A UGearCraftingRecipeDataAsset declares what is consumed, what is produced, and how long it takes. Items are referenced by direct UGearItemDefinition pointer, not by tag, so renaming or moving assets never breaks recipe references. Multiple outputs allow byproduct modelling (e.g. smelting ore yields ingots and slag).

Loot Tables

UGearLootTableDataAsset is a weighted pool for procedural inventory population. Define a set of entries each with a weight and quantity range, then call UGearFunctionLibrary::PopulateFromLootTable to roll the table and add results directly to a storage component, useful for chest contents, enemy drops, and random shop stock.

World Pickups

AGearPickupActor is the world-space item representation. The actor class and world mesh are configured per item via UGearPickupFragment. The built-in AGearStaticMeshPickupActor loads and applies the fragment's mesh asynchronously; subclass AGearPickupActor for custom visuals or interaction. Spawn pickups via UGearFunctionLibrary::DropItem, pre-placed pickups call InitializePickup at BeginPlay.

Item Transfer

UGearFunctionLibrary is the static utility layer for all cross-component item movement and world population. Every transfer pattern in GearFlow, looting a chest, buying from a vendor, dropping an item, populating a loot chest, runs through one of these functions. The unified model means OnSlotChanged delegates fire normally on both endpoints.

// Loot a chest into player inventory
UGearFunctionLibrary::TransferItem(ChestInventory, PlayerInventory, Item, Count);

// Buy from vendor (deducts Cost from wallet atomically)
UGearFunctionLibrary::TransferItem(VendorInventory, PlayerInventory, Item, 1, PlayerWallet);

// Drop item to world at a given transform
UGearFunctionLibrary::DropItem(WorldContext, PlayerInventory, Item, 1, DropTransform);

// Populate a chest from a loot table
UGearFunctionLibrary::PopulateFromLootTable(ChestInventory, LootTable);

Save System

UGearSaveLibrary provides static capture and restore functions for all three storage components. Capture functions extract the current component state into a structured save data type that you write to your project's save game object. Restore functions rebuild the component from that saved state, including per-instance custom data via the GetInstanceSaveData / SetInstanceSaveData hooks on UGearItemInstance.

// On save, in your SaveGame object population
UGearSaveLibrary::CaptureInventory(InventoryComp, MySaveGame->InventoryData);
UGearSaveLibrary::CaptureEquipment(EquipmentComp, MySaveGame->EquipmentData);
UGearSaveLibrary::CaptureWallet(WalletComp, MySaveGame->WalletData);

// On load, after the SaveGame object is read back
UGearSaveLibrary::RestoreInventory(InventoryComp, MySaveGame->InventoryData);
UGearSaveLibrary::RestoreEquipment(EquipmentComp, MySaveGame->EquipmentData);
UGearSaveLibrary::RestoreWallet(WalletComp, MySaveGame->WalletData);

Debug Tools

GearFlow registers a UGearCheatExtension (a UCheatManagerExtension subclass) automatically at module startup. The cheat commands are available in any build that has the CheatManager enabled, no manual setup required.

Replication

All three storage components, Inventory, Equipment, and Wallet, use FastArray replication with delta compression. Only changed slot entries are transmitted per frame; a 100-slot inventory that receives one item sends roughly 20–30 bytes, not a full snapshot. The model is server-authoritative: all mutating functions must originate on the server, client-side calls are silently ignored. The recommended pattern is: client sends a Server RPC → server validates and mutates → FastArray replicates the delta → delegates fire on client with the new state.