👤 Character

Components that let a GameObject access and expose inventory containers —
players, NPCs, chests, vendors, or any other “inventory-holding” entity.

✅ Runtime-safe and authority-agnostic
✅ Works with SceneInventoryService out of the box
✅ Adds automatic cleanup when destroyed

---

Purpose

This folder provides the per-entity bridge between scene objects and the Inventory system.
It handles binding, lookup, and cleanup — while SceneInventoryService remains the actual owner
of all containers.

Character components never store inventory locally; they only expose containers managed by the service.

---

Contents

Component	Purpose
CharacterInventory	Binds a specific container name (e.g. "Backpack") for this GameObject via the service.
InventoryBinder	Convenience component that binds a container to a UI or observer.
InventoryOwnerHook	Ensures the service clears containers when the owner is destroyed.

---

🚀 Quick Start

1. Add CharacterInventory to your player prefab.
2. Defaults to a 24-slot "Backpack" container (service-owned).

3. Automatically adds InventoryOwnerHook.

4. (Optional) Add CharacterEquipment for equippable gear.

5. (Optional) Add InventoryBinder to wire UI or observer logic.

---

🎒 CharacterInventory

Exposes one named container for a character (default: "Backpack").
The container is always created and owned by SceneInventoryService,
not by this component.

var cont = characterInventory.Container;

// Direct container access (authority bypass)
InvOpResult res = cont.TryAddAllResult(new ItemStack { def = potion, quantity = 3 });

cont.TryRemoveResult(potionGuid, 1);
int potions = cont.CountOf(potionGuid);

⚠️ Direct access bypasses authority.
Intended for local tools, UI, or inspectors.
Use SceneInventoryService for authoritative gameplay logic.

---

Events

OnChanged — fired when the bound container’s contents change.

characterInventory.OnChanged += () => ui.Refresh();

---

Inspector Fields

Field	Description
backpackSize	Initial slot count when no policy overrides it.
inspectorContainer	Container name to bind (case-insensitive; canonicalised).
ownerGuid	Stable ID for save/load systems (auto-generated).

---

Binding Details

• Binding is lazy — resolved on first access or OnEnable
• If the service is unavailable, binding retries on the next frame
• Container names are canonicalised (trimmed + lowercase)

---

🔗 InventoryBinder

Connects a container to UI or observer scripts.

public class MyUI : MonoBehaviour
{
    public InventoryBinder binder;

    void OnEnable()
    {
        // Binder auto-binds on enable
    }
}

Field	Description
owner	GameObject owning the container (defaults to Player-tag).
containerName	Case-insensitive container name.

The binder subscribes to the container’s OnChanged event and calls Refresh() internally.

---

🪝 InventoryOwnerHook

Ensures all containers for a GameObject are cleared when it is destroyed.

• Uses the active service if available
• Falls back to a cached service reference if teardown order changes (scene unload, playmode exit)

Automatically added by CharacterInventory.

---

⚠️ Notes & Gotchas

• CharacterInventory binds one container per component
• Service owns all containers — character components are views only
• Binding is lazy and retries safely
• Authority is enforced only by the service, never by character components
• ownerGuid is auto-generated and stable for saves
• InventoryBinder silently no-ops if the owner cannot be resolved

---

📎 Related

• Services → container creation, authority, and deltas
• Equipment → equippable gear system
• UI → slot grids, split popups, and UI bridges