Formations

formation

formation <name>
   debug
   detached
   offset ...

   [lead] formation ... end_formation
   [lead] section ... end_section
   [lead] unit ... end_unit
end_formation

Overview

Formations provide the means to organize both logically and physically groups of platforms having a WSF_P6DOF_MOVER, which can then be controlled as a group instead of individually. Formations can also be defined in script, see WsfFormation and WsfFormationManager. Formations can be given commands, see WsfFormationCommand.

A formation is a hierarchy: a formation may have sub-formations defined, which themselves have sub-formations ending ultimately at unit formations that have member platforms (see Unit Formation).

Each formation has two identifiers, its relative name and its qualified name. The relative name is used to identify a formation relative to its parent, and is only unique among the set of sibling sub-formations. A qualified name is a concatenation (using ‘.’) of the relative names of each formation of which it is a sub-formation. A qualified name can be used to uniquely identify a formation.

For example, if a top-level formation with relative name ‘yankee’ has a sub-formation with relative name ‘alpha’, then the qualified name of that subformation would be ‘yankee.alpha’. If that formation then had a sub-formation ‘one’, that would have the qualified name ‘yankee.alpha.one’.

Formation Control

Each formation is either attached or detached from its parent formation. When a formation is attached, its members will keep station relative to its leader. The attached state is applied to each formation individually, so it is possible, for example, to have most of a formation attached and a single subformation detached.

The attached state of a formation impacts both station keeping for the members of that formation, and the propagation of formation commands. Commands assigned to a formation will often lead to commands also being assigned to subformations of the assignee. However, most commands will not propagate to detached subformations (WsfFormationAttachCommand is one notable exception).

Controlling a formation is done by both assigning a WsfFormationCommand to a formation, and by directing the behavior of formation leaders directly. When a formation leader is controlled directly (e.g., by issuing a WsfManeuver), the members of any attached subformations will keep station with the leader.

Common Formation Commands

debug

Enable extra debugging output.

detached

For formations defined in the initial conditions, this will cause this formation to not be attached to its parent. After initialization any attached formation will have its members placed into the correct positions relative to the formation leader. The detached status on a formation also effects the way formation commands are propagated down through the hierarchy. See WsfFormationCommand.

offset <length-value> <angle-value> <length-value> offset_type

Specify the offset of the formation from its parent. This is the means by which the initial relative positioning of the members of a formation is specified. The offset is given as a triplet of a range from the reference point, a relative bearing from the direction of travel of the leader, and a vertical offset (or stack). For example, the following offset would be the point 100 m to the right of the reference point and at 1 m higher altitude.

offset 100 m 90 deg 1 m fixed-altitude

The offset type is either welded-wing or fixed-altitude. A welded wing offset computes its location based on the body frame of the lead platform. A fixed altitude offset computes its location as if the lead platform has a zero roll angle.

Sub-formation Commands

formation … end_formation

Define a general sub-formation. This block is identical to the top-level input block.

section … end_section

Define a section sub-formation. See Section Formation.

unit … end_unit

Define a unit sub-formation. See Unit Formation.

lead

When prefixed before a sub-formation command, this indicates that the following formation defined is the lead sub-formation of the enclosing parent formation. Formation defined in input must have one (and only one) lead sub-formation defined.