BeginnerValidated 1.0.0

Troubleshooting

Start at the first boundary that fails. Later symptoms are often consequences.

Find the failing boundary

What you observe	Check first
The project does not compile after import.	Installation and dependencies
Grid Toolkit compiles, but Sample scripts or components are unavailable.	Sample dependencies
An authored board never becomes ready.	The authoring build report
Preview and Apply disagree, or an action is rejected.	Action planning
Save or restoration fails.	Snapshot resolvers and validation
Board state is correct, but its display or input is wrong.	Visualization or hit resolution
Behavior duplicates after scripts reload.	Editor registration

The project does not compile after import

1. Confirm there is only one imported Grid Toolkit version.
2. Resolve Package Manager dependencies.
3. If errors name UnityEngine.UI, Image, Graphic, or VertexHelper, confirm that a compatible com.unity.ugui 2.x package is installed and resolved.
4. Distinguish product errors from project scripts that still use a pre-1.0 API.

Do not edit shipped assembly definitions. See compatibility and dependencies.

Sample scripts or components are unavailable

Grid Toolkit can compile while Sample assemblies remain inactive. Samples additionally require:

• compatible uGUI, Input System, and Universal Render Pipeline (URP) packages;
• an active URP asset;
• Universal Renderer as that asset's default renderer.

Grid Toolkit does not install the optional Sample packages or change the project's render-pipeline settings.

Missing Sample components before that setup do not indicate a missing Grid Toolkit runtime or uGUI module file. Do not save Sample scenes while their assemblies are inactive.

See Samples & Demos for the shared Sample requirements and catalog.

A board asset will not build

• Read every GridAuthoringBuildReport message, including source, identity, property path, and index.
• Verify the topology ID and matching authoring assembly.
• Check duplicate coordinates and stable non-empty IDs.
• Check structure footprints, occupancy layers, initial placements, policy profiles, and resolver profiles.
• After fixing serialized data, rebuild. A previous failed report does not update itself.

Use Diagnose Grid Toolkit workflows to identify which report or status owns the failure.

Preview succeeds but apply fails

Preview does not reserve the board. A GridActionRunner can build a fresh plan or consume an existing one:

Call	Planning behavior
GridActionRunner.Preview(state, action)	Builds and validates a plan without mutation.
GridActionRunner.Apply(state, action)	Builds a fresh plan, so its result may differ if state changed after Preview.
GridActionRunner.Apply(state, existingPlan)	Uses the supplied plan and rejects it when its source revision is stale.

Re-evaluate the request against current state. Do not bypass the revision check.

See Actions, transactions, and events for the plan lifecycle and stale-plan boundary.

A rejected action changed state

This violates the atomic action contract. Capture the action, preview/result, starting and ending revision, committed event batches, and a minimal reproduction using public APIs. Confirm the change did not come from project code mutating an owned object directly, then contact support.

Revision or event counts differ

Start with the authoritative successful-outcome table. These outcomes have different revision and event behavior:

• an event-only plan publishes a batch without advancing revision;
• a multi-board operation advances only boards that mutate;
• every successful snapshot restoration advances revision once, even if the saved and live values already match.

Preview, rejection, rollback, and a successful request with no mutation or event publish no batch and advance no revision.

Snapshot creation or restore fails

• Register every extension resolver used by the payload.
• Keep IDs stable and compare the game's save schema version.
• Select the unknown-payload policy deliberately.
• Validate topology, definitions, occupancy, and extension payloads before apply.
• Never partially restore around a failure.
• Discard or explicitly migrate pre-1.0 snapshots.

See Save and restore state for resolver setup and the full restore sequence.

The board is correct but visuals are missing

1. Confirm GridBoardView has a ready state source, one renderer, and a topology-compatible layout.
2. Check the configured node builders, renderer modules, visual library, capabilities, and readiness messages.
3. Confirm the view produces the expected render nodes. If it does, board synchronization is working; inspect only the scene or Canvas presentation that consumes those nodes.
4. Force a diagnostic refresh only to identify invalidation problems; do not use a per-frame full rebuild as the fix.

See Connect a board view to state and Configure a World 2D or World 3D renderer.

Hits resolve incorrectly

Use the hit resolver associated with the active renderer. Confirm its camera, physics mode, raycaster, hit surface, and layout.

Resolver path	Candidate behavior
World 2D or World 3D	Chooses the nearest hit with deterministic tie-breaking.
Multi-view uGUI helper	Returns the first view in the supplied order that produces a hit.

Built-in results are Hit, Miss, or Unhandled. If the game must reject overlapping targets, compare candidates in project code before accepting one.

See Resolve board hits for the renderer-specific result paths.

Inventory or Cell Metadata behaves inconsistently

Both modules use ordinary actions, extensions, and resolvers:

• For Inventory, verify the item definition and instance extensions. A transfer between boards must use the multi-board operation. Start with Understand Inventory.
• For Cell Metadata, verify the state extension and any policy that reads it. See Learn the extension pattern with Cell Metadata.

Then diagnose the same action, persistence, or presentation boundary used elsewhere in Grid Toolkit.

Editor behavior duplicates after script reload

Check whether a project-owned initializer registered the same callback more than once. Make that registration idempotent, unregister owned callbacks, reselect affected assets, and rebuild their previews or state. See the editor workflow.

If these checks do not isolate the problem, prepare the evidence listed under Contact support.