Luna UI Documentation

The Inventory System package was heavily refactored in the 1.5.x architecture shift.

It now follows a more modular runtime layout and is designed to work well with the Data package and CatalogKey-driven authoring patterns.

What This System Solves

defining items and item instances
moving items between inventories/slots
building UI views (inventory, equipment, tooltips)
composing item behavior (equip, consume, stat preview, etc.) via features

Item database (`IInventoryItemDatabase`)

UI and inventory code take IInventoryItemDatabase (lookup definitions, icons, CreateItem, etc.). Resolve it with ServiceLocator.Get<IInventoryItemDatabase>() after registration.

Default implementation: InventoryItemDatabaseSO — a ScriptableObject that reads item definitions from IAssetCatalog<InventoryItemDefinitionSO> / ICatalog registered under the items provider id (same pattern as samples). Use the asset as-is, subclass it, or provide your own IInventoryItemDatabase and register that instance against the interface.

The old InventoryItemDatabase type name is removed; migrate your ItemDatabase (or similar) to InventoryItemDatabaseSO or IInventoryItemDatabase.

Item definition assets (`InventoryItemDefinitionSO`)

Definitions are always DataSO<InventoryItemDefinition> via InventoryItemDefinitionSO. There is no InventoryItemDefinitionSO<T>—catalogs and samples expect that concrete SO type.

Optional thin subclass for menu naming only: class EquipmentSO : InventoryItemDefinitionSO { } with [CreateAssetMenu(...)].
Equipment stats / slot type: use EquipableFeature (and related RPG bridge features) on InventoryItemDefinition.Features, instead of a parallel generic definition type on the SO.

Key Ideas

Data-first definitions: item “definitions” are authored as data (good for JSON, remote content, versioning).
Key-based asset lookup: fields like icons can be stored as keys (e.g. CatalogKey) while still showing rich inspector previews.
Feature composition: items gain gameplay capabilities by attaching feature modules, instead of relying on deep inheritance trees.

Tooltips: stat lines moved to features

Inventory tooltips no longer call a virtual like GetItemStatDisplayLines on definitions. The slot tooltip builder calls InventoryItem.BuildItemTooltipStats, which loops InventoryItemDefinition.Features and, for each IItemFeature, calls BuildTooltipContent(VisualElement host, in ItemTooltipContext context).

Migrate custom stat/ingredient lines by implementing IItemFeature (plus IFeature.CloneFeature), add an instance to the item definition’s Features list, and build VisualElement children on the host (see ItemTierFeature for a small example, EquipableFeature for RPG stat text). Use ItemTooltipContext for IInventoryItemDatabase, optional attribute-name filtering, and equipment comparison via GetComparison.

Note: InventoryItemDefinition.Features is typed as List<IFeature> (the base interface). If your project has other IFeature sub-interfaces (e.g. unit feature definitions), the Inspector dropdown will show all types. To restrict the dropdown to inventory features only, change the list type to List<IItemFeature> and register a [CustomPropertyDrawer(typeof(IItemFeature), true)] that scans only for IItemFeature types. See Sub-interface type filtering for the full pattern.

ItemTierFeature tooltips resolve the tier line through IValueCatalog registered under InventoryConstants.ItemTierCatalogId (GetDisplayValue on the effective CatalogKey, fallback to the raw key). Slot USS on the Background button adds a slug derived from that display when available (e.g. common from Common), otherwise from the key (e.g. 0 stays 0). Style tier chrome in USS against those slugs; ClearSlotVisual removes slugs and legacy raw-key classes for all keys listed in the tier ICatalog.

Suggested Mental Model

Definition: “what this item type is” (static data)
Instance: “a concrete owned item” (runtime state like stack count, durability, rolled stats)
Slot: “a location that can hold an item” (inventory slot, equipment slot, hotbar slot)
Feature: “optional behavior attached to a definition/instance” (equipable, consumable, stat provider, etc.)

Package Layout (Common Areas)

Runtime/Item/Core: definitions, references, item databases
Runtime/Item/Features: feature modules (compose behavior)
Runtime/Item/Slot: slot controllers, visuals, tooltip builders
Runtime/UI: inventory/equipment UI controllers and views
Runtime/ItemStats: stat line data and controllers (UI-friendly formatting)
Data.DropTable/Runtime: weighted drop sources and roll helpers — see Drop Table

Integration Points

Data Package: makes “definitions as data” practical (default vs actual workflows, JSON tools).
Data Catalogs + CatalogKey: decouple definitions from direct Unity asset references while keeping authoring comfortable.
RPGStats (optional): when you want item features to drive stat deltas, comparisons, and equipment rules.

What Changed in 1.5.0 (High-Level)

inventory became more modular (separated responsibilities and assemblies)
moved toward feature-driven item behavior
stronger emphasis on key-based references and data-driven definitions

Inventory System