AgentAction

Abstract base class for all agent-specific actions. Extends the core Action class with pre-cached references to the owning Agent, its possessed Character, and the NavMeshAgent — providing a rich context for AI behavior implementations.

Definition

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

public abstract class AgentAction : Action

Inheritance: Action → AgentAction

Remarks

AgentAction is the bridge between Paragon's generic Action system and the Townskeep agent AI. It adds an Initialize() method that injects agent-specific context, which all concrete agent actions can use in their OnBegin() / OnExecute() implementations.

Initialization Flow

AgentAction.Initialize() is called by Agent.DoAI() at the start of each AI loop iteration, before the ActionSequence executes. This means context references are refreshed every loop cycle.

Context Fields

The four protected fields provide everything an agent action needs:

Field	Type	Source	Purpose
agent	Agent	Passed directly	Access to the agent brain, NavMeshAgent, and possession system
sequence	ActionSequence	Passed directly	The containing sequence (for variable sharing between actions)
character	Character	agent.Character	The possessed character — motor, controller, inventory, etc.
navMeshAgent	NavMeshAgent	agent.NavMeshAgent	Unity NavMesh pathfinding (path calculation only, updatePosition = false)

Quick Lookup

Goal	How
Create a new agent action	Subclass AgentAction, override OnExecute()
Access the character motor	character.Motor
Access the character controller	character.Controller
Calculate a NavMesh path	navMeshAgent.SetDestination(target)
Access the owning agent	agent
Share variables across actions	Use sequence.SetVariable<T>() / sequence.GetVariable<T>()

Fields

Field	Type	Access	Description
agent	Agent	protected	The owning agent
sequence	ActionSequence	protected	The containing action sequence
character	Character	protected	The possessed character
navMeshAgent	NavMeshAgent	protected	Unity NavMesh agent for pathfinding

Methods

Initialize

Injects agent context into the action. Called by Agent.DoAI() before each sequence execution.

public void Initialize(Agent agent, ActionSequence sequence)

Parameter	Type	Description
agent	Agent	The owning agent
sequence	ActionSequence	The action sequence containing this action

Behavior:

1. Stores agent and sequence references

2. Caches agent.Character → character

3. Caches agent.NavMeshAgent → navMeshAgent

Extension Points

Required Overrides

Method	Return Type	Purpose
OnExecute()	Task	Core AI logic — inherited from Action

Optional Overrides

Method	Return Type	Purpose
OnBegin()	void	Setup before execution (create sub-actions, resolve targets)
OnComplete()	void	Success-path cleanup
OnCancel()	void	Cancellation-path cleanup
OnEnd()	void	Final cleanup regardless of outcome

Implementation Requirements

When subclassing AgentAction, you MUST:

1. Override OnExecute() and return a Task

2. Use Yield methods for frame-based waiting (integrates with cancellation)

You SHOULD:

• Create sub-actions (like MoveToTargetAction) in OnBegin(), not in OnExecute()

• Call Initialize() on sub-actions before using them

• Use character.Controller or character.Motor for movement, not navMeshAgent.Move()

• Mark configurable fields with [Variable] for Inspector/sequence variable binding

You SHOULD NOT:

• Rely on navMeshAgent.updatePosition — it is false; the NavMesh agent is for path calculation only

• Assume Initialize() has been called in the constructor — it runs at the start of each AI loop iteration

Common Pitfalls

Initialize() is not called automatically Unlike CharacterComponent.OnInitialize(), AgentAction.Initialize() must be called explicitly. The Agent.DoAI() loop handles this, but if you create an AgentAction outside the normal AI loop (e.g., as a sub-action), you must call Initialize() yourself.

NavMeshAgent is for path calculation only navMeshAgent.updatePosition is false. Calling navMeshAgent.Move() or relying on navMeshAgent.nextPosition for automatic movement will not work. Use character.Controller.MoveTo() or character.Motor.MoveTo() instead.

Examples

Minimal Agent Action

using System.Threading.Tasks;
using Paragon.Core.Async;
using Paragon.Townskeep.AgentSystem;

public class IdleAction : AgentAction
{
    [Variable]
    private float duration = 3f;

    protected override async Task OnExecute()
    {
        await Yield.WaitForSeconds(duration);
    }
}

Action with Sub-Action

using System.Threading.Tasks;
using UnityEngine;
using Paragon.Townskeep.AgentSystem;

public class PatrolAction : AgentAction
{
    [Variable]
    private Vector3 pointA;

    [Variable]
    private Vector3 pointB;

    private MoveToTargetAction moveAction;

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

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

        moveAction.SetTargetPosition(pointB);
        await moveAction.ExecuteAsync();
    }
}

See Also

• Agent — the AI brain that initializes and executes agent actions

• FollowPathAction — concrete action: follow a waypoint path

• GoToStoreAction — concrete action: navigate to a shop table

• Action — core abstract action class

• Actions Overview — subsystem architecture