Table of Contents

Class NavSteering

Namespace
Trailblazer.Navigation.Steering
Assembly
Trailblazer.dll

Handles agent steering and path navigation logic by coordinating pathfinding, movement, and group behaviors within a lockstep simulation. Supports both direct line-of-sight travel and graph-backed A* or flow-field guidance.

public class NavSteering : IRecordable
Inheritance
NavSteering
Implements
IRecordable
Inherited Members

Constructors

NavSteering(TrailblazerWorldContext)

Initializes a new context-bound NavSteering instance.

public NavSteering(TrailblazerWorldContext context)

Parameters

context TrailblazerWorldContext

Fields

AvoidFactor

How far to look for obstacles to avoid.

public Fixed64 AvoidFactor

Field Value

Fixed64

BehaviorWeights

Weights for separating, aligning, and cohesion in group behavior. Avoidance weight is baked in here as well.

public GroupBehaviorWeights BehaviorWeights

Field Value

GroupBehaviorWeights

BrakingPower

Friction-based deceleration rate used when slowing down on ground surfaces.

public Fixed64 BrakingPower

Field Value

Fixed64

CanMove

Whether this agent can currently move.

public bool CanMove

Field Value

bool

CanPathfind

Disable if a unit never needs graph-guide validation or repathing.

public bool CanPathfind

Field Value

bool

DefaultAvoidFactor

Default padding radius used to maintain space between nearby agents.

protected static readonly Fixed64 DefaultAvoidFactor

Field Value

Fixed64

DefaultBehaviorWeights

Default weights used for group-based steering calculations (separation, alignment, cohesion).

protected static readonly GroupBehaviorWeights DefaultBehaviorWeights

Field Value

GroupBehaviorWeights

DefaultBrakingPower

Default braking factor applied when decelerating or stopping motion.

public static readonly Fixed64 DefaultBrakingPower

Field Value

Fixed64

DefaultGroupFactor

Default range to scan for other agents when calculating steering behaviors.

protected static readonly Fixed64 DefaultGroupFactor

Field Value

Fixed64

DefaultPathRecheckCooldown

Number of frames between pathfinding LOS rechecks.

protected const int DefaultPathRecheckCooldown = 16

Field Value

int

DefaultWaypointTolerance

Default world-space tolerance used when advancing between ordinary guide steps.

public static readonly Fixed64 DefaultWaypointTolerance

Field Value

Fixed64

GroupFactor

How far to look for group neighbors (separation/alignment/cohesion).

public Fixed64 GroupFactor

Field Value

Fixed64

PathRecheckCooldownFrames

Number of frames between pathfinding LOS rechecks.

public int PathRecheckCooldownFrames

Field Value

int

StuckRepathTries

Maximum number of repath attempts before declaring the agent fully stuck.

protected const int StuckRepathTries = 4

Field Value

int

_autoStopFrameCount

Internal cooldown before the agent can automatically stop again (used for bursty movement).

protected int _autoStopFrameCount

Field Value

int

_destination

The final destination this agent is attempting to reach.

protected Vector3d _destination

Field Value

Vector3d

_distanceToTarget

How far we move each update

protected Fixed64 _distanceToTarget

Field Value

Fixed64

_hasLineOfSightPath

True if the agent can reach the destination without requiring a path.

protected bool _hasLineOfSightPath

Field Value

bool

_isAtDestination

Has this unit arrived at destination?

protected bool _isAtDestination

Field Value

bool

_isStuck

Whether the agent has become stuck and exhausted repathing attempts.

protected bool _isStuck

Field Value

bool

_lastTargetDirection

Gets the direction vector of the most recent target interaction.

protected Vector3d _lastTargetDirection

Field Value

Vector3d

_pathCheckCooldown

Represents the cooldown period, in milliseconds, before the next path check can be performed.

protected int _pathCheckCooldown

Field Value

int

_repathTries

Number of attempts to repath after getting stuck.

protected int _repathTries

Field Value

int

_shouldMove

Whether the object is following a path or guide to the destination.

protected bool _shouldMove

Field Value

bool

_shouldRequestPathThisFrame

Current pathfinding search status.

protected bool _shouldRequestPathThisFrame

Field Value

bool

_stoppedFrameCount

Number of consecutive frames where movement failed and deceleration is occurring.

protected int _stoppedFrameCount

Field Value

int

_stuckFrameCount

Number of frames the agent has failed movement checks (used for stuck detection).

protected int _stuckFrameCount

Field Value

int

_targetDirection

Gets the current target direction as a three-dimensional vector.

protected Vector3d _targetDirection

Field Value

Vector3d

Properties

CanAutoStop

Indicates whether the agent is currently eligible for automatic stopping logic.

public bool CanAutoStop { get; }

Property Value

bool

CurrentQuery 

public PathQuery? CurrentQuery { get; }

Property Value

PathQuery?

Destination

The final destination this agent is attempting to reach.

public Vector3d Destination { get; }

Property Value

Vector3d

DistanceToTarget

How far we move each update

public Fixed64 DistanceToTarget { get; }

Property Value

Fixed64

Events

Container for delegate events that fire on pathfinding state changes (start, stop, arrive).

public NavSteeringEvents Events { get; protected set; }

Property Value

NavSteeringEvents

HasLineOfSightPath

True if the agent can reach the destination without requiring a path.

public bool HasLineOfSightPath { get; }

Property Value

bool

HasNavigationGuidance

Indicates whether the agent is actively following an A* or Flow guide.

