Item System Technical Specification - wwestlake/Steamforge GitHub Wiki

Item System Technical Specification

This document outlines the complete design and requirements for the Steamforge item management system. It ensures consistent item behavior across inventory, crafting, world interaction, and save/load operations.

1. Item Definition Structure

All items must derive their identity and behavior from a centralized definition class.

UItemDefinition

  • ID: Unique Name/Guid (used for reference and serialization)
  • DisplayName: Localized name
  • Description: Localized tooltip/description text
  • Icon: UTexture2D* for UI display
  • Weight: Float, used in capacity calculations
  • StackSize: Max stackable quantity
  • Tags: FGameplayTagContainer, defines semantic role (e.g., Weapon, Magical, Tool)
  • EquipmentSlotType (optional): Enum or Tag (Head, Back, Tool, etc.)
  • WorldActorClass (optional): Class to spawn when dropped

2. Item Instance Structure

Instances of items (e.g., in inventory) are lightweight references to the definition.

FItemInstance

  • ItemDef: Pointer or soft class reference to UItemDefinition
  • Quantity: Int
  • CustomData (optional): Map or struct for durability, enchantments, or quality

3. Inventory Component

UInventoryComponent

  • Items: TArray<FItemInstance> or TMap<SlotID, FItemInstance>
  • CapacityWeight: Total weight limit
  • CapacitySlots: Optional slot limit
  • Functions:
    • AddItem(FItemInstance)
    • RemoveItem(FName ItemID, int32 Quantity)
    • TransferItem(UInventoryComponent* Target, FName ItemID, int32 Quantity)
    • FindItemByTag(FGameplayTag Tag)

Replication

  • Use OnRep_InventoryChanged with custom replication rules to support multiplayer sync.

4. Crafting System Integration

  • Recipes defined via DataTable (FCraftingRecipe)
    • Inputs defined by tag or ID
    • Outputs as FItemInstance
  • Support both tag-based and exact match crafting
  • Inventory component must support:
    • HasIngredients(FGameplayTagContainer)
    • ConsumeIngredients(FGameplayTagContainer)

5. ItemActor (World Drop Support)

AItemActor

  • Represents a physical item in the world
  • Must support:
    • FItemInstance replication
    • OnInteract to pick up or inspect
    • Visual indicator of stack count
    • Lifetime/despawn logic if needed

6. Save Game Support

FInventorySaveData

  • Serializable structure with item array
  • Integrated with character save or global save slot
  • UInventoryComponent::SerializeInventory() to export/save
  • UInventoryComponent::LoadInventory(FInventorySaveData) to restore

7. UI Integration

  • Inventory slot widget receives FItemInstance
  • Displays:
    • Icon
    • Quantity (if stackable)
    • Durability or modifiers (if present)
  • Drag-and-drop must be supported between containers

8. Tags and Filtering

  • Use FGameplayTagContainer extensively for flexibility:
    • Tool, Food, Weapon, Resource, Magical
    • Used in filtering lists, crafting logic, quest needs, etc.
  • Items can be searched or queried by tag using helper functions

9. Networking

If multiplayer is supported in future:

  • Inventory mutation must be server-authoritative
  • Drag/drop, equip, use actions routed through RPC
  • Item drops are replicated actors

10. Extensions (Planned or Optional)

  • Item modifiers (prefixes, suffixes, enchantments)
  • Durability tracking
  • Per-instance custom names or effects
  • In-world container actors

This specification reflects the minimum requirements for a flexible, extensible, and data-driven item management system in Steamforge. As features are added, this doc will evolve accordingly.