t1k:unity:dots-ai:bdp-formations-pack

Field	Value
Module	`dots-ai`
Version	`2.1.7`
Effort	`high`
Tools	—

Keywords: AI movement, BDP, formations, tactical

How to invoke

/t1k:unity:dots-ai:bdp-formations-pack

BDP Formations Pack

Reference for Behavior Designer Pro — Formations Pack add-on by Opsive. Provides 15 built-in NavMesh group formation tasks, extensible via FormationsBase.

Related skills: behavior-designer-pro (BDP core) · agents-navigation (NavMesh bridge) · dots-rpg (RPG library) · bdp-tactical-pack (companion add-on) Related agents: dots-implementer

When This Skill Triggers

Using Opsive.BehaviorDesigner.AddOns.FormationsPack.Runtime.Tasks namespace (formation TASK classes — Column, Wedge, etc.)
Using Opsive.BehaviorDesigner.AddOns.Shared.Runtime.Tasks namespace (the FormationsBase BASE CLASS — moved to Shared in BDP 3.0.x)
Implementing group movement: Column, Wedge, Diamond, V formation, Echelon, Skirmisher, etc.
Working with FormationsBase, CalculateFormationPosition, FormationGroupID
Formation leader/follower assignment (ForceLeader)
Bridging MonoBehaviour formation logic to ECS via AgentNavigationBridgeSystem

Available Formations

15 built-in patterns — → See references/formations-catalog.md for shapes and use cases.

Formation	Shape	Best For
`Column`	Single file	Narrow corridors
`Line` / `Row`	Straight / horizontal	Defensive front
`Wedge` / `V`	Arrow-point / V-shape	Assault, flanking
`Diamond`	Diamond	All-round defense
`Circle`	Ring	Encirclement
`Arc`	Curved line	Partial encirclement
`Grid`	Rectangular	Large groups
`Square`	Square ring	Escort protection
`Echelon`	Diagonal stagger	Flanking advance
`Triangle`	Triangular	Small assault
`Skirmisher`	Dispersed spread	Recon/skirmish
`Swarm`	Loose cluster	Mob AI
`Established`	Keep current offsets	Preserve spread (renamed from `Existing` in BDP 3)

Shared Settings

Formation Group Settings (must match across all agents in same group):

Is2D — Enable for 2D NavMesh (XY plane)
FormationGroupID — Integer ID linking leader + followers
ForceLeader — Force this agent as permanent group leader

Leader Settings (leader entity only):

TargetPosition — Destination for the leader
FormationDirection — Transform / Movement / Specified
SpecifiedDirection — Used when FormationDirection = Specified
MoveToInitialFormation — Wait for all agents to reach slots before advancing
FailOnAgentRemoval — Fail task if any agent leaves group
UpdateUnitLocationsOnAgentRemoval — Recalculate slots on agent removal

Formation Tuning:

RotationSpeed / RotationThreshold — Rotation smoothing
OutOfRangeDistanceDelta / InRangeDistanceDelta — Slot hysteresis
OutOfRangeSpeedMultiplier — Catch-up speed boost
StuckDuration — Seconds before stuck detection triggers
StopOnTaskEnd — Stop NavMesh agent when task ends

Custom Formation

Extend FormationsBase to create a new pattern:

using Opsive.BehaviorDesigner.AddOns.Shared.Runtime.Tasks;  // FormationsBase (BDP 3 — moved from FormationsPack to Shared)
using UnityEngine;

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

    public override Vector3 CalculateFormationPosition(
        int index, int totalAgents, Vector3 center,
        Vector3 forward, bool samplePosition)
    {
        float spacing = 2f;
        float angle = (360f / totalAgents) * index * Mathf.Deg2Rad;
        return center + new Vector3(
            Mathf.Cos(angle) * spacing, 0f,
            Mathf.Sin(angle) * spacing);
    }
}

samplePosition = true → returned position is NavMesh-sampled
AssignOptimialIndicies = true → pack minimizes total travel distance to slots (Hungarian algorithm)

BDP 3 namespace note: FormationsBase moved from the FormationsPack add-on to the Shared add-on (Opsive.BehaviorDesigner.AddOns.Shared.Runtime.Tasks) in BDP 3.0.x. Formation TASK classes (Column, Wedge, etc.) remain in FormationsPack.Runtime.Tasks — only the BASE CLASS moved. Update using directives in any custom formation classes when migrating from BDP 2.

DOTS / ECS Integration

Formations Pack runs on MonoBehaviour NavMesh agents, not pure ECS:

Formation task sets destination on NavMesh agent (MonoBehaviour side)
AgentNavigationBridgeSystem reads NavigationTarget (ECS) → writes AgentBody.Destination
To use formations with DOTS entities: create ECS authoring wrapper that maps formation output to NavigationTarget

Formation tasks set NavMesh destinations — they do NOT move agents directly. Movement is handled by Agents Navigation (AgentBody, AgentLocomotion).

Gotchas

FormationGroupID must be identical across all agents in the same group — mismatched IDs = agents treated as independent
ForceLeader on multiple agents in one group → undefined behavior
Established formation captures world-space offsets at task start — not baked static offsets (renamed from Existing in BDP 3)
AssignOptimialIndicies uses Hungarian algorithm — disable for groups 100+ if CPU cost matters
Formations Pack and Tactical Pack both consume FormationsBase from the Shared add-on — single base class, two add-ons depending on it
BDP 3 FormationsBase namespace moved — base class is now in Opsive.BehaviorDesigner.AddOns.Shared.Runtime.Tasks (was FormationsPack.Runtime.Tasks in BDP 2). Custom formation classes need an updated using directive

Reference Files

File	Content
formations-catalog.md	All 15 formations — visual shapes, parameters, use cases