diff --git a/Custom-campaigns.md b/Custom-campaigns.md index 7d1a735..e63885a 100644 --- a/Custom-campaigns.md +++ b/Custom-campaigns.md @@ -18,6 +18,8 @@ Breaking campaign changes to do not get documented on the wiki immediately, but The campaign uses a JSON file to describe some metadata. To create a new campaign, add a JSON file (such as `mycampaign.json`) to `resources\campaigns`. +**Note:** as of DCS Liberation 5 the campaign descriptor file may also be written in YAML with the same structure. + This json file should contain a json object, with the following parameters : * `name`: The name of the campaign that will be shown in the New Game wizard. @@ -26,13 +28,46 @@ This json file should contain a json object, with the following parameters : * `description`: A description of the campaign that will be shown in the New Game wizard. * `version`: The version of the campaign format this campaign was built for. This supports a UI hint in the new game wizard to warn users about campaigns that were built for an incompatible version of the game. - Note that this field is **not** the DCS Liberation version, but the version of the campaign file format. The latest version is defined by `CAMPAIGN_FORMAT_VERSION` in [game/version.py](https://github.com/Khopa/dcs_liberation/blob/develop/game/version.py). **For DCS Liberation 3.0 the campaign version is 6.0.** + Note that this field is **not** the DCS Liberation version, but the version of the campaign file format. The latest version is defined by `CAMPAIGN_FORMAT_VERSION` in [game/version.py](https://github.com/Khopa/dcs_liberation/blob/develop/game/version.py). **For DCS Liberation 4.1 the campaign version is 8.0.** If `version` is not set or is `"0"`, the campaign is from an unknown version of the game and will be marked as incompatible in the new game wizard. * `recommended_player_faction`: The recommended player faction (will be automatically selected by default on the faction selection page) * `recommended_enemy_faction`: The recommended enemy faction (will be automatically selected by default on the faction selection page) * `miz`: The name of the miz file (in the same `resources\campaigns` directory) that describes the campaign. * `performance`: How much performance your campaign need to run smoothly (3 for biggest scenarios that will have huge impact on game performance, 0 for the smallest, performance-friendly scenarios) +* `squadrons`: Defines the default squadron configuration at the beginning of the campaign. Explained in the next section. + +### Squadron configuration + +**This feature is new in DCS Liberation 5 with campaign version 9.0** + +In DCS Liberation 5 campaigns define the starting squadron configuration for each coalition using the `squadrons` field of their campaign description. This field has the following format: + +``` +"squadrons": { + BASE_NAME_OR_ID: [ + { + "primary": PRIMARY_TASK, + "secondary": SECONDARY_TASKS, + "aircraft": PREFERRED_AIRCRAFT + }, + ... + ] +} +``` + +* `BASE_NAME_OR_ID`: The name of the base (in the case of a FOB, LHA, or CV) as defined by the group in the campaign miz file, or the ID number of the airfield as defined by pydcs. For example, [the ID of Anapa-Vityazevo is 12](https://github.com/pydcs/dcs/blob/4b3eb77507de6c4796251830682e154c4710da82/dcs/terrain/caucasus.py#L9). Refer to the pydcs source for airbase ID numbers. +* `PRIMARY_TASK`: Defines the primary task type for the squadron. If none of the preferred aircraft are available, a squadron will be generated using an aircraft that is capable of at least the primary task type. The allowed values here are the same as the values of the task types in `FlightType` found in https://github.com/dcs-liberation/dcs_liberation/blob/develop/gen/flights/flight.py (the same as the name of the mission type shown in the Liberation UI). +* `SECONDARY_TASKS`: Defines secondary tasks that the squadron will be allowed to perform if the squadron is capable of them. This can be either the literal strings `any`, `air-to-air`, or `air-to-ground`, or a list of specific task types. This property is optional. If not specified the auto-planner will only assign those squadrons to the primary task type. +* `PREFERRED_AIRCRAFT`: A list of either aircraft type names (using the same names as [custom factions](https://github.com/dcs-liberation/dcs_liberation/wiki/Custom-Factions)), or a list of squadron names. Each name will be tried in order and the first option valid for the coalition will be selected. If no preferred aircraft are compatible with the coalition, a squadron will be automatically generated based on `PRIMARY_TASK`. + +For a complete example, see the [Black Sea campaign description](https://github.com/dcs-liberation/dcs_liberation/blob/develop/resources/campaigns/black_sea.yaml). + +When choosing preferred aircraft, although the property is optional, it is best to pick at list at least one aircraft that is valid for the default faction configuration of your campaign to ensure that your campaign's out-of-the-box behavior works as you expect. You can list *any* aircraft here if you want to cater to non-default factions. For example, if your default faction for the player is USA 2005 but you want to provide good defaults for Russia, you can use `"aircraft": ["F-15C Eagle", "Su-27 Flanker-B"]` and the squadron will fly F-15s when the US is chosen and Su-27s when Russia is chosen. + +**Not every airbase needs squadrons.** Use the positioning, quantity, and roles of each squadron to control the size and pace of your campaign. You don't need to provide a squadron for every aircraft type, but in general you should ensure that a squadron is capable of the major task types (BARCAP, CAS, SEAD, Transport, AEW&C, and Refueling). Players can customize their squadrons at game start (note: it currently is not possible to *add* squadrons or change aircraft types, but squadrons can be removed at game start and task preferences may be changed at will), so it is most important that you set up your default squadrons the way that makes the most sense for your campaign. + +A best practice to follow is to set up one base per side as a transit hub. This is preferably a large airfield near the rear of the conflict (not easily captured or destroyed), that has the ability to produce ground units (has a factory), has a cargo aircraft squadron, and optionally has a port. Depending on the location of this base it may also be a good home for AEW&C and refueling squadrons (and a BARCAP squadron to defend those other squadrons). ## Designing campaigns in the mission editor @@ -55,6 +90,8 @@ To create an LHA, follow the same process but place an LHA-1. Note that the presence of the carrier or LHA in the game will depend on the player's options and the faction's navy. +**New in DCS Liberation 5:** Campaign version 9.0 uses the carrier or LHA's group name to determine which squadrons should be located at the base by default. See the earlier section about squadron presets for more information. + #### Off-map spawns To create a point where aircraft from other theaters can be spawned into the mission in-air, place an F-15C. As with carriers and LHAs, use CJTF Red or Blue to assign the point to either faction.