Table of Contents

Class Navigator

Namespace
Trailblazer.Navigation
Assembly
Trailblazer.dll

Base class for an object that owns movement, traversal state, and simulation flow.

public abstract class Navigator : INavigate, ISteer, IVoxelOccupant, IRecordable
Inheritance
Navigator
Implements
IVoxelOccupant
IRecordable
Inherited Members

Remarks

This class acts as a bridge between the simulation logic and the entity's external representation. It defines common traversal behaviors and lifecycle methods that can be extended by concrete implementations.

Constructors

Navigator()

Initializes a new unbound navigator. Bind it to a context before setup.

protected Navigator()

Navigator(TrailblazerWorldContext)

Initializes a new navigator bound to the supplied world context.

protected Navigator(TrailblazerWorldContext context)

Parameters

context TrailblazerWorldContext

Fields

_acceleration

The current acceleration vector of the object, updated each frame based on velocity change.

protected Vector3d _acceleration

Field Value

Vector3d

_frameCondition

Represents the traversal state of a scout, including its movement medium and surface interactions.

protected TrekCondition _frameCondition

Field Value

TrekCondition

_frameRequest

Represents a movement request for a object to pass to NavMotor, containing the current origin, foot position, rotation, direction, speed, and frame-owned locomotion intent.

protected TrekRequest _frameRequest

Field Value

TrekRequest

_globalId

Stable runtime identity used for occupancy and steering coordination.

protected Guid _globalId

Field Value

Guid

Remarks

By default this is allocated deterministically from object setup order. Hosts can override it during setup when a broader simulation stack already owns stable agent ids.

_isInitialized

Indicates whether the Navigator has been initialized.

protected bool _isInitialized

Field Value

bool

_isSet

Indicates whether the Navigator has been set.

protected bool _isSet

Field Value

bool

_lastPosition

The last world position of the object.

protected Vector3d _lastPosition

Field Value

Vector3d

_motor

The controller responsible for managing the object's movement and physics interactions.

protected NavMotor? _motor

Field Value

NavMotor

_position

The absolute world-space position of the occupant, representing its precise location in the environment.

protected Vector3d _position

Field Value

Vector3d

_positionDelta

The change in position to apply during the current simulation frame.

protected Vector3d _positionDelta

Field Value

Vector3d

_rotation

The object's visual rotation in world space.

protected FixedQuaternion _rotation

Field Value

FixedQuaternion

_rotationDelta

The change in rotation to apply during the current simulation frame.

protected FixedQuaternion _rotationDelta

Field Value

FixedQuaternion

_speed

The current movement speed, derived from the magnitude of the velocity.

protected Fixed64 _speed

Field Value

Fixed64

_steering

The controller responsible for managing the object's desired movement direction.

protected NavSteering? _steering

Field Value

NavSteering

_turning

The controller responsible for managing the object's rotation towards the movement direction.

protected NavTurning? _turning

Field Value

NavTurning

_velocity

The current velocity of the object in world space.

protected Vector3d _velocity

Field Value

Vector3d

_velocityDelta

The velocity change computed during the simulation frame.

protected Vector3d _velocityDelta

Field Value

Vector3d

Properties

Acceleration

The current acceleration vector of the object, updated each frame based on velocity change.

public Vector3d Acceleration { get; }

Property Value

Vector3d

BodyShape

Gets the authoritative body shape from NavigationProfile.

public KinematicBodyShape BodyShape { get; }

Property Value

KinematicBodyShape

Context

Gets the world context this navigator is bound to.

public TrailblazerWorldContext? Context { get; }

Property Value

TrailblazerWorldContext

FootPosition

Gets the derived world-space foot point used by navigation and locomotion.

public Vector3d FootPosition { get; }

Property Value

Vector3d

Forward

The direction the object is currently facing.

public Vector3d Forward { get; protected set; }

Property Value

Vector3d

GlobalId

Stable runtime identity used for occupancy and steering coordination.

public Guid GlobalId { get; }

