Runtime Control and Tuning

Export

Use shared variables when player commands, spawning, encounters, or another gameplay system must update a formation without rebuilding its behavior tree.

Control a formation from code

The built-in formation task moves the leader and calculates follower slots. Bind the leader task’s Target Position to a local Vector3 variable named LeaderDestination, leave Target Transform unassigned, and update the variable through the leader’s BehaviorTree:

using BehaviorDesigner.Runtime;
using UnityEngine;

public class FormationOrder : MonoBehaviour
{
    [SerializeField] private BehaviorTree m_LeaderTree;

    public void SetDestination(Vector3 worldPosition)
    {
        m_LeaderTree.SetVariableValue("LeaderDestination", worldPosition);
    }
}

While the formation is running, changed destination values are propagated to followers. Alternatively, bind Target Transform to follow a moving transform; a non-null transform takes precedence over Target Position. The protected TargetPosition method calculates member slots and is separate from these destination fields.

The task returns Success when the group arrives. For later orders, restart the participating formation tasks after writing the new destination, or author a repeated group workflow. Membership lasts only while the task is active. Avoid a concurrent movement task that writes the same navigation agent’s destination.

See Accessing Variables from non-Task Objects for GetVariable, SetVariableValue, and global-variable examples.

Handle dynamic membership

Start the formation task on an agent to join the configured group. Abort or stop the task before disabling or pooling the agent. Configure only one leader. For a leadership change, stop affected tasks, update their bound leader data, and start the group again.

When a member leaves, decide whether remaining agents should close the gap immediately or whether a higher-level branch should finish death, combat, or pooling first.

Tune spacing and motion

  1. Begin with a stationary leader on open navigation data.
  2. Set spacing above the combined radii of adjacent agents.
  3. Verify one, two, and several members.
  4. Move the leader slowly before testing turns and gameplay speed.
  5. Add corners, doors, slopes, and local avoidance.

When members cross paths, increase spacing, improve avoidance, or change initial placement. When trailing members continually fall behind, compare leader speed with follower acceleration and stopping behavior.

The formation cannot remain rigid if the leader permanently moves faster than followers can recover.

Change formation for a route segment

Abort the active wide formation, start Column through a bottleneck, then start the preferred shape in open space. Avoid running two formation actions that both own the same member destinations.