Skip to content

📦 Containers

Low-level runtime container types used by the Inventory system.

These types define how items are stored, filtered, mutated, and reported at the container level. They are created and managed by the inventory service.

🎯 Purpose

Define the concrete container implementation layer for inventory storage and mutation.

🧩 What Lives Here

  • InventoryContainer → mutable slot-based container for general inventory
  • EquipmentContainer → slot-id keyed container for equipment
  • InventoryDelta → immutable description of service-emitted changes
  • InventorySlot → slot value type used by containers and read surfaces

⚠️ Important Notes

  • These are runtime implementation types
  • Containers are owned and managed by the inventory service
  • Direct container mutation bypasses authority checks
  • Most systems should use the service layer instead of these types directly

🧠 Usage Guidance

Access pattern

Containers are typically accessed through the inventory service or wrapper components.

The service is responsible for:

  • container lifecycle
  • authority enforcement
  • delta emission

InventoryContainer

General-purpose mutable container.

Supports:

  • add, remove, split, merge, swap
  • resize and slot operations
  • count and lookup helpers
  • event deferral

Behaviour notes:

  • acceptance rules are enforced per slot
  • add flow merges first, then fills empty slots
  • operations may return structured result codes

EquipmentContainer

Mutable container for equipment slots.

Supports:

  • slot-based assignment
  • equip and unequip
  • slot filtering
  • event deferral

Behaviour notes:

  • slots hold at most one item
  • slot identifiers are normalised

InventoryDelta

Immutable description of container changes.

Produced by the inventory service after diffing container state.

Direct container mutation does not emit deltas.

InventorySlot

Slot value type used across containers and read surfaces.

Provides:

  • stack data
  • acceptance checks
  • empty state

Events and deferral

Containers support deferred change notifications:

using (container.DeferEvents())
{
    // multiple writes
}

Events are coalesced and emitted once if changes occur.

🚫 Not for Production Use

This folder does not:

  • Enforce authority
  • Provide service-level deltas for direct mutations
  • Define persistence or save/load
  • Replace the service layer API