Skip to content

📊 Data

Defines the item model, authorable assets, and runtime structures used throughout the Inventory system.

✅ ScriptableObject item assets (ItemDefinition, ItemDatabase)
✅ Runtime-safe structs (ItemStack, ItemMetaEntry, InventorySlot)
⚠️ Not fully serializable — some fields (e.g., slot predicates) are runtime-only
✅ Extensible metadata and size policies

Purpose

Provides the canonical data definitions and runtime carriers shared across all inventory features:
item assets, runtime stacks, slot wrappers, and initial container size policies.

Contents

Type Purpose
ItemDefinition Authorable ScriptableObject row: GUID, name, visuals, stack size, rarity, category/tags, use effects.
ItemDatabase Central item registry with case-insensitive GUID lookup and optional placeholder fallback.
ItemStack Runtime stack: definition + quantity + durability + metadata.
ItemMetaEntry One key/value metadata pair.
InventorySlot Runtime slot wrapper with optional accept predicate.
ContainerSizePolicy Authorable defaults for initial slot counts per container name.

🌍 What Is an Item?

Each item is defined by an ItemDefinition ScriptableObject —
a stable table row identified by a GUID.

[CreateAssetMenu(menuName = "RevFramework/Inventory/Item")]
public class ItemDefinition : ScriptableObject
{
    public string guid;
    public string displayName;
    public Sprite icon;
    public int maxStack = 1;
    public int rarity = 0;
    public string category;
    public string[] tags;
}

ItemDefinition also includes:

  • pickupPrefab
  • usable + useEffects[]
  • equipVisualPrefab + equipSocket
  • Auto-generated GUID in editor if missing
  • Normalized category/tags (trimmed + lowercase) for fast runtime matching

🗄️ ItemDatabase

Central registry used by services to resolve item GUIDs.

Features

  • Case-insensitive lookup (StringComparer.OrdinalIgnoreCase)
  • All GUIDs trimmed before storage
  • Duplicate GUIDs overwrite previous entries (warning logged)
  • Optional MissingPlaceholder for snapshot restores
var sword = db.GetByGuid("4f21c...");

Includes an editor-only “Scan & Add All Items In Project” utility for bulk authoring.

📦 ItemStack

Value-like struct representing a specific stack of items.

Field Description
def ItemDefinition reference
quantity Current count (not clamped by the struct)
durability Optional float (commonly 0–1)
meta List of key/value metadata pairs (unordered; last-write-wins)

Helpers

stack.IsEmpty;
stack.Clone();
stack.WithQuantityDeep(q);
stack.TryGetMeta("key", out value);
stack.SetMeta("key", "value");
stack.RemoveMeta("key");

Equality & Stackability

ItemStackUtil.StacksEqual(a, b);
a.CanStackWithStrict(b);
  • Durability uses epsilon comparison
  • Metadata treated as an unordered dictionary (last-write-wins)
  • Used by deltas, diffs, sorting, and rollback checks

🔑 Slot Model

InventorySlot

  • Holds an ItemStack
  • Has an optional Accepts(ItemDefinition) predicate
  • Default Accepts is null, meaning “accept anything”
  • Runtime-only (not serialized)

EquipmentSlot

  • Holds exactly one item (quantity = 1)
  • Uses EquipmentFilter to validate category/tags
  • Identified by string slotId (canonicalised by EquipmentContainer)

📐 Container Size Policy

Optional ScriptableObject defining initial slot counts per container name.

new Entry { name = "Backpack", size = 24 }
new Entry { name = "Hotbar",   size = 8  }

Rules

  • Case-insensitive comparison (Trim().ToLowerInvariant())
  • First match wins
  • Applied when SceneInventoryService lazily creates a container
  • If no policy matches, fallback defaults apply

⚠️ Notes & Gotchas

  • GUIDs must be unique — duplicates overwrite (warnings logged)
  • ItemStack does not clamp quantity — containers enforce maxStack
  • Category/tags are normalized automatically at runtime
  • Durability uses epsilon comparison
  • Metadata behaves like an unordered map (last-write-wins)
  • InventorySlot.Accepts is runtime-only
  • MissingPlaceholder applies only during snapshot restore under the correct policy
  • Containers → how slots are stored and mutated
  • Services → how containers, databases, and policies interact
  • Equipment → category/tag filtering and gear slots
  • Use → item-use and effect execution