IntermediateValidated 1.0.0

Add, read, update, and remove items

When to use

Use these operations for the basic lifetime of an Inventory item. Inventory adds two kinds of data to ordinary Grid Toolkit structures:

GridInventoryItemDefinitionExtension stores shared item-type metadata on the Unity-authored structure definition;
GridInventoryItemInstanceExtension stores mutable quantity on each placed structure.

The authored definition describes the item type. A placed structure in board state is the runtime item instance.

Before you start

Complete Add Inventory to a board in Unity. The excerpts assume you already have state, the authored itemDefinition, a definitionResolver, an instanceId, and a topology-compatible coordinate.

Procedure

Place an item with quantity

Preview the built-in placement action before applying it. Initial quantity is an instance extension, not a second Inventory record.

Excerpt — place an item with its initial quantity. Tested using public APIs.

public static GridActionResult PlaceItem(
    GridBoardState state,
    GridStructureDefinition itemDefinition,
    string instanceId,
    GridCoordinate coordinate,
    int quantity,
    out GridActionResult preview)
{
    IGridStructureInstanceExtension[] initialData = quantity > 1
        ? new IGridStructureInstanceExtension[]
            { new GridInventoryItemInstanceExtension(quantity) }
        : Array.Empty<IGridStructureInstanceExtension>();
    IGridAction action = GridActions.PlaceStructure(
        itemDefinition,
        coordinate,
        initialData,
        instanceId);

    preview = GridActionRunner.Preview(state, action);
    return preview.Success
        ? GridActionRunner.Apply(state, action)
        : preview;
}

Read item metadata and quantity

Resolve immutable item metadata from the definition and mutable quantity from the placed instance. IGridInventoryItemDefinitionReadModel and IGridInventoryItemInstanceReadModel are read-only views.

Excerpt — read an item's definition and current quantity. Tested using public APIs.

public static bool TryReadItem(
    IGridBoardStateView state,
    IGridStructureDefinitionResolver definitionResolver,
    string instanceId,
    out IGridInventoryItemDefinitionReadModel itemType,
    out int quantity)
{
    itemType = null;
    quantity = 0;
    if (!state.Occupancy.TryGetStructure(instanceId, out IGridStructureView item)
        || !definitionResolver.TryGetInventoryDefinition(
            item.DefinitionId,
            out _,
            out itemType))
        return false;

    quantity = item.TryGetExtensionView(
        GridInventoryItemInstanceExtension.Id,
        out IGridInventoryItemInstanceReadModel instanceData)
        ? instanceData.Quantity
        : 1;
    return true;
}

Set quantity

Use GridInventorySetQuantityAction so validation, revision, and event behavior remain inside the action transaction.

Excerpt — change an item's quantity through an action. Tested using public APIs.

public static GridActionResult SetQuantity(
    GridBoardState state,
    IGridStructureDefinitionResolver definitionResolver,
    string instanceId,
    int quantity,
    out GridActionResult preview)
{
    IGridAction action = new GridInventorySetQuantityAction(
        definitionResolver,
        instanceId,
        quantity);
    preview = GridActionRunner.Preview(state, action);
    return preview.Success
        ? GridActionRunner.Apply(state, action)
        : preview;
}

Remove an item

Inventory does not add a separate remove action. Remove the placed structure with the built-in remove-structure action.

Excerpt — remove an item with the built-in structure action. Tested using public APIs.

public static GridActionResult RemoveItem(
    GridBoardState state,
    string instanceId,
    out GridActionResult preview)
{
    IGridAction action = GridActions.RemoveStructure(instanceId);
    preview = GridActionRunner.Preview(state, action);
    return preview.Success
        ? GridActionRunner.Apply(state, action)
        : preview;
}

Result

Every preview leaves revision and events unchanged. Each successful placement, quantity update, or removal advances the board revision once and publishes one committed event batch. Rejected actions return diagnostics and do not partially mutate the item.

Troubleshooting

Symptom	Check
Placement cannot resolve a definition.	Pass the definition built from the authored item asset and keep the asset in the active structure library.
Quantity update fails.	Confirm the instance ID exists, resolves to an Inventory definition, and the requested quantity fits its stacking rules.
Read returns no item metadata.	The structure definition is missing its Inventory definition extension or the wrong structure ID was resolved.

Table of Contents