AdvancedValidated 1.0.0

Create and own a board in code

When to use

Choose code-owned board state for generated worlds, tests, headless Unity runtimes, or game systems where project code must create and dispose the board. A code-owned board is sometimes called a programmatic board.

This is an optional ownership model. It is not an extension point, and ordinary Grid Toolkit use does not require it. Start with Create your first board when Unity assets and scene components should own the setup.

Before you start

Complete installation. Create an empty scene and an empty GameObject named Programmatic Board. The logical board does not require a renderer or another Grid Toolkit scene component. Read Choose your scene setup before adding visualization.

Procedure

Create Assets/ProgrammaticBoard/ProgrammaticBoardExample.cs.
Copy the complete component below into the file.

Complete tested example

using System;
using LostLily.GridToolkit.Board;
using LostLily.GridToolkit.Topology.Square;
using UnityEngine;

namespace GridToolkit.Tutorials
{
    [DisallowMultipleComponent]
    public sealed class ProgrammaticBoardExample : MonoBehaviour, IGridBoardStateSource
    {
        public GridBoardState State { get; private set; }
        public event Action StateChanged;

        private void Awake()
        {
            Build();
        }

        public void Build()
        {
            if (State != null)
                return;

            GridBoardDefinition definition =
                SquareGridBoardFactory.CreateRectangle(width: 4, height: 3);
            GridRuntimeConfiguration configuration = new();
            State = new GridBoardStateBuilder(definition, configuration).Build();
            StateChanged?.Invoke();

            Debug.Log(
                $"Programmatic board ready: {State.CellStates.Count} cells, "
                + $"revision {State.Revision}.",
                this);
        }

        public void DisposeState()
        {
            GridBoardState oldState = State;
            if (oldState == null)
                return;

            State = null;
            StateChanged?.Invoke();
            oldState.Dispose();
            Debug.Log("Programmatic board disposed.", this);
        }

        private void OnDestroy()
        {
            DisposeState();
        }
    }
}

Add Programmatic Board Example to the Programmatic Board GameObject.
Enter Play Mode.

Result

The Console reports:

Programmatic board ready: 12 cells, revision 0.

The component retains the same GridBoardState until DisposeState or OnDestroy runs. Construction is initialization, so it publishes no committed action batch and leaves revision at 0.

How the state is created

SquareGridBoardFactory creates a frozen definition. GridBoardStateBuilder copies its cells into mutable board state. Implementing IGridBoardStateSource also lets a GridBoardView follow this state without owning it.

Optional runtime configuration

When project code controls board startup and ownership, build one GridRuntimeConfiguration and supply it when constructing the state. Preview and apply operations then use the services captured by that state; do not compose a new configuration for each action.

Excerpt — supply project-owned runtime services while constructing the state. Tested using public APIs.

public static class DocumentationRuntimeConfiguration
{
    public static GridRuntimeConfiguration Create()
    {
        GridExtensionSnapshotResolverSet resolvers = new(
            new IGridExtensionSnapshotResolver[]
            {
                new TurnCounterSnapshotResolver()
            },
            source: "Game");
        GridStructurePlacementPolicySet placement =
            GridStructurePlacementPolicySet.CreateDefault()
                .Add(new RejectOriginPlacementPolicy());

        return new GridRuntimeConfiguration(
            resolverCatalog: resolvers,
            placementPolicies: placement,
            structureInstanceIdProvider:
                new GridDeterministicStructureInstanceIdProvider());
    }
}

Ownership and disposal

Keep one owner for each state. Views and gameplay systems may observe it, but they must not dispose it. The owner clears its State property, notifies observers, and then disposes the old state from OnDestroy.

Troubleshooting

Symptom	Check
Square types do not compile	Reference `LostLily.GridToolkit.Topology.Square` from your assembly.
A view never binds	Assign this component as the `GridBoardView` state source.
The state is disposed unexpectedly	Ensure observers do not call `Dispose`; only this owner should.

Table of Contents