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 UI bindings or your own UI logic

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 resulting state using your netcode

Inventory does not replicate, predict, or rollback by itself.

Which API should I use: service or container?¶

Use IInventoryService when:

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

Use CharacterInventory when:

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

If you’re unsure, use the service.

Is Inventory safe to use in multiplayer?¶

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.

You can:

• Drive Inventory entirely from gameplay code
• Build your own UI framework
• Ignore UI completely

Inventory exposes clean runtime APIs regardless of presentation.

Can I delete folders I don’t need?¶

Yes. Inventory is modular by folder.

Common safe deletions:

Deleting these does not break the core Inventory system.

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 internal container
• Stores exactly one item per slot
• Coordinates transfers through inventory service operations

Why does AddMax (or similar) sometimes succeed when not everything fits?¶

Because placement behaviour is:

• Full success → Success = true
• Partial success → InvOpCode.Partial (Success = false)

Use GiveExact(...) when you require all-or-nothing behaviour.

For strict all‑or‑nothing adds, use:

svc.GiveExact(owner, stack, container);

or the equivalent exact‑add API.

Partial placement is explicit and signalled via:

InvOpCode.Partial

Why didn’t my UI update?¶

Common causes:

• You didn’t subscribe to service events
• The container didn’t exist yet (no mutation or Get() call has occurred)
• You listened to local changes instead of service deltas

For UI, subscribe to:

svc.OnContainerChanged

Can I change container sizes at runtime?¶

Yes:

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

Notes:

• Size policies apply only at creation
• Resizing emits a container delta event
• Truncation behaviour is explicit

Do Search and Sort create containers?¶

No.

• Search(...) → existing containers only
• Sort(...) → existing containers only

If the container does not exist:

• Search returns no results
• Sort returns ServiceMissing

Are snapshots a full save system?¶

No.

Snapshots:

• Capture inventory + equipment state
• Serialize to JSON
• Handle missing items via policy

They do not:

• Manage save slots
• Handle version migrations automatically
• Persist anything without being called

Can I plug in my own effect system?¶

Yes.

Use:

UseEffectResolver.ExternalResolvers += MyResolver;

If your resolver returns an IUseEffect, Inventory will execute it.

This is how optional integrations (e.g. Pickups) connect into the system.

Can I replace the Unity host?¶

Yes.

SceneInventoryService is the default host, but you can provide your own orchestration layer using public APIs.

You would only do this if you need:

• custom networking architecture
• ECS/DOTS workflows
• server‑authoritative orchestration

Most projects should use the provided host unless they have a clear architectural reason not to.

What shouldn’t I do with Inventory?¶

Inventory is a runtime state manager, not a full game framework.

Where should I look next?¶

• UnityIntegration/README.md → lifecycle, authority, deltas
• Containers/README.md → slot rules and mutation behaviour
• Use/README.md → item consumption and effects
• Extensions/README.md → helper APIs

Support Boundary¶

This keeps support clear and sustainable.