Class FormationUtils

Namespace

WitShells.DesignPatterns.Core

Static utility class that generates world-space Pose lists for common tactical/game unit formations. Each method returns a list of positions and rotations that can be assigned to agents, NPCs, or any Unity objects.

public static class FormationUtils

Inheritance

object

FormationUtils

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

All methods are allocation-friendly – they return a new List<Pose> that the caller owns. None of the methods move objects; callers apply the poses themselves.

Methods

GenerateBoxFormation(Transform, int, float)

Generates a square/rectangular box formation. Entities are arranged in a grid as close to square as possible.

public static List<Pose> GenerateBoxFormation(Transform transform, int numberOfEntities, float spacing)

Parameters

transform Transform

Reference transform providing position and orientation.

numberOfEntities int

Total number of entities in the box.

spacing float

Gap between entities both horizontally and vertically.

Returns

List<Pose>

GenerateCircleFormation(Vector3, float, int)

Generates a circular formation centred on center. Each entity faces the centre of the circle.

public static List<Pose> GenerateCircleFormation(Vector3 center, float radius, int numberOfEntities)

Parameters

center Vector3

The world-space centre of the circle.

radius float

Radius of the circle in world units.

numberOfEntities int

How many evenly-spaced poses to produce.

Returns

List<Pose>

A list of Pose values arranged on the perimeter of the circle.

GenerateColumnFormation(Transform, int, float, int)

Generates a column formation where entities are arranged in multiple rows, each row holding elementsPerRow entities side by side.

public static List<Pose> GenerateColumnFormation(Transform transform, int numberOfEntities, float spacing, int elementsPerRow = 2)

Parameters

transform Transform

Reference transform providing position and orientation.

numberOfEntities int

Total number of entities in the column.

spacing float

Gap between entities in all directions.

elementsPerRow int

Number of entities per row (default 2).

Returns

List<Pose>

GenerateDiamondFormation(Transform, int, float)

Generates a diamond formation with a single leader at the tip and expanding diagonal lines of entities behind. Additional entities beyond the first four continue the diamond pattern at each successive depth level.

public static List<Pose> GenerateDiamondFormation(Transform transform, int numberOfEntities, float spacing)

Parameters

transform Transform

Reference transform providing position and orientation.

numberOfEntities int

Total number of entities including the leader.

spacing float

Gap between adjacent entities in the diamond.

Returns

List<Pose>

GenerateEchelonFormation(Transform, int, float, float, bool)

Generates an echelon (staircase) formation where each entity is offset diagonally to the right or left and behind the previous one.

public static List<Pose> GenerateEchelonFormation(Transform transform, int numberOfEntities, float spacingX, float spacingZ, bool rightEchelon = true)

Parameters

transform Transform

Reference transform providing position and orientation.

numberOfEntities int

Total number of entities in the echelon.

spacingX float

Horizontal offset per step.

spacingZ float

Depth offset per step.

rightEchelon bool

If true, the echelon trails to the right; otherwise to the left.

Returns

List<Pose>

GenerateLineFormation(Transform, int, int, bool, bool)

Generates a straight-line formation relative to a Transform. The line runs along the right axis (horizontal) or forward axis (vertical) of the transform.

public static List<Pose> GenerateLineFormation(Transform transform, int numberOfEntities, int spacing, bool isCentered = false, bool isVertical = false)

Parameters

transform Transform

Reference transform that defines position and orientation.

numberOfEntities int

Total number of poses to place in the line.

spacing int

Gap between consecutive entities in world units.

isCentered bool

If true, the line is centred on the transform's position.

isVertical bool

If true, the line runs along the forward axis; otherwise the right axis.

Returns

List<Pose>

GenerateLineFormation(Vector3, Vector3, int)

Generates a straight-line formation between two explicit world positions. All entities face the direction from start to end.

public static List<Pose> GenerateLineFormation(Vector3 start, Vector3 end, int numberOfEntities)

Parameters

start Vector3

World-space start point of the line.

end Vector3

World-space end point of the line.

numberOfEntities int

Number of evenly-spaced poses along the line.

Returns

List<Pose>

GenerateTriangleFormation(Transform, int, float)

Generates a triangle formation where each successive row has one more entity than the previous, starting from a single entity at the front.

public static List<Pose> GenerateTriangleFormation(Transform transform, int numberOfEntities, float spacing)

Parameters

transform Transform

Reference transform providing position and orientation.

numberOfEntities int

Total number of entities to place.

spacing float

Gap between entities within a row and between rows.

Returns

List<Pose>

GenerateVFormation(Transform, int, float, float)

Generates a V-shaped formation (two diagonal lines diverging from the front). The first entity is placed at the tip; subsequent entities fan out on each side.

public static List<Pose> GenerateVFormation(Transform transform, int numberOfEntities, float spacingX, float spacingZ)

Parameters

transform Transform

Reference transform providing position and orientation.

numberOfEntities int

Total number of entities in the V.

spacingX float

Horizontal spacing between consecutive entities on each arm.

spacingZ float

Depth offset per step along the forward axis.

Returns

List<Pose>

GenerateWedgeFormation(Transform, int, float, float)

Generates a wedge (arrowhead) formation with a single leader at the front and two diverging lines trailing behind.

public static List<Pose> GenerateWedgeFormation(Transform transform, int numberOfEntities, float spacingX, float spacingZ)

Parameters

transform Transform

Reference transform providing position and orientation.

numberOfEntities int

Total number of entities including the leader.

spacingX float

Horizontal gap per step along each trailing arm.

spacingZ float

Depth gap per step behind the leader.

Returns

List<Pose>