InventoryFramework.UnityAdapter 1.0.1

AdvancedStorage & Crafting — InventoryFramework

A production-ready, server-authoritative inventory and crafting system for Unity, Godot, and Unreal Engine games. All game state lives on your server inside your infrastructure — no player data ever reaches the vendor.

Overview

InventoryFramework is a self-hosted backend that handles:

• Inventory management — slot-based containers, item stacking, transfers, quick-store
• Crafting — recipe definitions, ingredient validation, partial crafting, preview
• Item system — weight, durability, tags, affixes (rolled modifiers), JSON-driven definitions
• Player progression — per-actor recipe unlock keys
• Security — API key authentication, per-key admin privileges, optimistic concurrency
• Licensing — RSA-2048 signed license files, CLI tool for key generation and issuance

The server exposes a gRPC API. Thin adapter libraries for Unity, Godot, and Unreal Engine wrap the SDK into engine-friendly facades.

Editions

Project Structure

InventoryFramework.Domain/            Domain models, aggregates, business rules
InventoryFramework.Application/       Use-case application services
InventoryFramework.Infrastructure/    Item/affix definition loading, crafting evaluator
InventoryFramework.Persistence/       File-based repositories, snapshot serialization
InventoryFramework.Persistence.Sql/   EF Core SQL repositories (provider-agnostic)
InventoryFramework.Server/            ASP.NET Core gRPC host
InventoryFramework.SDK/               Client library (netstandard2.1)
InventoryFramework.UnityAdapter/      Unity-friendly facade (netstandard2.1)
InventoryFramework.GodotAdapter/      Godot-friendly facade (netstandard2.1)
InventoryFramework.UnrealAdapter/     Unreal Engine-friendly facade (netstandard2.1)
InventoryFramework.LicenseGenerator/  CLI tool for RSA key generation and license issuance

Quick Start

1. Configure the server

Edit InventoryFramework.Server/appsettings.json:

{
  "InventoryFramework": {
    "Auth": {
      "RequireApiKey": true,
      "ApiKeys": [
        { "Key": "sk-game-your-secret-key", "IsAdmin": false },
        { "Key": "sk-admin-your-admin-key", "IsAdmin": true }
      ]
    },
    "ItemDefinitionsRootPath": "data/items",
    "RecipeDefinitionsRootPath": "data/recipes",
    "AggregateStorageRootPath": "data/inventories",
    "ProgressionStorageRootPath": "data/progression",
    "LicensePath": "license.json"
  }
}

2. Add item definitions

Create data/items/items.json:

[
  { "id": "wood",  "displayName": "Wood",       "maxStackSize": 50, "weight": 1.0 },
  { "id": "stone", "displayName": "Stone",       "maxStackSize": 30, "weight": 2.0 },
  { "id": "sword", "displayName": "Iron Sword",  "maxStackSize": 1,  "weight": 3.0, "hasDurability": true, "maxDurability": 100 }
]

3. Run the server

cd InventoryFramework.Server
dotnet run

The server starts on https://localhost:7289 by default.

4. Connect from your engine

See the integration sections below for Unity, Godot, and Unreal Engine examples.

Engine Integration

Unity

var facade = new UnityInventoryFacade(new InventoryClientOptions
{
    BaseAddress = "https://your-server:7289",
    ApiKey      = "sk-game-your-secret-key",
    ActorId     = "player-123"
});

// Connect and create a default inventory
await facade.ConnectAsync();
await facade.CreateDefaultInventoryAsync();

// Grant an item
await facade.GrantItemsAsync("container-id", "wood", 10);

// Read current state
var snapshot = facade.CurrentSnapshot;
foreach (var container in snapshot.Containers)
    foreach (var slot in container.Slots)
        if (!slot.IsEmpty)
            Debug.Log($"{slot.ItemDefinitionId} x{slot.Quantity}");

Godot

// In a Node or autoload singleton
private GodotInventoryFacade _inventory;

public override void _Ready()
{
    _inventory = new GodotInventoryFacade(new InventoryClientOptions
    {
        BaseAddress = "https://your-server:7289",
        ApiKey      = "sk-game-your-secret-key",
        ActorId     = GetActorId()
    });
}

public async Task InitializeAsync()
{
    var connectResult = await _inventory.ConnectAsync();
    if (!connectResult.Succeeded)
        GD.PrintErr(connectResult.ErrorMessage);

    await _inventory.CreateDefaultInventoryAsync();
}

Unreal Engine (via C# Scripting / IL2CPP)

var facade = new UnrealInventoryFacade(new InventoryClientOptions
{
    BaseAddress = "https://your-server:7289",
    ApiKey      = "sk-game-your-secret-key",
    ActorId     = "player-456"
});

var connectResult = await facade.ConnectAsync();
if (!connectResult.Succeeded)
    UE.Debug.LogError(connectResult.ErrorMessage);

await facade.CreateDefaultInventoryAsync();

// Grant items with affixes (rolled modifiers)
var affixes = new List<ItemAffixRequest>
{
    new() { AffixDefinitionId = "fire_damage", Value = 42.5f }
};
await facade.GrantItemsAsync("container-id", "sword", 1, affixes);

Item Affixes (Rolled Modifiers)

Affixes let you attach per-instance stat rolls to any item stack. They travel through the full stack: Domain → Persistence → gRPC → SDK → Engine adapters.

Define affixes in JSON

[
  { "id": "fire_damage",  "displayName": "Fire Damage",  "statKey": "damage", "minValue": 10, "maxValue": 50 },
  { "id": "move_speed",   "displayName": "Move Speed",   "statKey": "speed",  "minValue": 1,  "maxValue": 5  }
]

Grant an item with affixes via SDK

var request = new GrantItemsRequest
{
    InventoryAggregateId = aggregateId,
    TargetContainerId    = containerId,
    ItemDefinitionId     = "sword",
    Quantity             = 1
};
request.Affixes.Add(new ItemAffixDto { AffixDefinitionId = "fire_damage", Value = 38.2f });

await client.GrantItemsAsync(request);

Read affixes from a slot

var result = await client.GetInventoryAsync(aggregateId);
foreach (var slot in result.Inventory.Containers[0].Slots)
{
    foreach (var affix in slot.Affixes)
        Console.WriteLine($"{affix.AffixDefinitionId}: {affix.Value}");
}

License Generator

The licgen CLI tool manages RSA-2048 license files.

# Generate a key pair
licgen keygen --out ./keys

# Issue a signed license
licgen issue \
  --private ./keys/private.pem \
  --licensee "My Studio" \
  --tier Pro \
  --expires 2027-12-31 \
  --out ./license.json

# Validate an existing license
licgen validate --license ./license.json --public ./keys/public.pem

Tiers: Demo | Pro | Enterprise

After generating a key pair, embed the Base64 public key printed by keygen into LicenseValidator.EmbeddedPublicKeyBase64 in the server project so the server can verify licenses at startup.

gRPC Endpoints

Authentication: x-api-key header (required). Admin operations additionally require an admin-flagged key.

Further Reading

• Item Definitions — JSON schema, durability, tags, weight
• Crafting & Recipes — Recipe definitions, ingredients, stations, unlock keys
• Player Progression — Recipe unlock keys, grant and revoke
• Server Configuration — API keys, storage paths, persistence
• Persistence — File, SQLite, and custom SQL providers
• SDK Usage — Connecting from plain C# without Unity or Godot
• Unity Integration
• Godot Integration