MoveToTargetAction

Core movement primitive for agent AI. Sets a NavMesh destination and continuously drives the character's controller toward the next path position until within 0.5 units of the target. Used directly and as a sub-action by higher-order actions.

Definition

Namespace: Paragon.Townskeep.AgentSystem Assembly: Townskeep.dll

public class MoveToTargetAction : AgentAction

Inheritance: Action → AgentAction → MoveToTargetAction

Remarks

MoveToTargetAction is the fundamental movement building block for agent AI. Most other movement-based actions (GoToTradeAction, GoToStoreAction, FollowPathAction, WanderAction) create and delegate to MoveToTargetAction internally.

Movement Loop

Key Design Decisions

Decision	Rationale
navMeshAgent.SetDestination for path calculation	NavMeshAgent is configured with updatePosition = false — it calculates the path but doesn't move the transform
character.Controller.MoveTo for actual movement	The character's controller/motor handles physics and animation
Teleport guard (nextStepDistance > 1f)	If the NavMesh suggests a position more than 1 unit away, it reverts to the last known good position to prevent teleporting
Arrival threshold 0.5f	Movement loop exits when within 0.5 units of the destination
Camera follows forward direction	character.Camera.LookAt(Position + forward) keeps the camera pointing ahead during movement

Usage as Sub-Action

MoveToTargetAction is commonly created inside other actions' OnBegin() methods:

protected override void OnBegin()
{
    moveAction = new MoveToTargetAction();
    moveAction.Initialize(agent, sequence);
}

protected override async Task OnExecute()
{
    moveAction.SetTargetPosition(target);
    await moveAction.ExecuteAsync();
}

Quick Lookup

Goal	How
Move agent to a position	moveAction.SetTargetPosition(pos); await moveAction.ExecuteAsync()
Set target programmatically	moveAction.SetTargetPosition(Vector3)
Set target from Inspector	Bind targetPosition via [Variable] in the sequence
Use as sub-action	Create in OnBegin(), call Initialize(agent, sequence), then use in OnExecute()

Fields

Field	Type	Access	Description
targetPosition	Vector3	[Variable] private	The destination position; settable via Inspector, sequence variables, or SetTargetPosition()
nextPosition	Vector3	private	Last known good NavMesh position (for teleport guard)

Methods

SetTargetPosition

Sets the movement target position. Call this before Execute() or ExecuteAsync() when using programmatically.

public void SetTargetPosition(Vector3 targetPosition)

Parameter	Type	Description
targetPosition	Vector3	World-space destination position

OnExecute

Runs the movement loop: sets NavMesh destination, drives the character controller each frame, and awaits arrival within 0.5 units.

protected override async Task OnExecute()

Common Pitfalls

Teleport guard can cause stuck agents If navMeshAgent.nextPosition is consistently more than 1 unit from the character's current position (e.g., due to frame spikes or complex navmesh geometry), the guard will keep reverting the position, potentially causing the agent to appear stuck. This threshold is hardcoded.

Arrival threshold is 0.5 units The while (distance > 0.5f) loop condition means the agent stops within half a unit of the destination. For precise positioning, additional logic is needed after the action completes.

No path failure handling If navMeshAgent.SetDestination fails (e.g., destination is off the NavMesh), the action will loop indefinitely — the distance will never decrease below 0.5. There is no timeout or path validity check.

Camera look direction is set every frame character.Camera.LookAt(character.Camera.Position + character.transform.forward) is called each frame, overriding any other camera targeting. This means the camera always faces the movement direction during movement.

Reusable but not concurrent A single MoveToTargetAction instance can be reused with different targets (call SetTargetPosition then ExecuteAsync again), but it should not be executed concurrently.

See Also

• AgentAction — abstract base with agent context

• GoToTradeAction — uses this to navigate to the trading table

• GoToStoreAction — uses this to navigate to display tables

• FollowPathAction — uses this to visit each waypoint

• WanderAction — uses this for wandering between waypoints

• Actions Overview — subsystem architecture