Property Value

Guid

Remarks

By default this is allocated deterministically from object setup order. Hosts can override it during setup when a broader simulation stack already owns stable agent ids.

HeightmapGrounding

Gets the opt-in heightmap grounding settings owned by this navigator.

public NavigatorHeightmapGroundingSettings HeightmapGrounding { get; }

Property Value

NavigatorHeightmapGroundingSettings

IsActive

Indicates whether the Navigator is currently active and ready for simulation.

public bool IsActive { get; }

Property Value

bool

IsGuided

Indicates whether the current traversal session owns navigation guidance.

public bool IsGuided { get; }

Property Value

bool

IsLockedOn

Gets or sets a value indicating whether the object is currently locked on to a target.

public bool IsLockedOn { get; set; }

Property Value

bool

LastCommittedCell

Gets the effective navigation cell resolved after the latest motion commit.

public NavigationCommittedCellState? LastCommittedCell { get; }

Property Value

NavigationCommittedCellState?

LastPosition

The last world position of the object.

public Vector3d LastPosition { get; }

Property Value

Vector3d

Motor

The controller responsible for managing the object's movement and physics interactions.

public NavMotor? Motor { get; }

Property Value

NavMotor

NavigationProfile

Gets the exact immutable navigation profile supplied during setup.

public NavigationAgentProfile NavigationProfile { get; }

Property Value

NavigationAgentProfile

OccupantGroupId

The group Id used for grouping occupants within a scan cell. Occupants with the same group Id belong to the same logical group. This allows efficient retrieval of related occupants in spatial queries.

public byte OccupantGroupId { get; set; }

Property Value

byte

PendingTransition

Gets the exact transition action currently awaiting host completion.

public NavigationTransitionInstruction? PendingTransition { get; }

Property Value

NavigationTransitionInstruction?

Position

The absolute world-space position of the occupant, representing its precise location in the environment.

public Vector3d Position { get; }

Property Value

Vector3d

Radius

Body radius used for spatial checks.

public Fixed64 Radius { get; }

Property Value

Fixed64

Rotation

The object's visual rotation in world space.

public FixedQuaternion Rotation { get; }

Property Value

FixedQuaternion

Speed

The current movement speed, derived from the magnitude of the velocity.

public Fixed64 Speed { get; }

Property Value

Fixed64

Steering

The controller responsible for managing the object's desired movement direction.

public NavSteering? Steering { get; }

Property Value

NavSteering

StuckThresholdSpeed

Minimum velocity threshold used to determine if the object is considered stuck.

public Fixed64 StuckThresholdSpeed { get; }

Property Value

Fixed64

Turning

The controller responsible for managing the object's rotation towards the movement direction.

public NavTurning? Turning { get; }

Property Value

NavTurning

Velocity

The current velocity of the object in world space.

public Vector3d Velocity { get; }

Property Value

Vector3d

Methods

Activate(TrekCondition, Vector3d, NavigationAgentProfile, FixedQuaternion?, Vector3d?, Guid?)

Initializes and activates the object with the specified condition, position, and optional parameters.

public virtual void Activate(TrekCondition condition, Vector3d position, NavigationAgentProfile navigationProfile, FixedQuaternion? rotation = null, Vector3d? velocity = null, Guid? globalId = null)

Parameters

condition TrekCondition

The condition that determines how the object is initialized and activated.

position Vector3d

The position in world coordinates where the object will be placed.

navigationProfile NavigationAgentProfile

The exact body geometry and traversal capabilities owned by the object.

rotation FixedQuaternion?

The optional rotation to apply to the object. If null, a default rotation is used.

velocity Vector3d?

The optional initial velocity of the object. If null, the object is initialized with zero velocity.

globalId Guid?

The optional global identifier for the object. If null, a new identifier may be generated.

Activate(TrailblazerWorldContext, TrekCondition, Vector3d, NavigationAgentProfile, FixedQuaternion?, Vector3d?, Guid?)

