Skip to content

📦 Services

Public service contracts for reading and mutating inventory state.

This folder defines the supported service surface for inventory access. These contracts are the primary way most systems interact with inventory at runtime.

🎯 Purpose

Provide a stable, supported API for reading and mutating inventory state.

🧩 What Lives Here

IReadOnlyInventoryService

Read-only inventory service contract.

Exposes:

  • Get(owner, container)
  • Search(owner, container, query)
  • OnContainerChanged

Intended for systems that observe inventory state without mutating it.

IInventoryService

Read/write inventory service contract.

Inherits from IReadOnlyInventoryService and adds mutation APIs such as:

  • GiveExact
  • AddMax
  • RemoveByGuid
  • RemoveFromSlot
  • SetAt
  • Swap
  • MergeThenSwap
  • SplitResult
  • Move
  • TransferResult
  • Sort
  • ResizeContainer

All mutation methods return InvOpResult.

⚠️ Important Notes

  • These contracts define the supported service surface
  • They do not define runtime implementation details
  • They should be the default integration point for gameplay systems

🧠 Usage Guidance

Result-first mutations

Mutations return InvOpResult instead of exceptions or boolean-only outcomes.

Read vs write separation

  • IReadOnlyInventoryService for observation
  • IInventoryService for mutation

Change notifications

OnContainerChanged represents container state changes caused by service-level mutations.

Direct container mutations are outside this contract.

Container addressing

Service calls use ContainerId rather than implementation-specific lookup rules.

⚠️ Authority Notes

IInventoryService is the supported seam for authority-aware mutation.

In the default runtime implementation, service-level mutations may be authority-gated and can return InvOpCode.NoAuthority when denied.

Direct container access or convenience wrappers may bypass authority.

Use the service when authority enforcement matters.

🚫 Not for Production Use

This folder does not:

  • Define a singleton service
  • Define a specific scene resolution model
  • Provide direct access to mutable runtime containers
  • Guarantee all inventory mutations route through the service

It defines the supported contract, not the full runtime behaviour.