Pathfinding

advanced scripting

Class: Path request methods on this page belong to VoxelPlayEnvironment. Access via VoxelPlayEnvironment.instance.

Requesting paths

VoxelPathRequest FindPath(Vector3d start, Vector3d end, VoxelPathOptions options = default, Action<VoxelPathRequest> onComplete = null)

Requests a path between two positions, resolved asynchronously on worker threads. The callback always fires on the main thread. Waypoints are voxel cell centers at feet level; agents add their own half height.

start: Path origin (feet position).
end: Path destination.
options: Optional search parameters (see VoxelPathOptions below).
onComplete: Invoked on the main thread when the request resolves.

void ReleasePathRequest(VoxelPathRequest request)

Returns a request to the internal pool. Call it when the request and its path are no longer referenced to avoid allocations.

bool IsPathStillValid(VoxelPathRequest request)

Returns false when any chunk crossed by the path corridor changed, unloaded or newly appeared since the path was computed. Agents typically re-request the path when this returns false.

Environment properties

int pathfindingThreads

Number of worker threads. 0 = automatic based on processor count.

int pathfindingMaxSearchNodes

Maximum cells explored per search before returning a partial path (default 6000).

int pathfindingCallbackBudgetMs

Milliseconds per frame spent delivering completed path callbacks (default 2).

int pathfindingDefaultWadeDepth

Fluid cells deep agents wade through by default, counted from the feet (default 1). Requests and agents can override it; the head always stays out of the fluid.

int pathfindingPendingCount

Number of path requests currently queued or computing.

VoxelPathRequest

VoxelPathStatus status

Idle, Queued, Computing, Ready, Failed or Canceled.

List<Vector3d> path

Resulting waypoints: voxel cell centers at feet level.

bool isPartial

True when the search hit its node budget or an unreachable target and the path leads to the closest reachable cell instead.

void Cancel()

Cancels the request; if it is already computing, the result is discarded and no callback fires.

VoxelPathOptions

int maxDrop

Maximum fall height per step (0 = default, 3).

int maxSearchNodes

Per-request override of the environment default (0 = use default).

int agentHeight

Vertical clearance in voxels required by the agent (0 = default, 2).

int maxSnapDown

Distance scanned below start and end to find the ground (0 = default, 4).

FluidTraversal fluidTraversal

How the search treats fluids: UseEnvironmentDefault wades up to the environment default depth, Forbidden never enters fluid cells, Wade uses maxWadeDepth.

int maxWadeDepth

Wade mode only: fluid cells tolerated from the feet up (0 = environment default). Always capped to agentHeight - 1 so the head stays out.

bool noDiagonals

Restricts movement to the four cardinal directions.

bool noPartialPaths

Fail instead of returning a partial path when the target is unreachable.

float crowdAvoidance

Extra cost per agent occupying a cell (0 = default 1, negative = disabled). Requires agents publishing their cells, which VoxelPlayPathAgent does automatically.

VoxelPlayPathAgent component

Transform target

Transform the agent chases. Leave empty and call SetDestination for fixed goals.

void SetDestination(Vector3 destination)

Sends the agent to a fixed position. Overrides the chase until ClearDestination is called.

void ClearDestination()

Cancels a SetDestination order; the agent resumes chasing its target, if any.

void AddKnockback(Vector3 velocity)

Applies a horizontal shove. The agent slides with the usual movement rules (stops at walls and forbidden fluids, can fall off ledges) and transfers part of the momentum to agents it rams.

bool hasPath

True while the agent has waypoints left to follow.

static IReadOnlyList<VoxelPlayPathAgent> ActiveAgents

All enabled path agents, for custom queries (shoves, selections, effects).

float speed, turnSpeed, stoppingDistance, heightOffset; int maxDrop, agentHeight

Movement tuning: walking and turning speed, stop distance to the target, pivot height above the feet, tallest accepted drop and vertical clearance in voxels (path searches use the same height).

float repathInterval, targetMoveRepathDistance, stuckRepathTime

Repath tuning. Agents stagger their checks automatically so large crowds never recompute on the same frame; stuck agents force a new path after some seconds without progress.

