InventoryFramework.SDK 1.0.8

InventoryFramework.SDK

Engine-agnostic .NET client for the InventoryFramework gRPC server. Works in any netstandard2.1 project: plain C#, ASP.NET Core backends, test harnesses, or custom game engines.

If you are using Unity, Godot, or Unreal Engine, install the matching adapter package instead; it wraps this SDK in engine-friendly patterns:

• InventoryFramework.UnityAdapter
• InventoryFramework.GodotAdapter
• InventoryFramework.UnrealAdapter

Requirements

• .NET Standard 2.1 compatible runtime
• A running InventoryFramework server (self-hosted ASP.NET Core)

Installation

dotnet add package InventoryFramework.SDK

Quick start

using InventoryFramework.SDK.Grpc;
using InventoryFramework.SDK.Models;

var client = new GrpcInventoryClient(new InventoryClientOptions
{
    ServerAddress = "https://your-server:7289",
    ApiKey        = "sk-game-your-key"
});

// Create an inventory for a player
var created = await client.CreateInventoryAsync(new CreateInventoryRequest
{
    OwnerActorId = "player-001"
});

// Grant items
await client.GrantItemsAsync(
    created.InventoryAggregateId,
    created.SourceContainerId,
    "wood", quantity: 10);

// Read inventory state
var inventory = await client.GetInventoryAsync(created.InventoryAggregateId);
foreach (var slot in inventory.Aggregate.Containers[0].Slots.Where(s => !s.IsEmpty))
    Console.WriteLine($"{slot.ItemDefinitionId} x{slot.Quantity}");

Item affixes (per-instance modifiers)

Affixes are rolled modifiers attached to individual item stacks: fire damage, move speed, crit chance, etc. Define them in Data/Affixes/affixes.json on the server, then grant items with specific values:

await client.GrantItemsAsync(
    aggregateId, containerId, "sword", quantity: 1,
    affixes: new[]
    {
        new ItemAffixRequest { AffixDefinitionId = "fire_damage", Value = 38.5f },
        new ItemAffixRequest { AffixDefinitionId = "crit_chance", Value = 12.0f }
    });

// Affixes come back on every GetInventory call
var inventory = await client.GetInventoryAsync(aggregateId);
foreach (var slot in inventory.Aggregate.Containers[0].Slots.Where(s => !s.IsEmpty))
    foreach (var affix in slot.Affixes)
        Console.WriteLine($"  {affix.AffixDefinitionId}: {affix.Value}");

Inventory operations

// Move items between containers
await client.TransferItemsAsync(aggregateId, sourceContainerId, slotIndex: 0,
    targetContainerId, quantity: 5);

// Bulk-transfer matching stacks (skips locked slots)
await client.QuickStoreItemsAsync(aggregateId, sourceContainerId, targetContainerId);

// Lock a slot (protects it from quick-store and sort; manual moves still work)
await client.LockSlotAsync(aggregateId, containerId, slotIndex: 2, lockSlot: true);

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

// Drop and discard items (returns item id + quantity for world-drop spawning)
var drop = await client.DropItemsAsync(aggregateId, containerId, slotIndex: 0, amount: 3);
if (drop.Succeeded) Console.WriteLine($"Dropped {drop.DroppedQuantity}x {drop.DroppedItemDefinitionId}");

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

Crafting

// Preview before committing
var preview = await client.PreviewCraftItemsAsync(
    aggregateId, "plank_recipe",
    sourceContainerId, targetContainerId,
    requestedCraftCount: 3, station: "workbench");

Console.WriteLine($"Can craft: {preview.CanCraftRequestedCount}");
Console.WriteLine($"Max craftable: {preview.MaxCraftableCount}");

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

// Browse available recipes
var recipes = await client.BrowseRecipesAsync(category: "weapons", station: "forge");
foreach (var recipe in recipes.Recipes)
    Console.WriteLine($"{recipe.Id}: {recipe.DisplayName}");

// Get only recipes the player can currently craft
var available = await client.GetAvailableRecipesAsync(aggregateId, sourceContainerId);

Player progression

Recipe unlock keys gate access to specific recipes. Grant or revoke them as players progress:

// Unlock a recipe (e.g. after boss kill or quest completion)
await client.UnlockRecipeKeyAsync("player-001", "tier2_weapons");

// Check all unlocked keys for a player
var progression = await client.GetPlayerProgressionAsync("player-001");
foreach (var key in progression.UnlockedKeys)
    Console.WriteLine(key);

// Revoke a key
await client.RevokeRecipeKeyAsync("player-001", "tier2_weapons");

Error handling

All result types expose a Succeeded flag and an ErrorMessage when the operation fails:

var result = await client.TransferItemsAsync(...);
if (!result.Succeeded)
{
    Console.WriteLine($"Transfer failed: {result.ErrorMessage}");
    // Common reasons: slot locked, container full, item not found, restriction mismatch
}

Dependency injection

// Program.cs / Startup.cs
services.AddSingleton<IInventoryClient>(sp => new GrpcInventoryClient(new InventoryClientOptions
{
    ServerAddress = configuration["InventoryFramework:ServerAddress"],
    ApiKey        = configuration["InventoryFramework:ApiKey"]
}));

All operations

All requests require an x-api-key header. Admin operations additionally require a key with IsAdmin: true.

Full documentation: SDK Usage Guide