Runtime Control

Export

Bind formation fields to Graph variables when spawning, match logic, or player commands must control the group. The pack does not use a separate followers array: every agent whose task is active registers under Formation Group ID, one member is the leader, and every other member receives a calculated follower slot.

Assign leaders and followers

  1. Create Graph variables such as FormationDestination, FormationGroupID, and ForceLeader.
  2. Bind Target Position, Formation Group ID, and Force Leader to those variables instead of constants.
  3. Give every member the same group ID.
  4. Set ForceLeader to true on exactly one member and to false on the followers.
  5. Start the formation branch only after the intended members are active.

An agent joins when its task starts and leaves when the task ends or its tree is stopped. Before returning an agent to a pool, stop or abort its formation task so the manager does not retain it as an active member.

To transfer leadership, stop the affected formation branches, change the leader bindings, and start them again. Do not leave two running members with Force Leader enabled during a handoff.

Update the destination from gameplay code

Bind the leader task’s Target Position to a Vector3 Graph variable. A MonoBehaviour can cache that variable and update it whenever the command marker, escort target, or RTS order changes:

using Opsive.BehaviorDesigner.Runtime;
using Opsive.GraphDesigner.Runtime.Variables;
using UnityEngine;

public class FormationDestinationDriver : MonoBehaviour
{
    [SerializeField] private BehaviorTree m_LeaderTree;
    [SerializeField] private Transform m_Destination;

    private SharedVariable<Vector3> m_FormationDestination;

    private void Awake()
    {
        m_FormationDestination =
            m_LeaderTree.GetVariable<Vector3>("FormationDestination");
    }

    private void Update()
    {
        if (m_FormationDestination != null && m_Destination != null) {
            m_FormationDestination.Value = m_Destination.position;
        }
    }
}

The spelling and capitalization passed to GetVariable must match the Graph variable, and the task field must be bound to it. See Accessing Variables for Graph, GameObject, Scene, and Project scopes, and the Behavior Designer Pro API for the runtime component surface.

Handle destination and membership changes

Built-in formations consume a Vector3 Target Position, not a Transform target. To follow a command transform, continuously copy its position into that bound variable, as above, or explicitly map the variable to the transform position. Filter insignificant position changes when network or animation noise would make the group continually repath.

Enable Update Unit Locations On Agent Removal when remaining members should close gaps. Use Fail On Agent Removal when losing a required member should abort to a higher-level recovery branch.

For a formation change, abort the current formation task and enter the replacement branch. Avoid running two formation tasks that both own the same member’s destination.