Initializes and activates the object with the specified condition, position, and optional parameters.

public virtual void Activate(TrailblazerWorldContext context, TrekCondition condition, Vector3d position, NavigationAgentProfile navigationProfile, FixedQuaternion? rotation = null, Vector3d? velocity = null, Guid? globalId = null)

Parameters

context TrailblazerWorldContext

The world context that owns this navigator.

condition TrekCondition

The condition that determines how the object is initialized and activated.

position Vector3d

The position in world coordinates where the object will be placed.

navigationProfile NavigationAgentProfile

The exact body geometry and traversal capabilities owned by the object.

rotation FixedQuaternion?

The optional rotation to apply to the object. If null, a default rotation is used.

velocity Vector3d?

The optional initial velocity of the object. If null, the object is initialized with zero velocity.

globalId Guid?

The optional global identifier for the object. If null, a new identifier may be generated.

AddPositionDelta(Vector3d)

Applies a positional delta to the current position and updates the last known position accordingly.

public virtual void AddPositionDelta(Vector3d delta)

Parameters

delta Vector3d

The vector representing the positional change to apply. If the vector is FixedMathSharp.Vector3d.Zero, no change is made.

Remarks

This method adjusts both the current and last positions to maintain consistent velocity calculations. Use this method to apply external position changes without affecting velocity tracking.

AddVelocityDelta(Vector3d)

Adds the specified velocity change to the current velocity delta.

public virtual void AddVelocityDelta(Vector3d delta)

Parameters

delta Vector3d

The velocity change to add. If this value is FixedMathSharp.Vector3d.Zero, no change is applied.

ApplyGuidedTrekRequest(PathQuery, TrekRate?, bool?, bool?, bool?, bool?, bool, int)

Applies complete immutable graph-backed A* or flow-field intent.

public virtual void ApplyGuidedTrekRequest(PathQuery query, TrekRate? rate = null, bool? isRequestingFlight = null, bool? isRequestingSwim = null, bool? isRequestingClimb = null, bool? isRequestingJump = null, bool canAffordJump = true, int groupId = -1)

Parameters

query PathQuery

The exact query intent whose start point equals the current derived foot position.

rate TrekRate?

Desired movement rate.

isRequestingFlight bool?

Whether the object intends to fly or glide during traversal.

isRequestingSwim bool?

Whether the object intends to actively swim during traversal.

isRequestingClimb bool?

Whether the object explicitly intends to climb during traversal.

isRequestingJump bool?

Whether the object intends to jump during traversal.

canAffordJump bool

Frame-owned jump affordability answer for this request.

groupId int

Optional shared movement-group identifier.

Exceptions

ArgumentException

Thrown when the query does not match the Navigator's exact navigation profile.

ApplyInputTrekRequest(Vector3d?, TrekRate?, Vector3d?, bool?, bool?, bool?, bool?, bool)

Constructs and applies a traversal request using high-level navigation input values.

public virtual void ApplyInputTrekRequest(Vector3d? direction = null, TrekRate? rate = null, Vector3d? facingDirection = null, bool? isRequestingFlight = null, bool? isRequestingSwim = null, bool? isRequestingClimb = null, bool? isRequestingJump = null, bool canAffordJump = true)

Parameters

direction Vector3d?

Desired direction of travel.

rate TrekRate?

Rate of travel (walk, run, etc.).

facingDirection Vector3d?

Optional world-space facing direction to use instead of facing along the movement direction.

isRequestingFlight bool?

Whether the agent is requesting to fly or glide.

isRequestingSwim bool?

Whether the agent is requesting active swim control while in liquid.

isRequestingClimb bool?

Whether the agent is requesting to climb or maintain climb intent.

isRequestingJump bool?

Whether the agent is requesting a jump action.

canAffordJump bool

Frame-owned jump affordability answer for this request.

ApplyRotationDelta(FixedQuaternion)

Applies the specified rotation delta to the current rotation state.

public virtual void ApplyRotationDelta(FixedQuaternion delta)