public bool HasNavigationGuidance { get; }

Property Value

bool

IsAtDestination

Has this unit arrived at destination?

public bool IsAtDestination { get; }

Property Value

bool

IsInGroup

Gets a value indicating whether the item is assigned to a movement group.

public bool IsInGroup { get; }

Property Value

bool

IsStuck

Whether the agent has become stuck and exhausted repathing attempts.

public bool IsStuck { get; }

Property Value

bool

LastTargetDirection

Gets the direction vector of the most recent target interaction.

public Vector3d LastTargetDirection { get; }

Property Value

Vector3d

MovementGroupID

Gets or sets the unique identifier for the movement group associated with the current session.

public int MovementGroupID { get; set; }

Property Value

int

ShouldMove

Whether the object is following a path or guide to the destination.

public bool ShouldMove { get; }

Property Value

bool

TargetDirection

Gets the current target direction as a three-dimensional vector.

public Vector3d TargetDirection { get; }

Property Value

Vector3d

WaypointTolerance

Gets or sets the non-negative world-space tolerance used for ordinary guide steps.

public Fixed64 WaypointTolerance { get; set; }

Property Value

Fixed64

Methods

AddToMovementGroup(int)

Assigns this steering session to a movement group.

public void AddToMovementGroup(int groupId)

Parameters

groupId int

A non-negative group identifier. Negative values remove the current group assignment.

Arrive()

Triggers the arrival event and resets internal movement tracking.

public void Arrive()

BindContext(TrailblazerWorldContext)

Binds this steering controller to a world context.

public void BindContext(TrailblazerWorldContext context)

Parameters

context TrailblazerWorldContext

CheckStuckStatus(Vector3d, Fixed64, Fixed64)

Evaluates the agent's current movement direction and velocity, updating stuck and arrival state.

protected virtual bool CheckStuckStatus(Vector3d position, Fixed64 speed, Fixed64 stuckThreshold)

Parameters

position Vector3d
speed Fixed64
stuckThreshold Fixed64

Returns

bool

ComputeCombinedSteering(Vector3d, Vector3d, Fixed64, Fixed64, Guid)

Computes a combined steering vector— Separation, Alignment, Cohesion, plus single-nearest obstacle avoidance.

public Vector3d ComputeCombinedSteering(Vector3d position, Vector3d velocity, Fixed64 speed, Fixed64 radius, Guid id)

Parameters

position Vector3d
velocity Vector3d
speed Fixed64
radius Fixed64
id Guid

Returns

Vector3d

FindTargetDirection(Vector3d, out NavigationTransitionInstruction?)

Computes the steering direction toward the destination or along the path.

protected virtual Vector3d FindTargetDirection(Vector3d position, out NavigationTransitionInstruction? pendingTransition)

Parameters

position Vector3d
pendingTransition NavigationTransitionInstruction?

Returns

Vector3d

GetHeading(ISteer, out NavigationTransitionInstruction?)

Called every simulation step to handle agent steering and movement logic.

public virtual Vector3d GetHeading(ISteer vessel, out NavigationTransitionInstruction? pendingTransition)

Parameters

vessel ISteer
pendingTransition NavigationTransitionInstruction?

Returns

Vector3d

LeaveMovementGroup()

Removes this steering session from its current movement group.

public void LeaveMovementGroup()

OnInitialize()

Initializes the object by setting up its defaults, events, traversal state, and movement controller.

protected virtual void OnInitialize()

PauseAutoStop()

Applies a short delay to prevent auto-stopping behavior for a few frames.

public void PauseAutoStop()

PrewarmMovementGroup(ISteer)

Rebuilds this steering session's shared movement-group membership from the current runtime owner state.

public void PrewarmMovementGroup(ISteer vessel)

Parameters

vessel ISteer

The current steering owner whose position, radius, and stable id should seed the coordinator.

Remarks

Call this after loading multiple grouped steering sessions when you want the coordinator warmed before the next simulation frame. If it is skipped, grouped steering will still recover lazily during GetHeading(ISteer, out NavigationTransitionInstruction?).

RecordData(IChronicler)

Records the current instance state to the provided chronicler.

public virtual void RecordData(IChronicler chronicler)

Parameters

chronicler IChronicler

The active chronicler pass.

SetDeceleration(Vector3d, Fixed64)

Adjusts the target direction to decelerate the object as it approaches its destination based on the specified acceleration and current speed.

protected virtual void SetDeceleration(Vector3d acceleration, Fixed64 speed)

Parameters

acceleration Vector3d

The acceleration vector used to determine the deceleration rate. If the vector is zero, a default braking power is used.

speed Fixed64

The current speed of the object, used to calculate the distance required to slow down.

Remarks

This method is intended to be overridden in derived classes to customize deceleration behavior. It modulates the target direction to ensure smooth slowing as the object nears its target.

ShouldAdvanceToNextWaypoint()

Returns true if the agent passed a step within its arrival radius, or entered the explicit ordinary-step tolerance.

public bool ShouldAdvanceToNextWaypoint()

Returns

bool

StopMove()

Resets the movement and pathfinding logic, halting the agent.

public virtual void StopMove()

ValidateMovementPath(Vector3d)

Periodically called to initiate a pathfinding query based on the current position and destination. Note: This runs once on the next simulation after a guided trek request is applied.

protected virtual bool ValidateMovementPath(Vector3d origin)

Parameters

origin Vector3d

Returns

bool
Edit this page