An Entity Task keeps managed authoring separate from unmanaged runtime data and Burst-compatible execution. Use it when the project already uses ECS or profiling shows that task execution needs to scale; otherwise start with a GameObject Task. Shared Variable values can also be registered for buffer access; see ECS Variables.

Define the task and runtime data

The example below creates a Within Distance Conditional that compares two positions. Add the compiled task to a tree, set Origin, Target, and Distance, and use Conditional Aborts when changes must interrupt another branch. The positions in this example are configured values; use registered Shared Variables or project ECS data when the endpoints move.

Part Responsibility
Authoring class Derives from ECSConditionalTask<TSystem, TBufferElement, TComponentFlag>, exposes the Inspector fields, and copies their values into the runtime buffer. RuntimeIndex identifies the corresponding task-status entry.
Buffer component Stores unmanaged per-task values and the runtime task index. Several instances of the same task can share one entity’s buffer.
Active flag An enableable component that selects entities with active instances of this task.
System and job Query the task buffer, status buffer, branch data, active flag, and EvaluateFlag. Evaluate only executable branches whose task status is Queued or Running, then write the result back to the status buffer.
Reevaluation flag and system Select instances being checked by conditional aborts. Only a changed result should update task status.

The base class implements the authoring boilerplate. A manual implementation instead supplies ITreeLogicNode, IAuthoringTask, and the task marker interface (IConditional here). That includes Enabled and structural indices, Flag and SystemType, buffer creation/removal, and Reset. Register Shared Variables through the ECSVariableRegistry passed to AddBufferElement. Implement IReevaluateResponder and its flag/system properties when the Conditional supports abort reevaluation.

Complete Entity Conditional

Create these declarations in the project. The authoring class, buffer, flags, systems, and job are one complete example; the nested job belongs inside its system. The systems use DisableAutoCreation because Behavior Designer creates them when required by a tree.

using Opsive.BehaviorDesigner.Runtime.Components;
using Opsive.BehaviorDesigner.Runtime.Tasks;
using Opsive.GraphDesigner.Runtime;
using Unity.Burst;
using Unity.Collections;
using Unity.Entities;
using Unity.Mathematics;
using UnityEngine;

[Opsive.Shared.Utility.Category("ECS Example")]
[Opsive.Shared.Utility.Description("Returns success when the agent is within distance of the specified position.")]
public class WithinDistance : ECSConditionalTask<WithinDistanceTaskSystem, WithinDistanceComponent, WithinDistanceFlag>, IReevaluateResponder
{
    [SerializeField] private Vector3 m_Origin;
    [SerializeField] private Vector3 m_Target;
    [SerializeField] private float m_Distance = 5f;

    public ComponentType ReevaluateFlag { get => typeof(WithinDistanceReevaluateFlag); }
    public System.Type ReevaluateSystemType { get => typeof(WithinDistanceReevaluateTaskSystem); }

    /// <summary>
    /// Returns a new TBufferElement for use by the system.
    /// </summary>
    /// <returns>A new TBufferElement for use by the system.</returns>
    public override WithinDistanceComponent GetBufferElement()
    {
        return new WithinDistanceComponent()
        {
            Index = RuntimeIndex,
            Origin = m_Origin,
            Target = m_Target,
            Distance = m_Distance
        };
    }
}

/// <summary>
/// The DOTS data structure for the WithinDistance struct.
/// </summary>
public struct WithinDistanceComponent : IBufferElementData
{
    [Tooltip("The index of the node.")]
    public ushort Index;
    [Tooltip("The target position to determine if the agent is within the distance of.")]
    public float3 Origin;
    [Tooltip("The target position to determine if the agent is within the distance of.")]
    public float3 Target;
    [Tooltip("Returns success when the agent is within the specified distance.")]
    public float Distance;
}

/// <summary>
/// A DOTS flag indicating when a WithinDistance node is active.
/// </summary>
public struct WithinDistanceFlag : IComponentData, IEnableableComponent { }

/// <summary>
/// Runs the WithinDistance logic.
/// </summary>
[DisableAutoCreation]
public partial struct WithinDistanceTaskSystem : ISystem
{
    private EntityQuery m_Query;

    /// <summary>
    /// Creates the required objects for use within the job system.
    /// </summary>
    /// <param name="state">The current SystemState.</param>
    [BurstCompile]
    private void OnCreate(ref SystemState state)
    {
        m_Query = new EntityQueryBuilder(Allocator.Temp)
        .WithAllRW<TaskComponent>()
        .WithAll<BranchComponent>()
        .WithAll<WithinDistanceComponent, WithinDistanceFlag, EvaluateFlag>()
        .Build(ref state);
    }

