> For the complete documentation index, see [llms.txt](https://travljen.gitbook.io/unit-formation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://travljen.gitbook.io/unit-formation/how-it-works/formations.md).

# Formations

## List of formations

Here you can find names and behaviours for each provided formation. 

<details>

<summary>Ring</summary>

Positions units in a ring formation with specified configurations:

* **Angle**
* **Unit spacing**&#x20;

![](https://373113018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FO5oY9g3h48cclwOChrGD%2Fuploads%2Fpb4L5yE4C4tKq6rHCiUe%2FScreenshot%202024-05-19%20at%2018.59.01.png?alt=media\&token=6aa2a429-d4f6-4cd6-a6ee-c27580535ccd)

</details>

<details>

<summary>Cone</summary>

Positions units in a cone formation. Configurations:

* **Unit spacing**
* **Pivot in center** (flag)

![](https://373113018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FO5oY9g3h48cclwOChrGD%2Fuploads%2FMLxo8vVLrYi6xGET9h7z%2FScreenshot%202024-05-19%20at%2019.00.07.png?alt=media\&token=76e5f3b5-556e-4a6b-ac11-62ca339fa234)

</details>

<details>

<summary>Line</summary>

Positions units in a line formation. Only configuration here is **unit spacing**.

![](https://373113018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FO5oY9g3h48cclwOChrGD%2Fuploads%2F5tezRtevLD5q5CszYziM%2FScreenshot%202024-05-19%20at%2019.00.18.png?alt=media\&token=f30113f0-5d6b-4e68-b0e6-21937e0fa0f7)

</details>

<details>

<summary>Rectangle</summary>

Positions units in a filled rectangle. Configurations:

* **Column count**
* **Unit spacing**
* **Center units** (when last line is not full)
* **Pivot in center** (flag)

![](https://373113018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FO5oY9g3h48cclwOChrGD%2Fuploads%2FWZfFeToz2FJ1BRNBwZtC%2FScreenshot%202024-05-19%20at%2019.00.38.png?alt=media\&token=925568e2-3d58-40d4-b95e-21bab0ee94fe)

</details>

<details>

<summary>Rectangle Border</summary>

Positions units along the rectangle edges. If there are too few units, then a line is formed.&#x20;

Configurations:

* **Unit spacing**
* **Aspect Ratio**
* **Pivot in center** (flag)

![](https://373113018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FO5oY9g3h48cclwOChrGD%2Fuploads%2FMt494q3swKSggstNXhze%2FScreenshot%202024-05-19%20at%2019.00.48.png?alt=media\&token=4a0c1470-dc4e-4e1f-9954-bb556d2ad4f3)

*When there is a left over unit, it will be added to back side of the formation (front and back might be uneven in unit numbers)*

</details>

<details>

<summary>Triangle</summary>

Positions units in a filled triangle formation. Configuration:

* **Unit spacing**
* **Center units** (when last line is not full)
* **Pivot in center**

![](https://373113018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FO5oY9g3h48cclwOChrGD%2Fuploads%2Fq8Nnz3GMxx0fMI8eNzb0%2FScreenshot%202024-05-19%20at%2019.01.11.png?alt=media\&token=bd38c0d8-88e1-4558-a985-7a707f615d6d)

</details>

<details>

<summary>Triangle Border</summary>

Positions units in a triangle formation. Configuration:

* **Unit spacing**
* **Pivot in center** (flag)

![](https://373113018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FO5oY9g3h48cclwOChrGD%2Fuploads%2FBTWfUuxE0oFSyAwbvDKt%2FScreenshot%202024-05-19%20at%2019.01.23.png?alt=media\&token=de5e01ef-c1fc-47b5-9079-095663278ea3)

*When units cannot be divided by 3, there are some leftovers. When there are 2, they are added on left and right side, when there is one, it is added to the back side of the triangle formation.*

</details>

<details>

<summary>Circle</summary>

Positions units within a circle with fill. While this implementation is fairly simplistic, filling a circle can be quite a computational heavy and complex task. For this the formation must be adjusted manually with parameters to fit different unit counts:

* **Outer radius**
* **Unit spacing**

When max radius is not large enough for unit count and their required spacing, remaining units will be placed in its center.

![](https://373113018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FO5oY9g3h48cclwOChrGD%2Fuploads%2FOv2Dp7xZkCNfM78loAtI%2FScreenshot%202024-05-19%20at%2018.59.55.png?alt=media\&token=5160ddf6-c9b5-4aea-a562-9f5535a7d5d9)

</details>

<details>

<summary>Computed Circle</summary>

Uses the same calculation as the base Circle, but uses iterations to fit best fit. Search is controlled by:

* **Minimal radius** (starting radius)
* **Maximal iterations** (number of maximal attempts)
* **Radius increment** (radius increment for each attempt)

Use this formation to find the best fit, but using it in game/project to calculate filled circle could be performance intensive for higher number of units or iterations.

![](https://373113018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FO5oY9g3h48cclwOChrGD%2Fuploads%2FIweTGxU4fEbJ3LubgDUJ%2FScreenshot%202024-05-19%20at%2018.59.58.png?alt=media\&token=67ce1a70-2096-4310-81e6-c74a70cddbe2)

</details>

## Customisation

And you can always add a new one by implementing <mark style="color:blue;">**IFormation**</mark>.

The interface is very simple, you get a number of units to position and then formation must return positions relative to `Vector3.zero`. Translating positions to world space is done by `FormationPositioner` utility class, which is used by other components.

```csharp
public interface IFormation
{
    List<Vector3> GetPositions(int unitCount);
}
```

If unit count and returned list size do not match, *errors are expected*.