Workes.InventorySystem 3.0.0

Workes.InventorySystem

Workes.InventorySystem is a reusable .NET inventory library for games and other applications that need structured item ownership. It is not tied to one genre, UI, container shape, or persistence format.

The package separates item identity, inventory contents, stacking, capacity, rules, placement, transactions, events, and persistence so each concern can be configured or extended without replacing the rest of the system.

Highlights

• Catalog-registered item definitions with stable IDs, tags, typed attributes, schemas, and ID migrations.
• Configurable stack resolvers, capacity policies, and inventory rules.
• Entry, slot, grid, multi-cell grid, equipment, and sectioned layouts.
• Direct placement, automatic placement, movement, swapping, sorting, and repacking.
• Atomic local and cross-inventory transactions, bulk transformations, and swaps.
• Per-instance metadata with inventory-owned validation and events.
• Structured change events for gameplay, auditing, and incremental UI synchronization.
• Portable, serializer-friendly snapshots with exact restoration, reconciliation, and salvage workflows.
• Extension contracts for definitions, policies, rules, layouts, footprints, sorting, and persistence codecs.

Installation

Install the package from NuGet:

dotnet add package Workes.InventorySystem --version 3.0.0

Or add a package reference:

<PackageReference Include="Workes.InventorySystem" Version="3.0.0" />

The package targets .NET Standard 2.1.

Quick Example

Create a catalog, register the canonical item definitions, freeze the catalog, and use an inventory created by a manager:

using System;
using Workes.InventorySystem.Capacity;
using Workes.InventorySystem.Core;
using Workes.InventorySystem.Layout;
using Workes.InventorySystem.Stacking;

var catalog = new ItemCatalog<string>();

var apple = new ItemDefinition<string>("apple");
var coin = new ItemDefinition<string>("coin");

catalog.Registry.Register(apple);
catalog.Registry.Register(coin);
catalog.Freeze();

var manager = new InventoryManager<string>(
    new FixedSizeStackResolver<string>(maxStack: 10),
    new UnlimitedCapacityPolicy<string>(),
    new EntryLayout<string>(),
    catalog);

var inventory = manager.CreateInventory();

inventory.Add("apple", amount: 5);
inventory.Add("coin", amount: 25);

Console.WriteLine(inventory.Count("apple"));     // 5
Console.WriteLine(inventory.Find("coin").Count); // 3 stacks: 10, 10, 5

Use throwing methods such as Add(...) when success is expected. Use their Try... counterparts when rejection is a normal application branch; rejected operations leave the inventory unchanged and report an InventoryFailure with a stable Kind, stable Code, and human-readable Message.

See the Quick Start for the complete first-use walkthrough.

Mental Model

Two rules prevent many integration mistakes:

1. Reuse the exact definition objects registered in the catalog. A detached definition with the same ID is not the canonical definition.
2. Treat Inventory.Items as ownership and storage order, not UI order. Query the active layout for visible placement.

Built-In Placement Models

Layouts own contexts, placement, sorting, and repacking. Inventory remains responsible for item lifetime, validation, atomic commit, events, and application-facing layout queries such as GetItemAt(context).

Documentation

Start here:

1. Quick Start
2. Core Concepts
3. Inventory Operations

Focused guides:

• Catalogs And Definitions
• Layouts
• Policies And Rules
• Transactions
• Events And UI Integration
• Failure Handling
• Persistence
• Extending The Inventory System

See the Changelog for release history and migration-sensitive changes.

The repository also contains executable examples covering item setup, layouts, transfers, policies, events, metadata, and other common workflows. Use them when you find the documentation to be lacking examples.

Persistence Boundaries

CaptureSnapshot() returns a non-generic, deeply detached object model suitable for ordinary serializers. The package owns inventory snapshot semantics, validation, and restoration; your application chooses JSON, MessagePack, another serializer, and its own file or database workflow.

The package does not own save slots, compression, encryption, application-envelope versioning, or file I/O. Use the portable snapshot APIs for package-owned persistence; the old generic compatibility serializer API was removed in 3.0.

License

Workes.InventorySystem is available under the MIT License.