Parameters

delta FixedQuaternion

The rotation delta to apply. Must not be FixedMathSharp.FixedQuaternion.Identity; otherwise, no change is made.

BindContext(TrailblazerWorldContext)

Binds this navigator to a world context before setup.

public virtual void BindContext(TrailblazerWorldContext context)

Parameters

context TrailblazerWorldContext

CheckTrekCondition()

Checks and updates the current traversal condition.

public abstract void CheckTrekCondition()

CheckVoxelOccupancy(bool)

Checks and updates the occupancy status of the current and previous voxels based on the object's position.

protected virtual void CheckVoxelOccupancy(bool init = false)

Parameters

init bool

Indicates whether the occupancy check is being performed during initialization. If set to true, the check is performed regardless of position changes.

Remarks

This method ensures that the object is registered as an occupant in the correct voxel and removed from the previous voxel if the position has changed. It should be called whenever the object's position may have changed to maintain accurate occupancy tracking.

CommitFrameMotion()

Finalizes traversal by updating movement calculations and applying corrections.

public virtual void CommitFrameMotion()

Remarks

Should be called once every rendering/player interfacing frame, after physics bodies apply velocity changes.

CompletePendingTransition(in NavigationTransitionInstruction)

Completes the exact pending semantic action owned by the active guide.

public virtual NavigationGuideStatus CompletePendingTransition(in NavigationTransitionInstruction instruction)

Parameters

instruction NavigationTransitionInstruction

Returns

NavigationGuideStatus

ConfigureHeightmapGrounding(HeightmapGroundingMode, string?, Fixed64?, Fixed64?)

Configures explicit heightmap grounding for concrete navigators that opt in during traversal checks.

public virtual void ConfigureHeightmapGrounding(HeightmapGroundingMode mode, string? layerName = null, Fixed64? groundOffset = null, Fixed64? snapTolerance = null)

Parameters

mode HeightmapGroundingMode

Heightmap grounding behavior to use when TryApplyHeightmapGrounding(bool, Fixed64?, MotionTransfer) is called.

layerName string

Optional initial layer preference used before an active layer is established.

groundOffset Fixed64?

Optional extra root offset above the sampled ground Y.

snapTolerance Fixed64?

Optional maximum root-Y correction allowed for positional projection.

CreateLocomotionProfile()

Creates the locomotion profile used when this object initializes its motor.

protected virtual LocomotionProfile CreateLocomotionProfile()

Returns

LocomotionProfile

Remarks

Override this to install a smaller or custom locomotion set per object type while preserving the default profile for callers that do not opt in.

GenerateGUID()

Generates a new globally unique identifier (GUID) for use in object identification or tracking.

protected virtual Guid GenerateGUID()

Returns

Guid

A new Guid value that is guaranteed to be unique across space and time.

Remarks

Override this method to customize GUID generation logic if a different strategy is required by derived classes.

Initialize(TrekCondition)

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

public virtual void Initialize(TrekCondition condition)

Parameters

condition TrekCondition

NotifyCollision()

Notifies the object that a collision occurred so collision-driven subsystem responses can run on the next simulation step.

public virtual void NotifyCollision()

PrewarmMovementGroup()

Prewarms the steering movement-group coordinator from this object's currently loaded state.

public virtual void PrewarmMovementGroup()

Remarks

This is primarily useful after loading several grouped navigators through Chronicler. Call it once for each loaded object before the next simulation frame if you want movement-group formation state available immediately. If it is skipped, grouped steering will still rejoin lazily on the next update.

RecordData(IChronicler)

Records the current instance state to the provided chronicler.

public virtual void RecordData(IChronicler chronicler)

Parameters

chronicler IChronicler

The active chronicler pass.

ReplaceTrekCondition(TrekCondition, bool)

Replaces the current traversal state with the given one.

public virtual void ReplaceTrekCondition(TrekCondition state, bool updateMotorState)

Parameters

state TrekCondition

