Custom Formations

Export

Create a project-specific pattern with a bindable destination by inheriting from FormationsTargetBase and implementing CalculateFormationPosition. The lower-level FormationsBase also requires an implementation of the abstract TargetPosition property. The method returns one member’s world-space assignment from its index, group size, center, and forward direction.

Implement a formation

using Opsive.BehaviorDesigner.AddOns.Shared.Runtime.Tasks;
using UnityEngine;

public class MyFormation : FormationsTargetBase
{
    public override bool AssignOptimialIndicies => true;

    public override Vector3 CalculateFormationPosition(
        int index,
        int totalAgents,
        Vector3 center,
        Vector3 forward,
        bool samplePosition)
    {
        // A 3D line with two units between adjacent members.
        var right = Vector3.Cross(Vector3.up, forward).normalized;
        var position = center + right * (index * 2f);
        if (samplePosition) {
            SamplePosition(ref position);
        }
        return position;
    }
}

This example uses the 3D XZ plane. Supply a nonzero horizontal forward direction, and adapt the axes for a 2D formation. Return a position relative to center and forward, not a fixed world position. Use samplePosition when the implementation should constrain the result to the selected navigation surface.

Set AssignOptimialIndicies to true when the manager should minimize member travel to the calculated slots. Set it to false when authored, random, or role-specific index meaning should remain stable.

Design the index mapping

Define what every index means before writing the position math. Test index 0, one member, an incomplete final row, and every special role the pattern reserves.

Do not silently clamp every unreachable assignment to the same sampled point. Decide whether the custom formation should accept provider sampling, fail to another graph branch, or choose a narrower pattern.

Verify the custom task

  1. Add the compiled task to a small group.
  2. Verify one, two, and several members.
  3. Rotate and move the leader so positions remain relative to the intended direction.
  4. Add and remove a member while the task is running.
  5. Test navigation edges, corners, and narrow routes.
  6. Compare spacing with the navigation agent radius and stopping distance.