Lost Lily/Grid ToolkitDocs 1.0
Table of Contents
IntermediateValidated 1.0.0

Observe committed events

When to use

Subscribe to committed events when another system must react after a board change. Preview does not publish events, and subscribers never observe a partially applied transaction.

Before you start

Start with a ready board and subscribe before applying the action. Choose the narrowest stream the observer needs:

  • use GridBoardEventBatch for the revision, mutations, operation, result, and all domain events associated with one commit;
  • use a typed subscription when the observer needs only one event type.

Procedure

Excerpt — subscribe, apply, and clean up. Tested using public APIs.

public static EventObservationResult ObserveCommittedEvents()
{
    using GridBoardState state = CreateProgrammaticBoard();
    int batchCount = 0;
    int placedCount = 0;
    GridBoardEventBatch lastBatch = null;
    state.EventsCommitted += batch =>
    {
        batchCount++;
        lastBatch = batch;
    };
    using IDisposable placedSubscription =
        state.Subscribe<GridStructurePlacedEvent>(_ => placedCount++);

    IGridAction action = GridActions.PlaceStructure(
        CreateCrate(),
        new SquareGridCoordinate(1, 1),
        instanceId: "crate-1");
    GridActionRunner.Preview(state, action);
    GridActionResult result = GridActionRunner.Apply(state, action);

    return new EventObservationResult(
        result.Success,
        batchCount,
        placedCount,
        lastBatch?.PreviousRevision ?? -1,
        lastBatch?.Revision ?? -1);
}
  1. Let one owner create each subscription.
  2. React only after the batch arrives; state is already committed and readable.
  3. Dispose typed subscriptions or detach event handlers when the owner stops observing.
  4. Treat subscriber failures as observer faults. They do not roll back a valid commit.

Event-only commits publish at an unchanged revision. Successful no-ops publish nothing. Mutating commits advance each changed board once and publish its designated batch.

Result

In the placement example, preview produces no callback. Apply advances revision 0 to 1 and publishes one batch containing GridStructurePlacedEvent.

Troubleshooting

Symptom Check
Notifications arrive twice Ensure only one owner subscribes and that cleanup runs during disable or disposal.
An observer reads partial state React to the committed batch rather than an action planning callback.
The commit succeeds but an observer throws The commit remains valid; diagnose and fix the subscriber.