The new traversal condition to apply.

updateMotorState bool

Flags whether or not to immediately sync the new traversal snapshot into the motor before the next traversal step.

Reset()

Resets the state of the object to its initial configuration, clearing any active conditions, requests, and internal flags.

public virtual void Reset()

Remarks

Call this method to reinitialize the object for reuse or to clear any ongoing operations. After calling this method, the object will be in the same state as after construction, and any previous state or intent will be lost. This method is intended to be overridden in derived classes to extend the reset behavior as needed.

SetAirborne(Fixed64?, GroundCondition?, Fixed64?, bool)

Updates the object to an airborne state while preserving the last known ground condition unless an override is provided.

public virtual void SetAirborne(Fixed64? surfaceLevel = null, GroundCondition? launchCondition = null, Fixed64? ceilingLevel = null, bool updateMotorState = false)

Parameters

surfaceLevel Fixed64?
launchCondition GroundCondition?
ceilingLevel Fixed64?
updateMotorState bool

SetFrameJumpAffordability(bool)

Sets the frame-owned jump affordability snapshot used by NavMotor on the next traversal step.

public virtual void SetFrameJumpAffordability(bool canAffordJump)

Parameters

canAffordJump bool

SetGroundContact(Fixed64, PlatformSnapshot, Fixed64?, MotionTransfer, Fixed64?, bool)

Updates the object to a grounded state using a host-provided platform snapshot plus surface settings. Inert snapshots still describe the contacted surface but opt out of moving-platform carry logic.

public virtual void SetGroundContact(Fixed64 surfaceLevel, PlatformSnapshot platform = default, Fixed64? surfaceFriction = null, MotionTransfer motionTransfer = MotionTransfer.None, Fixed64? ceilingLevel = null, bool updateMotorState = false)

Parameters

surfaceLevel Fixed64
platform PlatformSnapshot
surfaceFriction Fixed64?
motionTransfer MotionTransfer
ceilingLevel Fixed64?
updateMotorState bool

SetGuidedTrekRate(TrekRate)

Changes the speed at which the object is currently traveling without altering direction.

public virtual void SetGuidedTrekRate(TrekRate rate)

Parameters

rate TrekRate

New traversal rate to apply (walk, run, etc.).

SetTrekCondition(TraversalMedium?, Fixed64?, GroundCondition?, bool, Fixed64?, bool)

Updates the scout’s traversal state, including its current medium and surface information.

public virtual void SetTrekCondition(TraversalMedium? medium = null, Fixed64? surfaceLevel = null, GroundCondition? surfaceCondition = null, bool replaceGroundContact = true, Fixed64? ceilingLevel = null, bool updateMotorState = false)

Parameters

medium TraversalMedium?

The traversal medium (e.g., ground, air, water).

surfaceLevel Fixed64?

The vertical surface level, if applicable.

surfaceCondition GroundCondition?

The ground state data, if applicable.

replaceGroundContact bool

Whether to replace the current ground contact platform. This should be true when entering water or jumping off a platform, but false when maintaining contact with the same surface across frames.

ceilingLevel Fixed64?

The vertical ceiling level, if applicable.

updateMotorState bool

Flags whether or not to update the motor's internal surface state. Otherwise, it should be updated at the end of the frame.

Remarks

Make sure to update this before the next CommitFrameMotion() so FinalizeTraversal(Vector3d, Vector3d, FixedQuaternion, TrekCondition, Vector3d?) can update its state. If the motor must see the new snapshot before the next Simulate(), either pass updateMotorState as true or call SyncCurrentTrekConditionToMotor().

SetWaterContact(Fixed64, Fixed64?, bool)

Updates the object to a water-contact state and clears any grounded platform contact.

public virtual void SetWaterContact(Fixed64 surfaceLevel, Fixed64? ceilingLevel = null, bool updateMotorState = false)

Parameters

surfaceLevel Fixed64
ceilingLevel Fixed64?
updateMotorState bool

