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
- Drop a
TGorillaPathfindingAStar(or custom algorithm) onto your viewport - Set the
Agentproperty to the character/NPC that needs to navigate - 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
OnUpdateevent 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