FluidTraversal fluidTraversal; int maxWadeDepth

Fluid behavior for both path searches and movement: wade using the world default depth, never enter fluids, or wade down to maxWadeDepth cells.

float detectionRange, loseTargetDistance, loseSightTime; bool requireLineOfSight, returnHome

Optional perception, all off by default (the agent always knows where its target is): acquire targets only within detectionRange, require an unobstructed voxel line of sight to start or keep the chase, give up beyond loseTargetDistance or after loseSightTime seconds hidden, and optionally walk back to the spawn point.

bool separation; float separationRadius, separationStrength

Crowd separation: agents softly push each other apart through a shared spatial grid, with no physics involved. Pushes that would enter a solid column or forbidden fluid are discarded. Scales to thousands of agents.

float crowdAvoidance

Extra path cost per agent standing on a cell. New searches route around crowded corridors when an alternative exists. Negative disables it.

bool blockedByColliders; float colliderStepHeight

Scene colliders (props, debris, the player) block movement; colliders reaching no higher than colliderStepHeight above the feet (carpets, pressure plates) are walked over instead. The voxel terrain itself is always handled by the grid rules.

float knockbackDeceleration, knockbackTransfer

How quickly a shove loses speed, and how much of it passes on to agents rammed along the way (chain effect).

bool debugTraces

Prints repaths, blocked moves and stuck warnings for this agent to the console.

Voxel definition

float pathfindCost

Native pathfinding cost, editable in the inspector for terrain voxels, fluids and custom voxels. Ground: 1 = normal, higher = avoided, below 1 = preferred, 0 = impassable. Fluids: wading penalty, 0 = agents never enter (bundled lavas ship with 0). Custom voxels: crossing penalty, 0 = blocks agents.

Examples

Asynchronous path request with a callback:

using VoxelPlay;

VoxelPlayEnvironment env = VoxelPlayEnvironment.instance;

env.FindPath(transform.position, targetPosition, default, request => {
    if (request.status == VoxelPathStatus.Ready) {
        foreach (Vector3d waypoint in request.path) {
            // feed waypoints to your character movement
        }
    }
    env.ReleasePathRequest(request);
});

Spawning a chasing agent entirely from code:

GameObject mob = GameObject.CreatePrimitive(PrimitiveType.Capsule);
Destroy(mob.GetComponent<Collider>()); // agents move kinematically, no physics needed
mob.transform.position = spawnPosition;

VoxelPlayPathAgent agent = mob.AddComponent<VoxelPlayPathAgent>();
agent.target = player;   // chases the player and repaths automatically
agent.speed = 4f;
agent.maxDrop = 3;       // accepts drops of up to 3 voxels

// or send it to a fixed destination instead:
agent.SetDestination(new Vector3(120, 60, -40));
agent.ClearDestination(); // back to chasing the target

// arrival check
if (!agent.hasPath) {
    // no path yet or already arrived
}

Per-voxel walk costs, editable in the inspector or from code:

VoxelDefinition mud = env.GetVoxelDefinition("Mud");
mud.pathfindCost = 6f;   // agents prefer routes around mud

VoxelDefinition road = env.GetVoxelDefinition("StonePath");
road.pathfindCost = 0.5f; // agents favor walking on roads

VoxelDefinition lava = env.GetVoxelDefinition("VoxelLava");
lava.pathfindCost = 0f;  // impassable for agents

Fluids and perception:

// this agent never steps into water or lava
agent.fluidTraversal = FluidTraversal.Forbidden;

// a tall amphibious agent wading two cells of water
VoxelPathOptions options = new VoxelPathOptions {
    agentHeight = 3,
    fluidTraversal = FluidTraversal.Wade,
    maxWadeDepth = 2
};
env.FindPath(start, end, options, OnPathReady);

// guard dog: only reacts to targets it can actually see nearby, then returns to its post
agent.detectionRange = 15f;
agent.requireLineOfSight = true;
agent.loseTargetDistance = 30f;
agent.returnHome = true;

Was this page helpful? |