Updated Squadrons and pilots (markdown)

Squadrons-and-pilots.md

@@ -2,15 +2,17 @@
 
 This feature is a [work in progress](https://github.com/dcs-liberation/dcs_liberation/issues/276). This documentation will be improve as the feature nears completion.
 
-## Players
+## Pilots
+
+### Players
 
 Each pilot can be set as either a player or AI pilot. Instead of creating client slots in flights as in previous versions of Liberation, pilots are set as players and those pilots are assigned to flights.
 
-## Skill level
+### Skill level
 
 AI pilots gain skill after completing missions. Every four missions completed confers one increase in skill level from the base level chosen in the campaign settings.
 
-## Pilot names
+### Names
 
 Pilot names are generated randomly (user-defined names will be added later). The generated names are localized based on the `locales` field of the faction definition. For example:
 
@@ -23,4 +25,58 @@ Pilot names are generated randomly (user-defined names will be added later). The
 
 Names will be localized if the chosen locale has a `faker.providers.person` listed on https://faker.readthedocs.io/en/master/locales.html.
 
-If the faction has no locales defined, names will be generated using `en_US` (the default for the name generator library).
+If the faction has no locales defined, names will be generated using `en_US` (the default for the name generator library).
+
+## Squadrons
+
+### Predefined squadrons
+
+Predefined squadrons are loaded from `resources\squadrons\*\*.yaml` (for built-in squadrons) and from `<DCS saved games directory>\Liberation\Squadrons\*\*.yaml` (for user-defined squadrons).
+
+The directory name within the squadrons directory is not important; it's just to allow organizing the squadron files. For example:
+
+```
+<squadron directory>
+    hornet/
+        VFA-113.yaml
+        VFA-122.yaml
+    skyhawk/
+        VFA-113.yaml
+```
+
+Here is an example squadron definition file:
+
+```yaml
+---
+name: VFA-113
+nickname: Stingers
+country: USA
+role: Strike Fighter
+aircraft: FA-18C_hornet
+livery: VFA-113
+mission_types:
+  - Anti-ship
+  - BAI
+  - BARCAP
+  - CAS
+  - DEAD
+  - Escort
+  - Intercept
+  - OCA/Aircraft
+  - OCA/Runway
+  - SEAD
+  - SEAD Escort
+  - Strike
+  - Fighter sweep
+  - TARCAP
+```
+
+The country and aircraft fields will be used to match squadrons that are found against the squadrons being used. The country should be spelled exactly as it would be in a faction file. Factions that use Combined Joint Task Forces nations will have access to all squadrons with matching aircraft. The aircraft should match the key (the value in quotes) of the aircraft found in `plane_map` in https://github.com/pydcs/dcs/blob/master/dcs/planes.py or `helicopter_map` in https://github.com/pydcs/dcs/blob/master/dcs/helicopters.py
+
+The `role` and `mission_types` fields are currently non-functional. The `role` field will later be shown in the UI as information for the player and the `mission_types` field will be used to determine which mission types to assign to the squadron. The spelling of each entry in `mission_types` should match the spelling of the mission that is used in the Liberation UI.
+
+The `livery` field, if set, will be the livery used by all aircraft of this squadron. It should match the name of the livery in game.
+
+### Generated squadrons
+
+A squadron will be generated for any aircraft that does not have any predefined squadrons available.