IntermediateValidated 1.0.0

Resolve board hits

When to use

Resolve a board hit when pointer, touch, ray, or world-position input must identify a logical cell or structure. The renderer reports what was hit; game code decides whether that target means hover, selection, placement, movement, or another action.

Before you start

Connect a ready GridBoardView to one renderer. Choose strict geometry when input must remain inside the cell polygon, or nearest-cell resolution when proximity is acceptable. Physical hit surfaces are optional.

Procedure

1. Choose the input path

For World 2D or World 3D, pass a ray or point to GridBoardView.ResolveHit.
For a Canvas, pass the pointer position and view to GridUiBoardHitUtility. The assigned uGUI renderer owns the screen-to-board mapping.

2. Interpret the result

Inspect the returned GridHit. Its kind and IDs distinguish a cell from a structure. Then inspect the resolution status:

Status	Meaning
`Hit`	The result contains a logical target.
`Miss`	This means the renderer handled the query but found nothing.
`Unhandled`	This means that renderer cannot process the query.

Treat Miss and Unhandled as no target. Do not infer a logical target from transform names or hierarchy.

Excerpt — resolve one world-space ray. Tested using public APIs.

public static bool TryResolveWorldHit(
    GridBoardView boardView,
    Ray worldRay,
    out GridHit hit)
{
    if (boardView == null)
        throw new ArgumentNullException(nameof(boardView));

    return boardView.ResolveHit(worldRay, out hit) && hit.HasHit;
}

3. Choose how candidates are resolved

LayoutOnly uses topology geometry. RegisteredSurfacesFirst checks registered physical surfaces before falling back according to the selected options. Resolution traces are diagnostic evidence; they are not gameplay state.

World-space physical surfaces choose the nearest valid hit. Equal distances use a deterministic surface-key tie-break. The multi-view uGUI helper checks views in the supplied order and returns the first view that produces a hit. If your game must reject overlapping candidates, resolve and compare those candidates in project code before accepting a target.

Result

A successful query returns a logical coordinate and, when appropriate, a structure instance ID. No board revision or event is produced because hit resolution is read-only.

Troubleshooting

Symptom	Check
Every query misses	Confirm the view and renderer are ready and use the camera or coordinate space expected by the backend.
Decorative UI receives the pointer	Disable unnecessary raycast targets or resolve through the renderer mapping.
Overlapping candidates should be rejected by the game	Resolve the relevant candidates explicitly and apply the project's ambiguity rule before accepting one.
Layout and physical hits disagree	Inspect the resolution options and trace before changing gameplay logic.

Table of Contents