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
- Core Concepts
- Getting Started
- Item Groups
- Item Templates
- Collecting Items
- Manufacturing (Crafting)
- Serialization
- Best Practices
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:
- Groups organize items into categories
- Templates define item blueprints (weight, max quantity, parameters)
- Collectables are runtime instances created from templates
- 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
Dataproperty is transient — use Parameters for persistent custom data - Use
ImageIndexwith aTImageListfor inventory UI icons