❓ Inventory — FAQ

This FAQ answers decision questions about using the Inventory system correctly. It does not repeat the README — it helps you choose the right integration point and avoid common mistakes.

---

How do I integrate Inventory into my game?

Minimum setup (single‑player or prototypes):

1. Add SceneInventoryService to the scene
2. Assign an ItemDatabase
3. Add CharacterInventory to your player
4. (Optional) Add InventoryUiBridge for UI

That’s it. Containers are created lazily on first access.

Multiplayer / authoritative setup:

1. Add SceneInventoryService
2. Implement IInventoryAuthority
3. Invoke service mutations only on the authoritative instance (server/host)
4. Replicate state using your netcode

Inventory does not replicate itself.

---

Which API should I use: service or container?

Use SceneInventoryService when:

• The action affects gameplay
• Authority matters
• You need failure reasons
• You’re in multiplayer

Use InventoryContainer / CharacterInventory when:

• You’re building UI
• You’re writing tools or debug panels
• You’re in local or single‑player code

Containers bypass authority by design.

If you’re unsure, use the service.

---

Is Inventory safe to use in multiplayer?

Yes — by design, but not automatically.

Inventory: - Enforces authority via IInventoryAuthority - Returns InvOpCode.NoAuthority when denied - Does not replicate, predict, or rollback

You must: - Call service methods on the authoritative side - Replicate resulting state yourself

This keeps Inventory netcode‑agnostic.

---

Can I use Inventory without UI?

Absolutely.

UI lives entirely under Inventory/UI and is optional. You can: - Drive Inventory from code only - Use your own UI framework - Ignore UI completely

Inventory exposes clean runtime APIs regardless.

---

Can I delete folders I don’t need?

Yes. Inventory is modular by folder.

Common safe deletions:

Folder	Safe to Delete	When
UI/	✅	Using custom UI
Bridges/	✅	No cross‑system integrations
Bridges/Pickups/	✅	Not using Pickups
Snapshots/	✅	No save/load needs
Presentation/	✅	No rarity theming
Use/World/	✅	No demo pickups

Deleting these does not break Inventory.

---

How do I add equipment to my game?

1. Add CharacterEquipment to your character
2. Define slot layout (Weapon, Helmet, etc.)
3. Create EquipmentFilter assets
4. Call TryEquipFromInventoryResult(...)

Equipment: - Uses its own container - Always stores exactly one item per slot - Is not managed by SceneInventoryService

---

Why does TryAdd(...) sometimes return true when not everything fits?

Because it means:

“At least some items were added.”

For strict all‑or‑nothing adds, use:

container.TryAddAllResult(stack);

This distinction avoids silent loss while still supporting partial placement.

---

Why didn’t my UI update?

Common causes:

• You mutated the container directly instead of using the service
• The container didn’t exist yet (lazy creation)
• You subscribed to InventoryContainer.OnChanged instead of service deltas

For UI, always listen to:

SceneInventoryService.OnContainerChanged

---

Can I change container sizes at runtime?

Yes, explicitly:

svc.ResizeContainer(owner, "Backpack", newSize, allowTruncate, out _);

Notes: - Policies apply only at creation time - InventorySizeSync is a scene‑start helper - Resizing emits a full delta resnap

---

Are snapshots a full save system?

No.

Snapshots: - Capture inventory + equipment state - Serialize to JSON DTOs - Handle missing items via policy

They do not: - Manage save slots - Version migrations (beyond a version field) - Persist anything automatically

They are helpers, not a framework.

---

Can I plug in my own effect system?

Yes.

Use UseEffectResolver.ExternalResolvers:

UseEffectResolver.ExternalResolvers += MyResolver;

If your resolver returns an IUseEffect, Inventory will run it. This is how the Pickups integration works.

---

What shouldn’t I do with Inventory?

Avoid:

• Mutating containers directly in multiplayer gameplay
• Using bool helpers for authoritative logic
• Adding gameplay rules inside Bridges or UI
• Treating Inventory as a save/replication system

Inventory is a runtime state manager, not an engine.

---

Where should I look next?

• Services/README.md → lifecycle, authority, deltas
• Containers/README.md → slot rules and deferral
• Use/README.md → item consumption and effects
• Extensions/README.md → optional sugar helpers

---

Support Boundary

If a bug occurs without modifying Inventory code, it’s on us.

If behaviour breaks after modifying Inventory internals or bypassing APIs, that’s outside the support boundary.

This keeps support honest and sustainable.