Adding a formation
Adding a formation has become more simple. The only thing you need to do is making a formation template (like any entity template), preferably in the formations subdirectory. See one of the existing templates. You also need to make an icon, and make it available under the same name in the formation icons.
Afterwards, the formation needs to be made available to certain civilisations by adding them to the civ profile, as done in other civ profiles.
At that point, the formation will be visible in the formation panel in the GUI when playing the game, but it will be greyed out. To make the formation available to certain units, it needs to be added to their Identity component of the template. Either to the unit.xml template for all units, or one of the subtemplates.
This is enough to add the formation to the units you want.
The formation parameters change the look and working of formations.
This name will be used in the GUI tooltip
Require a minimum number of members in the formation.
This tooltip will be shown in addition to the formation name when the formation is available to the civilisation, but disabled.
The default speed of a formation is the minimum speed of all members. But a formation can have a SpeedMultiplier to modify that default speed. E.g. a SpeedMultiplier of 0.5 will make the formation half as fast.
The formation shape is a general description of the shape. Currently, "square" and "triangle" are supported. "special" is also used, but for those formations, the code to calculate the positions has to be specified in JS.
If this tag is set to "true", subsequent rows will be shifted.
SortingClasses and SortingOrder
The formation positions are created in a certain order. By default, the first position is the center of the first row, then filling the row outwards, and starting again in the center of the next row. The positions are then filled in the order defined by the SortingClasses. F.e. if "Melee" is your first sorting class, then it will try to fill the first row with melee units, if there are still melee units left, it will fill the second row, ... The SortingOrder tag can be used to change the order in which the positions are filled. Currently there are two supported orders: "fillFromTheSides" and "fillToTheCenter". fillFromTheSides will start filling from the sides instead of the front of your formation. This can be handy to get the cavalry on the sides. The fillToTheCenter will start with filling all borders of the formation (thus the front and last row, and the side columns). This is handy to protect vulerable units in the middle of the formation if you expect attacks from all sides.
The WidthDepthRatio will define the general shape of the formation. A WidthDepthRatio will try to create a perfect square (expressed in number of units, not in meters). A WidthDepthRatio of 2 will try to create a formation that's twice as wide as it's deep. And a WidthDepthRatio of 0.5 will try to create a formations that's twice as deep as it's wide.
MinColumns, MaxColumns and MaxRows
These tags should be pretty clear, but they can collide a bit. When the MinColumns is defined, it will start with filling that number of columns before starting a new row. When MaxColumns and MaxRows are defined, and the number of entities is too big to fit in those constraints, it will keep the MaxRows as wanted, but will go over the MaxColumns. When there are no problems with constraints, it will fall back to using the WidthDepthRatio.
The size of the central gap in the formation (for a flank formation). The gap is expressed in number of units (so will be wider when your formation contains bit units).
UnitSeparationWidthMultiplier and UnitSeparationDepthMultiplier
Normally, the units are placed on a distance in the formation based on their footprint size. By using these variables, you can place them closer together, or further apart.
The formation component can also set animation variants, that will be used by formation members. This is an example of animation-replacement code. This is an example:
<Animations> 1..2,1..-1: syntagma_front; 3..3,1..-1: syntagma_01; 4..4,1..-1: syntagma_02; 5..5,1..-1: syntagma_03; 6..6,1..-1: syntagma_04; 7...-1,1..-1: syntagma_back </Animations>
The above example schema replaces animation variant with syntagma_front for row 1 and 2. The indices you see denote a rectangle with the following parameters: rowStart..rowEnd,columnStart..columnEnd. You can use negative indices to denote the last row/column, second to last, etc. Then after the ":", the name of the animation variant replacement is given. That name needs to be present in the actor file. Else the animations will fall back to animation variant with highest frequency as for all missing animations. The different rectangle definitions need to be separated by a ";" character. Indices that fall out of all rectangle definitions will keep using the default animation variants.
Current UnitAI implementation will apply this variant if present for combat, idling, walking and running.