Skip to content
Grid Building Docs

Grid Targeting

Overview of the Grid Targeting subsystem and how cursor positions map to grid coordinates.

This page introduces the Grid Targeting subsystem used by the building workflow and explains how mouse/viewport positions become snapped grid coordinates other systems can use.

What it does

Section titled “What it does”

Grid Targeting is responsible for turning pointer input into a stable, snapped target that the building and validation pipelines can consume.

  • Convert viewport/world coordinates to grid-space
  • Apply snapping rules (cell, edge, corner) and epsilon filtering to avoid flicker at boundaries
  • Expose the current target info for other systems (validation, indicators, placement)

See also: Building System Process

Data flow

Section titled “Data flow”
  1. Input is sampled from the active viewport (mouse/touch position)
  2. GridTargetingSystem computes a target using GridPositioner2D and settings from GridTargetingSettings
  3. Resulting target info is stored in GridTargetingState
  4. Downstream systems consume it:
    • Indicators highlight the hovered cell(s)
    • Placement validation evaluates rules against the target
    • Building system uses it to place or preview objects

Position calculation basics

Section titled “Position calculation basics”
  • World position → grid coords: sampling the world-space cursor and converting to integer cell coordinates based on configured cell size/origin.
  • Snapping modes: center-of-cell, edge-aligned, or corner-snapping depending on your chosen settings.
  • Epsilon filtering: small movement within a cell won’t constantly resignal target changes; this prevents UI flicker.

Consuming the current target

Section titled “Consuming the current target”

Most systems don’t compute targeting directly—they read it from state or receive updates.

  • Poll model/state: read the latest target info from GridTargetingState
  • Event-driven: connect to target update signals emitted by your coordination layer
  • Render-time: indicators query the state and render highlights for hovered cells

Typical consumers:

Configuration

Section titled “Configuration”

Use GridTargetingSettings to control:

  • Cell size and origin
  • Snapping mode and tolerance (epsilon)
  • Edge/corner behavior for non-centered snapping

These settings are typically provided via your composition container and shared with the GridPositioner2D.

Debugging and validation

Section titled “Debugging and validation”
  • Visualize: enable an indicator layer to color the active cell and neighbors.
  • Inspect text: add GridTargetingDebugText to render current cell, world pos, and snap mode.
  • Validate: run your rule set through PlacementValidator using the current target to confirm expected acceptance/rejection.
Section titled “Related reading”