Skip to content

📦 Inventory System — Public API

This page defines the supported, stable public API for the RevFramework Inventory System.

No lock-in to framework implementations; all systems are interface-driven and replaceable.

If something is not listed here, it is not supported as a public integration point, even if it appears accessible in code.

Audience: Developers integrating Inventory into gameplay, UI, or persistence
Scope: Runtime public API only (Editor / Teaching helpers excluded)
Stability: Breaking changes to items listed here are avoided or versioned

📌 Core Concepts

Inventory in RevFramework is:

  • service-first (with optional convenience components)
  • container-based
  • result-driven

Key characteristics:

  • Containers hold slot-based item stacks
  • All mutations return InvOpResult
  • Items are defined by ItemDefinition assets
  • Container identifiers use ContainerId
  • Runtime logic lives behind IInventoryService

Internal container structures are never exposed publicly.

🧱 Service Entry Points

IInventoryService

Primary runtime interface for inventory mutations.

Supported operations include:

  • GiveExact(owner, stack, container)
  • AddMax(owner, stack, out remainder, container)
  • RemoveByGuid(owner, itemGuid, amount, container)
  • RemoveFromSlot(owner, container, index, amount)
  • SetAt(owner, container, index, stack, out previous)
  • Swap(owner, container, a, b)
  • MergeThenSwap(owner, container, from, to)
  • SplitResult(owner, container, srcIndex, amount, targetIndex)
  • Move(owner, fromContainer, fromIdx, toContainer, toIdx)
  • TransferResult(from, to, itemGuid, amount, fromContainer, toContainer)
  • Sort(owner, container, spec) — sorts existing containers only (fails if container does not exist)
  • ResizeContainer(owner, container, newSize, allowTruncate, out truncated)

All mutations return InvOpResult.

🔍 Read-Only Access

Read-only operations are exposed via the inventory service and container views.

Supported operations:

  • Get(owner, container) — resolves a container view and will create the container if it does not already exist
  • Search(owner, container, query) — returns matches for existing containers only; does not create containers

Events:

  • OnContainerChanged

IReadOnlyInventoryContainer

Read-only view of a container.

Properties:

  • Owner
  • Id
  • Capacity
  • Slots

Methods:

  • Peek(index)

🔎 Service Resolution

Inventory services are resolved using:

SceneInventoryService svc = InventoryResolve.ServiceFrom(context);

Resolution order:

  1. SceneInventoryService.Instance
  2. Scene-local service search
  3. Global fallback search

SceneInventoryService is the default runtime implementation and reference Unity host, but consumers should resolve services via InventoryResolve.

📦 Runtime Components

SceneInventoryService

Scene-level inventory service.

Responsibilities:

  • container creation and tracking
  • mutation orchestration
  • delta publication (via internal tracking)
  • authority enforcement

CharacterInventory

Convenience wrapper around a character’s inventory container.

Provides:

  • container access
  • local mutation helpers
  • inspector debugging
  • owner GUID generation

For multiplayer logic, prefer using IInventoryService directly.

CharacterEquipment

Equipment system managing fixed equipment slots.

Supports:

  • strict equipping
  • unequipping
  • equipment filtering
  • transactional inventory interaction

Events:

  • OnEquipped
  • OnUnequipped

ItemUseSystem

Consumes inventory items and executes their configured use effects.

Works with:

  • ItemDefinition.usable
  • ItemDefinition.useEffects
  • IUseEffect

Effects may be resolved through UseEffectResolver.

🧾 Operation Results

InvOpResult

Returned by all inventory mutations.

Fields:

  • Success
  • Code
  • Message

InvOpCode

Stable outcome codes including:

  • Ok
  • InvalidArgs
  • OutOfRange
  • Empty
  • ServiceMissing
  • NoSpace
  • NotEnoughQuantity
  • NotFound
  • AlreadyFull
  • FilterMismatch
  • SlotInvalid
  • SlotMissing
  • SwapBlocked
  • Partial
  • NoAuthority

📊 Change Events

InventoryDelta

Emitted after successful mutations or container resizes.

Contains:

  • owner
  • container
  • slot-level change list

📦 Data Types

Stable value types used by the system:

  • ItemStack
  • InventorySlot
  • ItemMetaEntry
  • ContainerId
  • ItemGuid
  • InventorySortSpec
  • InventorySortKey

These types are safe for:

  • UI
  • persistence
  • gameplay logic

📚 Item Definitions

ItemDefinition

ScriptableObject representing an item.

Contains:

  • GUID
  • display metadata
  • stack size
  • rarity
  • classification
  • tags
  • use effects
  • equip visuals

ItemDatabase

ScriptableObject storing all known items.

Supports:

  • GetByGuid
  • All
  • MissingPlaceholder

🔧 Extension Points

Inventory supports extension via the following interfaces:

  • IInventorySearch
  • IInventorySorter
  • IItemDatabase
  • IInventoryAuthority
  • IUseEffect

Optional external modules may integrate via:

  • UseEffectResolver.ExternalResolvers

🧩 Supported Extensions

Public helper extensions include:

  • InventoryReadExtensions
  • InventoryServiceSortExtensions
  • CharacterEquipmentExtensions
  • InvOpResultExtensions

These provide convenience helpers without modifying core interfaces.

💾 Snapshots

Inventory snapshots allow save/restore of inventory and equipment state.

Public helpers include:

  • InventorySnapshots.CaptureJson
  • InventorySnapshots.ApplyJson
  • InventorySnapshots.SaveJsonToFile
  • InventorySnapshots.LoadJsonFromFile

Snapshot behavior is controlled via:

  • InventorySnapshotOptions
  • MissingItemPolicy

❌ Explicitly Not Supported

The following are not public API:

  • InventoryContainer
  • EquipmentContainer
  • snapshot DTO classes
  • All types under RevGaming.RevFramework.Inventory.Internal
  • resolver implementation classes
  • default search/sort implementations
  • direct container mutation outside the service

Runtime Guarantees

  • Inventory mutations are deterministic.
  • All operations return InvOpResult.
  • Container change events emit after successful mutations.
  • Container change events also emit after container resize operations.
  • Authority policies are respected for mutations.
  • Snapshot application uses deferred change events and emits consolidated deltas.

Not Guaranteed

  • network replication
  • cross-system transactional atomicity
  • deterministic ordering of external effect resolvers
  • persistence format stability beyond JSON snapshot helpers

TL;DR

If it is not listed here, it is not part of the supported Inventory API.