Pathfinding

Gorilla3D includes a grid-based pathfinding system with an A* algorithm implementation. The system supports static and dynamic obstacles, configurable obstacle margins, and integrates with the 3D scene for navigation of characters and NPCs.

Table of Contents

Overview

Class Description
TGorillaPathfindingAlgorithm Abstract base for pathfinding algorithms (obstacle and agent management)
TGorillaPathfindingAStar A* pathfinding implementation (in Gorilla.Utils.Pathfinding.AStar)

Getting Started

Design-Time

  1. Drop a TGorillaPathfindingAStar (or custom algorithm) onto your viewport
  2. Set the Agent property to the character/NPC that needs to navigate
  3. Add obstacles via code

Runtime

uses Gorilla.Utils.Pathfinding, Gorilla.Utils.Pathfinding.AStar;

var
  Pathfinder: TGorillaPathfindingAStar;
begin
  Pathfinder := TGorillaPathfindingAStar.Create(Self);
  Pathfinder.Parent := GorillaViewport1;
  Pathfinder.Agent := CharacterModel;
end;

Obstacles

Obstacles are 3D controls that block pathfinding. Each obstacle has a bounding box and can be static (optimized) or dynamic (recalculated each query).

Adding Obstacles

// Static obstacle (never moves - better performance)
Pathfinder.AddObstacle(WallMesh, True);

// Dynamic obstacle (moves at runtime)
Pathfinder.AddObstacle(MovingPlatform, False);

// With explicit bounding box
Pathfinder.AddObstacle(SomeObject, CustomBounds, True);

Managing Obstacles

// Remove a specific obstacle
Pathfinder.RemoveObstacle(WallMesh);

// Remove all obstacles
Pathfinder.ClearObstacles();

// Reset computed grid rectangles (force recalculation)
Pathfinder.ResetObstacles();

// Get obstacle count
var Count := Pathfinder.CountObstacles();

Obstacle Margin

Add a buffer zone around obstacles to prevent the agent from clipping:

Pathfinder.ObstacleMargin := Point3D(0.5, 0, 0.5); // half-unit margin on X and Z

Obstacle Properties

Field Type Description
Control TControl3D The visual component acting as obstacle
IsStatic Boolean If true, bounding box is computed once
Bounds TBoundingBox Current bounding box
Computed Boolean Whether grid rect has been calculated
GridRect TRectF Computed grid coordinates

Custom Obstacle Bounds

Use the OnUpdate event to provide custom bounding boxes:

Pathfinder.OnUpdate := procedure(const AControl: TControl3D; out ABounds: TBoundingBox)
begin
  // Return custom bounds for this obstacle
  ABounds.Min := Point3D(-1, 0, -1);
  ABounds.Max := Point3D(1, 2, 1);
end;

A* Algorithm

The A* implementation (Gorilla.Utils.Pathfinding.AStar) extends the base algorithm with grid-based pathfinding. It finds the shortest path from the agent's position to a target while avoiding obstacles.

Finding Paths

// The pathfinder uses the Agent property to determine the start position
var AgentPos := Pathfinder.AgentPosition; // returns (0,0,0) if no agent set

Best Practices

  • Prefer static obstacles whenever possible — they only compute their grid rect once
  • Set appropriate ObstacleMargin to prevent the agent from walking too close to walls
  • Call ResetObstacles() when the scene layout changes significantly
  • Use the OnUpdate event for obstacles with complex shapes that need custom bounding boxes
  • For large scenes, only add nearby obstacles to the pathfinder to improve performance
  • Combine pathfinding with the character controller for smooth NPC movement