Skip to content

🧩 Extensions

Convenience helpers built on top of the result-first APIs.
These are optional shortcuts — ideal for UI glue, quick prototypes, or sample scenes —
but production gameplay should usually use the full InvOpResult methods so you can branch on specific failure codes.

🧠 Use for: lightweight helpers and debug tools
🧱 Avoid for: authoritative gameplay logic or validation flows

Purpose

Provide small utility wrappers and result-formatting helpers to make common operations cleaner in scripts and UIs.
All logic still routes through the main result-first APIs.

Contents

File Purpose
InventoryContainerExtensions Bool-returning wrappers (TryAdd, AddMax, TryRemove, TrySplit, etc.).
InventoryServiceSortExtensions Friendly helpers for sorting/searching via IInventoryService.
InventoryReadExtensions Read-only shortcuts for IReadOnlyInventoryService.
Results/InvOpResultUtil Converts InvOpResult into short UI/debug strings.
Results/CurOpResultUtil Currency result helper — only compiled when REV_CURRENCY_PRESENT.

🚀 Quick Start

✅ Container sugar (bool wrappers)

using RevGaming.RevFramework.Inventory.Extensions;

var ok = container.TryAdd(
    new ItemStack { def = potion, quantity = 1 },
    out var remainder
);

if (!ok)
    ShowToast("Could not place any items");

⚠️ Important:
TryAdd returns true if any amount was added, even partially.

For strict all-or-nothing adds, use the result-first API:

var res = container.TryAddAllResult(stack);
if (!res.Success)
    ShowToast(res.ToUserMessage("Add"));

🔍 Service sorting and searching

// Sort by name asc, rarity desc, empty slots last
svc.SortByName(player);

Two versions of Search exist:

svc.Search(player, "potion");              // defaults to "Backpack"
svc.Search(player, "potion", "Hotbar");    // explicit container
  • Case-insensitive text search over name / category / tags
  • Container names are accepted as strings for convenience, but internally converted to ContainerId before calling service APIs

💬 User Messages

InvOpResultUtil provides short, readable phrasing for UI or debug logs:

var res = svc.MergeThenSwap(player, (ContainerId)"Backpack", 0, 1);
if (!res.Success)
    Debug.LogWarning(res.ToUserMessage("Move"));

Example outputs:

Move failed – not enough space.
Move blocked – no authority.
Move partially succeeded.

⚠️ Notes & Gotchas

  • Authority: Container-level sugar helpers bypass service-level authority checks.
    Use SceneInventoryService methods for authoritative gameplay logic.

  • Sugar helpers never throw — they simply return true / false.

  • Sugar vs Result-First:
    Use sugar helpers in UI, tools, and tests.
    Use result-first APIs for gameplay logic.

  • Null Safety: Sugar helpers assume valid containers/services.

  • Conditional Compilation:
    CurOpResultUtil exists only when REV_CURRENCY_PRESENT is defined.

  • Abstractions → InvOpResult and result semantics
  • Services → where authoritative gameplay mutations occur
  • UI → practical use of sugar helpers in slot/grid logic