Setup(Vector3d, NavigationAgentProfile, FixedQuaternion?, Vector3d?, Guid?)

Sets the initial position, exact navigation profile, rotation, velocity, and optional stable identity.

public virtual void Setup(Vector3d position, NavigationAgentProfile navigationProfile, FixedQuaternion? rotation = null, Vector3d? velocity = null, Guid? globalId = null)

Parameters

position Vector3d

Initial world-space position.

navigationProfile NavigationAgentProfile

The exact body geometry and traversal capabilities owned by the object.

rotation FixedQuaternion?

Optional starting rotation.

velocity Vector3d?

Optional initial velocity.

globalId Guid?

Optional host-provided stable identity. When omitted, Trailblazer assigns one deterministically from setup order.

Setup(TrailblazerWorldContext, Vector3d, NavigationAgentProfile, FixedQuaternion?, Vector3d?, Guid?)

Sets the initial position, exact navigation profile, rotation, velocity, and optional stable identity.

public virtual void Setup(TrailblazerWorldContext context, Vector3d position, NavigationAgentProfile navigationProfile, FixedQuaternion? rotation = null, Vector3d? velocity = null, Guid? globalId = null)

Parameters

context TrailblazerWorldContext

The world context that owns this navigator.

position Vector3d

Initial world-space position.

navigationProfile NavigationAgentProfile

The exact body geometry and traversal capabilities owned by the object.

rotation FixedQuaternion?

Optional starting rotation.

velocity Vector3d?

Optional initial velocity.

globalId Guid?

Optional host-provided stable identity. When omitted, Trailblazer assigns one deterministically from setup order.

Simulate()

Runs simulation logic for this object (input handling, steering, etc.).

public virtual void Simulate()

SyncCurrentTrekConditionToMotor()

Pushes the current traversal snapshot into the motor before the next traversal phase begins.

public virtual void SyncCurrentTrekConditionToMotor()

ToggleGuidedClimb(bool)

Called to toggle climb intent if supported by the installed locomotion profile.

public virtual void ToggleGuidedClimb(bool status)

Parameters

status bool

ToggleGuidedFlight(bool)

Called to toggle controlled flight if supported by the installed locomotion profile.

public virtual void ToggleGuidedFlight(bool status)

Parameters

status bool

ToggleGuidedJump(bool)

Called to make the agent jump if allowed and in a valid state.

public virtual void ToggleGuidedJump(bool status)

Parameters

status bool

ToggleGuidedSwim(bool)

Called to toggle active swim control if supported by the installed locomotion profile.

public virtual void ToggleGuidedSwim(bool status)

Parameters

status bool

TryApplyHeightmapGrounding(bool, Fixed64?, MotionTransfer)

Applies configured heightmap grounding when a concrete navigator chooses to opt in.

protected bool TryApplyHeightmapGrounding(bool updateMotorState = false, Fixed64? surfaceFriction = null, MotionTransfer motionTransfer = MotionTransfer.None)

Parameters

updateMotorState bool

Whether to immediately sync the resulting ground contact into the motor.

surfaceFriction Fixed64?

Optional friction stored in the generated ground condition.

motionTransfer MotionTransfer

Motion transfer mode stored in the generated ground condition.

Returns

bool

True when a registered heightmap sample updated this navigator's ground contact.

Remarks

The base navigator never calls this automatically. Host/concrete navigators should invoke it from their traversal probing code after they know the navigator is grounded on solid terrain.

TryGetTurnDirection(TrekRequest, out Vector3d)

Attempts to resolve the direction the object should try to face for the current frame.

protected virtual bool TryGetTurnDirection(TrekRequest request, out Vector3d turnDirection)

Parameters

request TrekRequest
turnDirection Vector3d

Returns

bool

Events

CommittedCellChanged

Occurs after committed motion enters a different effective cell or leaves navigation data.

public event Action<NavigationCommittedCellState?>? CommittedCellChanged

Event Type

Action<NavigationCommittedCellState?>
Edit this page