Inventory System

The Gorilla3D Inventory System provides a flexible, template-based item management framework for games. It supports item groups, templates, collectables, manufacturing/crafting, upgrade/downgrade chains, dependencies, multi-language names, and full XML serialization.

Table of Contents

Overview

Class Description
TGorillaInventory Main inventory component
TGorillaInventoryGroup Category of items (weapons, keys, potions, etc.)
TGorillaInventoryItemTemplate Blueprint/prototype for collectible items
TGorillaInventoryCollectable An actual collected item instance
TGorillaInventoryManufacturer Crafting system for combining items
TGorillaInventoryManufacturingProcess A crafting recipe

Core Concepts

The inventory follows a template-instance pattern:

  1. Groups organize items into categories
  2. Templates define item blueprints (weight, max quantity, parameters)
  3. Collectables are runtime instances created from templates
  4. Manufacturers define crafting recipes using ingredients

Collect States

State Description
None No action
Allowed Collection permitted
Collected Successfully collected
QuantityExceeded Max quantity reached
Disabled Item template is disabled
NotFound Template not found
Missing Missing dependency

Getting Started

uses Gorilla.Utils.Inventory;

var
  Inventory: TGorillaInventory;
begin
  Inventory := TGorillaInventory.Create(Self);
end;

Item Groups

Groups categorize your items:

// Groups are collections within the inventory
// Example groups: Weapons, Armor, Consumables, Keys, Notes

Item Templates

Templates define what items look like and how they behave:

Property Type Description
Id String Unique identifier
Name TGorillaInventoryLanguageMap Multi-language display name
Enabled Boolean Whether the item can be collected
Group TGorillaInventoryGroup Category
MaxQuantity Integer Maximum stack size
Weight Single Item weight
MaxWeight Single Maximum weight
IsPooled Boolean Whether instances are pooled
Parameters TGorillaInventoryParameters Custom key-value parameters
ImageIndex Integer Index in a TImageList for UI
UpgradeItem TGorillaInventoryItemTemplate Next tier upgrade
DowngradeItem TGorillaInventoryItemTemplate Previous tier downgrade
Dependency TGorillaInventoryDependencyList Required items for collection

Creating Templates

// Templates are prototypes - build collectables from them
var LCollectable := SomeTemplate.Build();

Dependencies

Templates can require other items to be present before collection:

// Add a dependency: need 2x "Key" to collect "Treasure"
TreasureTemplate.AddDependency('Key', 2);

Upgrade/Downgrade Chains

// Create an upgrade chain: Sword → BetterSword → BestSword
SwordTemplate.UpgradeItem := BetterSwordTemplate;
BetterSwordTemplate.UpgradeItem := BestSwordTemplate;
BestSwordTemplate.DowngradeItem := BetterSwordTemplate;

Collecting Items

Collectables are instances of templates that represent actual items in the player's inventory:

Property Type Description
Id String Unique identifier
Name TGorillaInventoryLanguageMap Display name
Parameters TGorillaInventoryParameters Custom parameters
Data TValue Runtime data (not serialized)

Manufacturing (Crafting)

The manufacturing system allows combining items:

Class Description
TGorillaInventoryManufacturer Contains crafting processes
TGorillaInventoryManufacturingProcess A single recipe
TGorillaInventoryIngredient An ingredient in a recipe

Manufacturing States

State Description
Undefined Not started
Processing Currently crafting
Completed Crafting finished
Failed Crafting failed

Serialization

The inventory system serializes to XML:

// Save to XML
Inventory.ToXml(ParentXmlElement);

// Load from XML
Inventory.FromXml(XmlNode, LoadingCache);

Multi-language support is built-in via TGorillaInventoryLanguageMap — each name can have translations for different languages.

The inventory can also be managed through the Assets Manager as INVENTORY asset type.

Best Practices

  • Define all templates first, then create collectables from them at runtime
  • Use groups to organize items logically (weapons, consumables, quest items)
  • Set MaxQuantity to prevent unlimited stacking
  • Use Parameters for game-specific values (damage, healing amount, duration)
  • Use Dependencies to gate item collection behind prerequisites
  • Use Upgrade/Downgrade chains for item progression systems
  • The Data property is transient — use Parameters for persistent custom data
  • Use ImageIndex with a TImageList for inventory UI icons