Skip to content

01 — Items & Stacks

Goal

Learn practical slot and stack behaviour: seed items, inspect the live grid, merge or swap slots, split stacks, and clear through the service.

What This Scene Demonstrates

The core stack interaction flow:

UI input → SceneInventoryService → InvOpResult → refreshed container view

The panel uses the service for every mutation. The grid reflects the live container view. The service result is the source of truth.

This scene builds on the Inventory Quickstart by showing practical inventory-grid behaviour: select, merge/swap, quick split, manual split, and auto-placement.

What To Look For

  • Seed Items uses GiveExact(...) to add stackable items through the service
  • Grid reads the live container through Get(...)
  • Left-click selects a slot
  • Left-click another slot routes the action through MergeThenSwap(...)
  • Right-click a stack performs a quick split using auto-placement
  • Shift + Right-click quick splits one item
  • Split allows an explicit amount and target index
  • Target -1 means auto-place through the service
  • Maintenance / Clear All clears by writing ItemStack.Empty through SetAt(...)

Every operation reports through Last Result using InvOpResult.

Sample Scope

This scene focuses only on:

  • Seeding stackable items
  • Reading the live container grid
  • Slot selection
  • Merge-then-swap behaviour
  • Quick split
  • Manual split
  • Auto-placement with target -1
  • Clear through the public service seam

This scene does NOT cover:

  • Search
  • Sorting
  • Transfers between owners
  • Snapshots
  • Equipment integration
  • Production UI implementation

Those behaviours belong in dedicated teachable scenes.

Authority Note

This scene may include a permissive sample authority setup. If no authority is resolved, mutations are allowed for demonstration purposes.

Networking Reminder

No networking is included. Multiplayer authority and synchronization are the developer’s responsibility.

How To Use

  1. Assign stackable ItemDefinitions in Quick Items
  2. Press Give in Seed Items to populate the container
  3. Read the refreshed slots in Grid
  4. Left-click a slot to select it
  5. Left-click another slot to run MergeThenSwap
  6. Right-click a stack to quick split half into auto-placement
  7. Hold Shift and right-click a stack to quick split one item
  8. Select a stack with quantity greater than one to enable Split
  9. Set an amount and target index in Split
  10. Use target -1 for auto-placement, or a specific slot index for explicit placement
  11. Press Clear All in Maintenance to clear slots through the service
  12. Check Last Result after each operation

Failure Behaviour

Failures come directly from InvOpResult.

Common patterns:

  • Give fails → item setup, container setup, capacity, filters, or authority → Check the assigned ItemDefinition, container id, available space, filters, or authority setup

  • MergeThenSwap fails → invalid slots, incompatible stacks, filters, capacity, or authority → Check the selected slots and whether the target can accept the stack

  • Quick split fails → empty stack, quantity too low, no space, filters, or authority → Use a stack with quantity greater than one and confirm there is valid destination space

  • Manual Split fails → invalid source, invalid amount, invalid target, no space, filters, or authority → Check the source stack, amount, target index, available space, filters, or authority

  • Clear All fails → service, container id, or authority issue → Check the container id, service setup, and authority configuration

The panel does not guess. Read the Code and Message in Last Result to decide the next fix.

Behind The Scenes

This panel uses only public service APIs and public data types:

  • SceneInventoryService.GiveExact(...)
  • SceneInventoryService.Get(...)
  • SceneInventoryService.MergeThenSwap(...)
  • SceneInventoryService.SplitResult(...)
  • SceneInventoryService.SetAt(...)
  • IReadOnlyInventoryContainer
  • ItemStack
  • ContainerId
  • InvOpResult

No direct container editing occurs outside the service.

Key Takeaway

Stack behaviour belongs behind the service, not inside the UI layer. The panel sends intent: give, merge/swap, split, or clear. The service applies the rules and returns the result.

That is the foundation for honest drag-and-drop inventory behaviour.