Skip to content

🔌 Inventory System — Integration Surfaces

This page explains where new gameplay logic should integrate with the RevFramework Inventory system.

If you're adding a new mechanic, start here.

The Inventory architecture is intentionally modular. Each gameplay behaviour belongs to a specific extension surface. Choosing the correct surface keeps systems predictable, maintainable, and compatible with the rest of the framework.

💡 If you're unsure where logic belongs, start at IInventoryService and move outward only when a clearer extension surface exists.

🧠 Supported Integration Surfaces

Goal Extension Point Example
Mutate inventory state IInventoryService add, remove, split, move
Read inventory state IReadOnlyInventoryContainer (via IInventoryService.Get) UI, tooltips, AI checks
Gate mutations IInventoryAuthority server authority, ownership checks
Customize searching IInventorySearch tag-aware search, fuzzy search
Customize sorting IInventorySorter rarity-first, category-first
Define item data ItemDefinition (data) / IItemDatabase (lookup abstraction) items, placeholders, lookup
Control equipment validity EquipmentFilter weapon-only, helmet-only
Coordinate equipment flow CharacterEquipment equip / unequip logic
Run item use behaviour IUseEffect heal potion, mana restore
Resolve external item effects UseEffectResolver.ExternalResolvers bridge external systems into inventory use-effects
Capture / restore state InventorySnapshots save/load, restore
Add optional cross-system integrations Integrations/... Pickups, future systems
Replace default orchestration Custom IInventoryService implementation custom host, server-driven systems
Identify containers ContainerId backpack, hotbar, custom containers

⚙ Example Decision Flow

Add an item to a player

Use:

IInventoryService (mutation APIs)

This is a gameplay mutation, so it belongs at the service layer.

Show a UI inventory grid

Use:

IInventoryService (read operations)
IReadOnlyInventoryContainer

UI should read, not mutate.

Prevent non-authoritative clients from changing items

Use:

IInventoryAuthority

Authority decides whether a mutation is permitted, not how inventory behaviour is executed.

Add a custom “sort by value” mode

Use:

IInventorySorter

Sorting policy belongs in the sorter seam, not in UI code.

Add “use item” behaviour for a custom external system

Use:

IUseEffect

or, if coming from another module:

UseEffectResolver.ExternalResolvers

Restrict a slot to helmets only

Use:

EquipmentFilter

This is a slot acceptance rule, not a mutation permission rule.

Save and restore inventory contents

Use:

InventorySnapshots

Snapshots handle inventory state capture and restore, but do not provide full save system features such as versioning, migration, or persistence orchestration.

⚠ Common Mistakes

Avoid the following:

  • Assuming containers always exist (containers are created lazily on first access)
  • Mutating internal containers directly
  • Putting multiplayer authority logic inside UI
  • Treating CharacterInventory as the authoritative multiplayer API
  • Putting gameplay rules into bridges or presentation helpers
  • Treating snapshots as replication or save-slot infrastructure
  • Using external integrations to replace the core service layer

🧩 Architecture Summary

Gameplay Mutation Request
↓
Authority Validation
↓
Service-Orchestrated Mutation
↓
Container / Slot State Update
↓
Delta Computation (internal)
↓
Delta Event Emission
↓
UI / Observers Refresh

Optional flows:

Equipment → CharacterEquipment → Inventory interaction
Use Item → ItemUseSystem → IUseEffect / Resolver
Persistence → InventorySnapshots
Integrations → Integrations/Inventory/...

🔍 Behaviour Notes

  • Search and sort operations apply to existing containers only and do not create containers implicitly.
  • Mutation operations may lazily create containers when required.
  • Authority is always validated before any mutation is executed.

🔗 Related Docs

  • Mental Model
  • Public API
  • System Guarantees Matrix
  • FAQ