Grid Builder API

Overview

The GridBuilder is the core component for managing pathfinding grids in JPS4. It handles grid creation, collision detection, and serves as the primary interface for requesting paths.

Recommended Workflow

1. Configure cellSize, gridSize, and collisionSettings in the Inspector
2. Call Build() or use the Inspector button
3. Verify the grid's world-space positioning with showGizmos = true
4. Request paths using the Path Requests API

Grid Builder

PathfindingGridBuilder

The primary grid manager object for storing collision data and generating paths.

Key Concepts

• Grid Position: 2D discrete coordinates where bottom-left = (0,0)
• World Position: 3D continuous positions in the Unity scene
• Static Collision: Unchanging obstacles cached during Build()
• Dynamic Collision: Runtime obstacles that can be added/removed

---

Configuration

Inspector Properties

Property	Description
enableDebug	Track additional debug information from every path request
showGizmos	Display gizmos for the grid definition in the scene view
cellSize	Side length in world units of a grid tile
gridSize	Dimensions in tiles for the grid (width, height)
collisionSettings	Collision configuration for detecting static obstacles
pathingAlgorithm	Which algorithm to use for pathfinding
allowCutCorners	For A* 8-connected, can agents move diagonally between blocking obstacles?
maxConcurrentJobs	Maximum number of path jobs that can run simultaneously

Collision Settings

public struct CollisionSettings
{
    public float VerticalOffset;        // Distance to offset before casting collision ray
    public LayerMask CollisionMask;     // What layers count as obstacles
    public ECollisionType CollisionType; // Type of ray-casting (2D/3D/Custom)
}

Collision Types

public enum ECollisionType
{
    Collider2D,  // Use Raycast2D per cell
    Collider3D,  // Use Raycast3D per cell
    Custom       // Manually supplied collision data
}

---

Building the Grid

Build Behavior

• Creates a new TileGrid object with static collision data
• Cancels all pending and active path jobs
• Can be called multiple times to rebuild collision
• Uses raycasting based on CollisionSettings

Custom Collision

If using ECollisionType.Custom, use the TryBuildExternal() overloads instead.

Build()

Build the static collision grid using the configured collision settings.

[Button("Build")]
public void Build()

---

TryBuildExternal()

Build collision from an external source with custom collision data.

With Grid SizeCurrent Grid Size

public bool TryBuildExternal( NativeArray<bool> gridTraversableIn, int2 gridSizeIn  )

public bool TryBuildExternal( NativeArray<bool> gridTraversableIn )

Parameters:

• gridTraversableIn: Static collision matrix where true = walkable, false = obstacle
• gridSizeIn: Size of the incoming collision matrix (optional, uses current gridSize if omitted)

Returns: true if configuration is valid and a new TileGrid was created

Memory Management

The input array is copied internally, so remember to dispose it! This can be a temporary allocation too since it happens immediately.

---

Properties

Grid Information

public TileGrid Grid { get; }              // The underlying tile grid data
public bool IsBuilt { get; }               // True if grid has been built
public float CellSize { get; }             // World size of each grid cell
public Vector3 GridCenter { get; }         // World position of grid center
public Vector3 LocalLeftCorner { get; }    // Local position of bottom-left corner

Debugging

public List<JPSDebugStep> LastJPSDebugSteps { get; }  // Debug info from last path
public bool IsDebuggingEnabled { get; }               // Is debug tracking enabled?

---

Helpers

GetWorldPosition()

Convert a 2D grid position to a 3D world position.

public Vector3 GetWorldPosition(int2 gridPosition)

---

GetGridPosition()

Convert a 3D world position to a 2D grid position.

public int2 GetGridPosition(Vector3 worldPosition)

Bounds Checking

The result is automatically clamped to valid grid bounds.

---

TileGrid

The underlying data structure storing collision information.

public class TileGrid : IDisposable
{
    public readonly int2 Size;
    public NativeArray<bool> StaticTraversable;   // Static walkability
    public NativeArray<bool> DynamicBlocked;      // Runtime obstacles
    public NativeArray<bool> EmptyMatrix;         // Helper for disabling dynamic

    public int IDX(int2 tile);                    // Convert 2D position to 1D index
    public bool IsTraversable(int2 tile);         // Check if tile is walkable
    public bool IsDynamicBlocked(int2 tile);      // Check if dynamically blocked
    public void SetStaticTraversable(int x, int y, bool isTraversable);
    public void SetDynamicBlocked(int x, int y, bool isBlocked);
}