Transfer and merge items
When to use
Use a move action for a new position on the same board. Use a transfer operation when an item must move between boards. Merge stacks only when their item IDs match and the destination has capacity.
Before you start
Both boards must be live GridBoardState instances,
and the destination must be able to resolve the transferred definition. The excerpts assume
sourceState, destinationState, definitionResolver, the source and target instance IDs, and a
destination coordinate are available.
Procedure
Begin a logical drag session
A drag session captures the source board, placed item, grabbed cell, and orientation. It does not depend on uGUI or a pointer controller.
Excerpt — begin a logical drag session for one item. Tested using public APIs.
public static GridInventoryDragSession BeginDrag(
GridBoardState sourceState,
string instanceId)
{
if (!GridInventoryInteraction.TryBeginDrag(
sourceState,
instanceId,
out GridInventoryDragSession session,
out GridActionFailure failure))
throw new InvalidOperationException(failure.Message);
return session;
}
Transfer an item
Preview first. Applying a successful GridInventoryTransferItemOperation removes the source instance and places the same instance on the destination atomically. The result object belongs to that Preview or Apply call; do not reuse a preview result as the applied result.
Excerpt — transfer one item between boards atomically. Tested using public APIs.
public static GridInventoryOperationResult TransferItem(
GridInventoryDragSession session,
IGridStructureDefinitionResolver definitionResolver,
GridBoardState destinationState,
GridCoordinate destinationCoordinate,
out GridInventoryOperationResult preview)
{
preview = session.PreviewDrop(
definitionResolver,
destinationState,
destinationCoordinate);
return preview.Success
? session.ApplyDrop(
definitionResolver,
destinationState,
destinationCoordinate)
: preview;
}
Merge matching stacks
GridInventoryStackMergeOperation requires matching item IDs, stackable definitions, and free capacity in the target. A partial merge fills the target and leaves the remaining quantity on the source instance.
Excerpt — merge matching stacks up to the target capacity. Tested using public APIs.
public static GridInventoryStackMergeResult MergeStacks(
GridInventoryDragSession session,
IGridStructureDefinitionResolver definitionResolver,
GridBoardState targetState,
string targetInstanceId,
out GridInventoryStackMergeResult preview)
{
preview = session.PreviewMerge(
definitionResolver,
targetState,
targetInstanceId);
return preview.Success
? session.ApplyMerge(
definitionResolver,
targetState,
targetInstanceId)
: preview;
}
Result
Preview leaves both boards unchanged. Apply commits both participating boards atomically: either all planned source and destination changes succeed, or neither board changes.
Each Preview or Apply call returns its own GridInventoryOperationResult or stack-merge result. Read that result for source cells, destination cells, quantities, and diagnostics.
Troubleshooting
| Symptom | Check |
|---|---|
| Transfer preview fails. | Confirm the destination resolves the definition and that every destination footprint cell is valid and free. |
| Merge preview fails. | Compare item IDs, stackable flags, current quantities, and target capacity. |
| One board appears to change during preview. | Keep project callbacks read-only during planning; only call Apply after an accepted preview. |