InventoryFramework.UnityAdapter 1.0.8

InventoryFramework.UnityAdapter

Unity integration for InventoryFramework: a server-authoritative inventory and crafting backend. Wraps the gRPC SDK in a MonoBehaviour-friendly facade.

Requirements

• Unity 2021.3 LTS or later
• .NET Standard 2.1 scripting backend
• A running InventoryFramework server

Installation

dotnet add package InventoryFramework.UnityAdapter

Or copy the DLLs from dist/unity/ into Assets/Plugins/.

Setup

Attach to a persistent GameObject (e.g. a GameManager):

using InventoryFramework.UnityAdapter.Models;
using InventoryFramework.UnityAdapter.Services;

public class InventoryManager : MonoBehaviour
{
    public UnityInventoryFacade Facade { get; private set; }

    private async void Start()
    {
        Facade = new UnityInventoryFacade(new UnityInventoryConfiguration
        {
            ServerAddress = "https://your-server:7289",
            ActorId       = SystemInfo.deviceUniqueIdentifier,
            ApiKey        = "sk-game-your-key"
        });

        var result = await Facade.ConnectAsync();
        if (!result.Succeeded)
        {
            Debug.LogError($"Connect failed: {result.ErrorMessage}");
            return;
        }

        await Facade.CreateDefaultInventoryAsync();
        await Facade.RefreshAsync();
    }

    private void OnDestroy() => Facade?.Dispose();
}

Reading inventory state

var snapshot = Facade.CurrentSnapshot;  // last fetched state, no network call
// or: var snapshot = await Facade.RefreshAsync();  // force network refresh

foreach (var container in snapshot.Containers)
{
    Debug.Log($"Container: {container.ContainerId} ({container.Slots.Count} slots)");
    foreach (var slot in container.Slots.Where(s => !s.IsEmpty))
    {
        Debug.Log($"  Slot {slot.SlotIndex}: {slot.ItemDefinitionId} x{slot.Quantity}");
        if (slot.HasDurability)
            Debug.Log($"    Durability: {slot.CurrentDurability}/{slot.MaxDurability}");
        foreach (var affix in slot.Affixes)
            Debug.Log($"    {affix.AffixDefinitionId}: {affix.Value}");
    }
}

Item operations

// Grant items (admin)
await Facade.GrantItemsAsync(containerId, "wood", quantity: 10);

// Transfer a slot between containers
await Facade.TransferItemsAsync(sourceContainerId, slotIndex: 0, targetContainerId, quantity: 5);

// One-button quick-store (backpack → chest, skips locked slots)
await Facade.QuickStoreToTargetContainerAsync(sourceContainerId, targetContainerId);

// Lock a slot; protected from quick-store and auto-sort. Manual moves still work.
await Facade.LockSlotAsync(containerId, slotIndex: 2, lockSlot: true);

// Split a stack into two slots
var split = await Facade.SplitStackAsync(containerId, sourceSlotIndex: 0, amount: 5);
Debug.Log($"Split landed in slot {split.DestinationSlotIndex}");

// Drop items; returns item id and quantity to spawn a world pickup
var drop = await Facade.DropItemsAsync(containerId, slotIndex: 0, amount: 3);
if (drop.Succeeded) SpawnPickup(drop.DroppedItemDefinitionId, drop.DroppedQuantity);

// Sort all unlocked slots
// sortMode: 0 = ByNameAscending, 1 = ByWeightDescending, 2 = ByTagThenName
await Facade.SortContainerAsync(containerId, sortMode: 0);

Item affixes (per-instance modifiers)

Affixes are rolled modifiers on individual item stacks: fire damage, crit chance, move speed, etc. Define them in Data/Affixes/affixes.json on the server:

// Grant a sword with specific affix values (admin)
await Facade.GrantItemsAsync(containerId, "sword", quantity: 1, affixes: new[]
{
    new ItemAffixRequest { AffixDefinitionId = "fire_damage", Value = 38.5f },
    new ItemAffixRequest { AffixDefinitionId = "crit_chance", Value = 12.0f }
});

// Affixes are returned on every snapshot refresh
var snapshot = await Facade.RefreshAsync();
foreach (var slot in snapshot.Containers[0].Slots.Where(s => !s.IsEmpty))
    foreach (var affix in slot.Affixes)
        Debug.Log($"{slot.ItemDefinitionId} | {affix.AffixDefinitionId}: {affix.Value}");

Crafting

// Preview first: checks ingredient availability without modifying state
var preview = await Facade.PreviewCraftItemsAsync(
    "plank_recipe", sourceContainerId, targetContainerId,
    count: 3, station: "workbench");

Debug.Log($"Can craft: {preview.CanCraftRequestedCount}  Max: {preview.MaxCraftableCount}");

if (preview.CanCraftRequestedCount)
    await Facade.CraftItemsAsync(
        "plank_recipe", sourceContainerId, targetContainerId,
        count: 3, allowPartial: false, station: "workbench");

// List available recipes for current inventory
var available = await Facade.GetAvailableRecipesAsync(sourceContainerId);
foreach (var recipe in available.Recipes)
    Debug.Log($"{recipe.DisplayName} ({recipe.CraftingCategory})");

Player progression

// Unlock a recipe key when player completes a quest or kills a boss
await Facade.UnlockRecipeKeyAsync("tier2_weapons");

// Check what the player has unlocked
var progression = await Facade.GetPlayerProgressionAsync();
foreach (var key in progression.UnlockedKeys)
    Debug.Log($"Unlocked: {key}");

Session controller

For UI screens that need live state and connection tracking:

var controller = new UnityInventorySessionController(Facade);
await controller.StartSessionAsync();

// controller.State.Snapshot      = current inventory
// controller.State.IsConnected   = connection status
// controller.State.ErrorMessage  = last error if any

Error handling

Every operation returns a result with Succeeded and ErrorMessage:

var result = await Facade.TransferItemsAsync(sourceId, slotIndex: 0, targetId, quantity: 5);
if (!result.Succeeded)
    Debug.LogWarning($"Transfer failed: {result.ErrorMessage}");

Full documentation: Unity Integration Guide