Skip to content

🎯 Using the Inventory System

The Inventory system is a scene-scoped, authority-aware container service. It powers adding, removing, sorting, searching, equipping, and using items through a result-first API (InvOpResult).

Designed for developers comfortable with C# in Unity. If you’re looking for a no-code solution, this isn’t the right tool.

Containers are created lazily. Calling Get(), GiveExact(), AddMax(), SplitResult(), etc. will create the container the first time it is accessed for a given owner + container name.

  • Services → lifecycle, deltas, authority, resolution rules
  • Data → ItemDefinition, ItemDatabase, ContainerSizePolicy
  • Equipment → equipping, slot filters, visuals
  • UI → optional reference UI (Unity UI)

🧠 Usage Guidance

If you want terse bool-returning helpers, import:

using RevGaming.RevFramework.Inventory.Extensions;

…but for gameplay logic you should prefer the result-first APIs (GiveExact, SplitResult, TransferResult, etc.) so failure reasons are explicit.

📦 Quickstart

1. Add SceneInventoryService

  • Create an empty GameObject
  • Add SceneInventoryService
  • Assign your ItemDatabase
  • (Optional) assign a ContainerSizePolicy

⚠ Only one SceneInventoryService may exist per scene. Extra instances are disabled or destroyed during initialisation.

2. Add CharacterInventory to your player

This automatically adds InventoryOwnerHook and exposes:

playerCharacterInventory
  • Default backpack size = 24 slots
  • May be overridden by ContainerSizePolicy

3. Subscribe to container deltas

svc.OnContainerChanged += delta =>
{
    bridge.Handle(delta); // e.g. InventoryUiBridge
};

Containers must exist before deltas are emitted.

⚠️ Important Notes

Authority

All authoritative gameplay mutations should be performed through IInventoryService.

  • Service-level mutations consult IInventoryAuthority
  • Denied mutations return InvOpCode.NoAuthority

Direct calls on InventoryContainer or CharacterInventory:

  • Do not consult authority
  • Intended for single-player, local logic, or UI-only usage

If you mutate inventory from a non-authoritative instance, the call may succeed locally but is logically rejected by authority.

Authority Setup

Single-player

InventoryAuthorityBinder

Multiplayer

  • Implement a custom authority binder (NGO / Mirror / Fusion / custom)
  • Invoke mutations only on the authoritative instance (server / host)

🧩 Common Operations

Adding Items (authority-safe)

var res = svc.GiveExact(
    player,
    new ItemStack { def = sword, quantity = 1 },
    "Backpack"
);

Adding Items (local only)

var res = inv.TryAddAllResult(stack);

⚠ Direct container calls bypass authority.

Removing Items

var res = svc.RemoveByGuid(player, "sword-guid", 2, "Backpack");

Splitting Stacks

var splitRes = svc.SplitResult(player, "Backpack", 0, 2, -1);

Equipping

var equipRes = playerCharacterEquipment.TryEquipFromInventoryResult(
    playerCharacterInventory,
    0,
    "Weapon"
);

Unequipping

var unequipRes = playerCharacterEquipment.TryUnequipToInventoryResult(
    playerCharacterInventory,
    "Weapon"
);

Using an Item

var useRes = useSys.UseResult(player, 0);
  • Effects run in order
  • At least one effect must apply
  • Exactly one item is consumed on success
  • Consumption is authority-gated

🧪 Diagnostics

Snapshots (Save / Load)

var json = InventorySnapshots.CaptureJson(playerInv, playerEquip);

Snapshots serialize inventory state only.

They do not provide a full persistence system.

Snapshot Notes

  • Extra slots are ignored
  • Equipment quantities are forced to 1

  • Unknown GUID handling:

  • Skip

  • OR SubstitutePlaceholder (requires ItemDatabase setup)

🧠 Usage Guidance

Sorting & Searching

svc.SortByRarity(player);
var hits = svc.Search(player, "potion");

Sorting is stable and preserves relative order where possible.

Tips

  • Always check Success
  • Use .Code and .Message for UX
  • Prefer service calls for gameplay logic

Common InvOpCodes

Code Meaning
Ok Success
NoSpace Not enough capacity
NotFound Item not found
NotEnoughQuantity Too many removed
FilterMismatch Slot cannot accept item
NoAuthority Authority denied
SwapBlocked Merge/swap blocked
Partial Partial success

🧹 Safe to Remove

Folder Safe to Delete Notes
UI/ Yes Reference UI only
Bridges/ Yes Optional integrations
Equipment/ Yes Only needed if used
Snapshots/ Yes Optional helpers
Presentation/ Yes Visual helpers
  • Services
  • Data
  • Samples/Inventory
  • InventoryDebugPanel

YouTube Playlist: Inventory System Teaching Panels https://www.youtube.com/playlist?list=PLRcFCSvBkJAGXfc2fbQQrJ5WfWVLNqsBJ