AdvancedValidated 1.0.0

Authoring and editor adapters

Use case

Use these contracts when project-owned assets or Inspector controls must build validated Grid Toolkit runtime data or participate in board preview.

Contract and ownership

Authoring assets convert serialized configuration to immutable runtime values. Editor adapters add creation, editing, preview, or renderer setup without changing the runtime contract.

A renderer setup recipe is the Editor adapter that creates or configures a renderer stack; it is not a runtime renderer dependency.

Choose the adapter that owns the missing Editor behavior:

Need	Contract
Create a preview layout for a board asset	IGridBoardPreviewLayoutProvider
Convert setup placements to project-owned editing data	IGridBoardSetupPlacementEditorAdapter
Draw a definition extension in cell preview	IGridCellExtensionPreviewProvider
Preview project renderer content	IGridRendererPreviewProvider
Declare which preview features a renderer supports	IGridRendererPreviewCapabilitySource
Draw renderer-specific preview controls or content	IGridRendererPreviewContentDrawer
Project preview geometry into a renderer-specific plane	IGridRendererPreviewProjection
Configure a renderer stack on an existing board view	IGridRendererSetupRecipe
Edit project-specific structure footprints	IGridStructureFootprintEditorAdapter
Publish stable integration name, order, or capability metadata	IGridEditorIntegrationMetadata

Runtime assemblies may depend on Unity runtime APIs, never UnityEditor. Registries and inspectors belong in Editor-only assemblies. Preview values are detached and disposable.

Implementation

Excerpt — provide a deterministic board-preview layout. Tested using public APIs.

public sealed class DocumentationBoardPreviewLayoutProvider :
    IGridBoardPreviewLayoutProvider
{
    public string Id => "game.board-preview-layout";
    public int SortOrder => 1000;
    public bool CanHandle(GridBoardAsset asset) => false;

    public bool TryCreateLayout(
        GridBoardAsset asset,
        float cellSize,
        out IGridLayout layout,
        out string diagnostic)
    {
        layout = null;
        diagnostic = "No project-owned board type matched.";
        return false;
    }

    public static void Register()
    {
        GridBoardPreviewLayoutProviderRegistry.Register(
            new DocumentationBoardPreviewLayoutProvider());
    }

    public static void Unregister()
    {
        GridBoardPreviewLayoutProviderRegistry.Unregister(
            "game.board-preview-layout");
    }
}

The layout provider uses a stable ID, deterministic sort order, narrow CanHandle, and explicit register/unregister lifecycle.

A cell-extension preview provider uses the extension's stable ID and adds only visual preview contributions. This example renders the terrain cost created in Store project data in definitions.

Excerpt — draw one definition extension in the preview. Tested using public APIs.

public string ExtensionId => TerrainCostDefinitionExtension.Id;

public void BuildPreview(
    IGridExtensionReadModel extension,
    GridCellExtensionPreviewContext context,
    GridCellExtensionPreviewBuilder builder)
{
    if (extension is not TerrainCostReadModel cost)
        return;

    builder.AddLabel($"Cost {cost.Cost}", Color.yellow, sortOrder: 20);
}

Excerpt — register and remove the provider deterministically. Tested using public APIs.

public static void Register() =>
    GridCellExtensionPreviewProviderRegistry.Register(
        new TerrainCostPreviewProvider());

public static bool Unregister() =>
    GridCellExtensionPreviewProviderRegistry.Unregister(
        TerrainCostDefinitionExtension.Id);

public static bool VerifyRegistrationLifecycle()
{
    Register();
    try
    {
        return GridCellExtensionPreviewProviderRegistry.TryGet(
            TerrainCostDefinitionExtension.Id,
            out IGridCellExtensionPreviewProvider provider) &&
               provider is TerrainCostPreviewProvider;
    }
    finally
    {
        Unregister();
    }
}

Registration

Register at Editor initialization or from the owning integration and unregister during reload and test cleanup. Use RegisterOrReplace only for an intentional replacement. Duplicate stable IDs should otherwise remain deterministic errors.

Topology authoring safety

Custom topology authoring can use the protected replacement and validation helpers exposed by GridBoardData, GridBoardSetupAsset, GridStructureAsset, and GridStructurePlacementAuthoringData. Use only the helpers that match the custom storage lifecycle. They protect atomic Editor changes; they do not supply a topology algorithm.

Verification

Return actionable preview diagnostics for unsupported assets or configurations. Keep scene-only objects out of serialized authoring data.

Test registration cleanup, duplicate IDs, sort order, asset cloning, validation, preview disposal, and that the runtime assembly compiles for non-Editor platforms.

Done when

The project asset validates, participates in serialization and Undo, rebuilds after reload, preview registrations are deterministic and removable, and runtime data uses only public authoring contracts.

Table of Contents