    /// <summary>
    /// Updates the job.
    /// </summary>
    /// <param name="state">The current state of the system.</param>
    [BurstCompile]
    private void OnUpdate(ref SystemState state)
    {
        state.Dependency = new WithinDistanceJob().ScheduleParallel(m_Query, state.Dependency);
    }

    /// <summary>
    /// Job which executes the task logic.
    /// </summary>
    [BurstCompile]
    private partial struct WithinDistanceJob : IJobEntity
    {
        /// <summary>
        /// Executes the idle logic.
        /// </summary>
        /// <param name="branchComponents">An array of BranchComponents.</param>
        /// <param name="taskComponents">An array of TaskComponents.</param>
        /// <param name="withinDistanceComponents">An array of WithinDistanceComponents.</param>
        [BurstCompile]
        public void Execute(in DynamicBuffer<BranchComponent> branchComponents, ref DynamicBuffer<TaskComponent> taskComponents, in DynamicBuffer<WithinDistanceComponent> withinDistanceComponents)
        {
            for (int i = 0; i < withinDistanceComponents.Length; ++i) {
                var withinDistanceComponent = withinDistanceComponents[i];
                var taskComponent = taskComponents[withinDistanceComponent.Index];
                var branchComponent = branchComponents[taskComponent.BranchIndex];

                if (!branchComponent.CanExecute || (taskComponent.Status != TaskStatus.Queued && taskComponent.Status != TaskStatus.Running)) {
                    continue;
                }

                taskComponent.Status = math.distance(withinDistanceComponent.Origin, withinDistanceComponent.Target) < withinDistanceComponent.Distance ? TaskStatus.Success : TaskStatus.Failure;
                taskComponents[withinDistanceComponent.Index] = taskComponent;
            }
        }
    }
}

/// <summary>
/// A DOTS flag indicating when an WithinDistance node needs to be reevaluated.
/// </summary>
public struct WithinDistanceReevaluateFlag : IComponentData, IEnableableComponent
{
}

/// <summary>
/// Runs the WithinDistance reevaluation logic.
/// </summary>
[DisableAutoCreation]
public partial struct WithinDistanceReevaluateTaskSystem : ISystem
{
    /// <summary>
    /// Updates the reevaluation logic.
    /// </summary>
    /// <param name="state">The current state of the system.</param>
    [BurstCompile]
    private void OnUpdate(ref SystemState state)
    {
        foreach (var (taskComponents, withinDistanceComponents) in SystemAPI.Query<DynamicBuffer<TaskComponent>, DynamicBuffer<WithinDistanceComponent>>().WithAll<WithinDistanceReevaluateFlag, EvaluateFlag>()) {
            for (int i = 0; i < withinDistanceComponents.Length; ++i) {
                var withinDistanceComponent = withinDistanceComponents[i];
                var taskComponent = taskComponents[withinDistanceComponent.Index];
                if (!taskComponent.Reevaluate) {
                    continue;
                }

                var status = math.distance(withinDistanceComponent.Origin, withinDistanceComponent.Target) < withinDistanceComponent.Distance ? TaskStatus.Success : TaskStatus.Failure;
                if (status != taskComponent.Status) {
                    taskComponent.Status = status;
                    var buffer = taskComponents;
                    buffer[taskComponent.Index] = taskComponent;
                }
            }
        }
    }
}

Execution and conditional aborts

At initialization, GetBufferElement copies the configured positions and distance into WithinDistanceComponent. During normal execution, the job looks up the corresponding TaskComponent and its BranchComponent. An executable task returns Success when the distance is strictly less than the threshold and Failure otherwise. It does not remain Running.

Queries must require enabled EvaluateFlag. Pausing or stopping a tree disables that flag even while the component remains present; querying with IgnoreComponentEnabledState would also process those stopped trees.

Reevaluation uses WithinDistanceReevaluateFlag rather than the active-task flag. The reevaluation system processes only entries marked for reevaluation, compares the newly calculated result with the stored status, and writes only when it changes. The tree’s conditional-abort configuration decides whether that change interrupts a running branch; the task does not select or abort branches itself.

Test with a distance above, below, and exactly at the threshold. To test aborts, supply changing runtime values, keep another branch Running, and confirm that the selected abort mode reacts when the Conditional changes result. Ensure ordinary execution and reevaluation use the same comparison and that the systems write status changes back to the buffers.

Related: GameObject Tasks, Conditional Aborts, ECS Variables, and Performance.