Principle

Frustrated that your home country is not a possible choice in DCS Retribution, or annoyed that an aircraft is missing in your favorite faction? Good news, you can now mod factions in Retribution!

And these custom factions can be created easily with a text editor as a yaml or json file (prefer yaml for new factions).

You can find the default factions included in Retribution in the \resources\factions\ folder within the Retribution install directory. If you have created your own custom faction files and wish to place them in a more permanent location, you have the option of placing them instead in the DCS folder itself, by creating a folder call "Factions" (Retribution will read faction files from either location). This would be the same location that is listed as your "DCS Saved Game Directory" under File > Preferences in Retribution. As an example, it would likely be C:\users\<your username>\Saved Games\DCS.openbeta\Retribution\Factions\ or C:\users\<your username>\Saved Games\DCS\Retribution\Factions\.

If there is no error, your custom faction will appear in the New Game Wizard. Please note that factions saved in your DCS saved games folder will appear at the bottom of the list and not in alphabetical order.

If there is an error with the file it will not appear, please check the content of the console output, it might contain hints about the error. First, please verify the yanl/json syntax is valid.

File format

This yaml or json file should contain the following fields:

country : The country to be used in DCS. Careful, if it is not a valid country name in DCS, the mission generation will not work.
name : Name of the faction in DCS Retribution UI
locales : List of locales to use when generating random pilot names once predefined names are exhausted (if the field is left empty, "en_US" is used by default)
aircrafts : List of Aircrafts available to this faction
awacs : List of AWACS planes available to this faction
tankers : List of Tankers planes available to this faction
frontline_units : List of units that will fight on the frontline
artillery_units : List of artillery that will fight on the frontline
infantry_units : List of infantry units that will fight on the frontline
logistics_units : List of units used for logistics
air_defense_units : List of anti air units and ewrs
missiles : List of missile units (not used yet)
requirements : List of required mods for this faction to work
preset_groups : List of preset ForceGroups which can be used to add multiple related units at once (will be used for complex groups like SAM Systems)
naval_units : List of naval units like Carriers, Destroyers or Cruisers
carrier_names : List of possible name for carriers (will be picked randomly if there is more than one)
helicopter_carrier_names : List of possible name for helicopter carriers (will be picked randomly if there is more than one)
has_jtac : Whether this faction has access to jtac
jtac_unit : Type of unit to use as JTAC.
doctrine : Either "modern" for modern doctrine, "coldwar" for coldwar doctrine, or "ww2" for WW2 doctrine. Doctrine controls the altitude of flights and other flight planner AI parameters.
building_set : Either "default" for default set, "ww2ally" for WW2 ally buildings, "ww2germany" for WW2 german building or "ww2free" for a ww2 building set that does not require the WW2 asset pack.
liveries_overrides : List of aircraft and liveries to set. It is possible to have multiple liveries for aircraft, and Retribution will pick one out of the list randomly. The livery must be available to the country set in order to appear. If the livery doesn't show up in Mission Editor for that country, it won't show up in your Retribution mission either. The name of the livery can be found in its description.lua (if it's not there, then use the exact name of the livery's folder).
unrestricted_satnav : Enable this option to allow unrestricted SATNAV in the mission. This will allow the use of GPS by non-US countries, e.g. non-US F/A-18s will be able to use GPS for alignment. This value is optional and may be either true or false. If not set this defaults to false.

Note:

I highly recommend you look at the default files provided in DCS Retribution for examples. All parameters have default values, so you do not have to set them all up necessarily.

When changing a livery, if an aircraft is a Core DCS aircraft or module such as the MiG-19P, the livery must be in the Modules Liveries section and not your Saved Games folder.

It is recommended, that your faction has access to all unit types, e.g. at least one tank, one IFV, one APC and so on in order for the auto purchase option for the player and the AI to work.

Aircraft, ground unit und naval names

Ground, naval, and air units in the faction file use the name of the unit in Retribution rather than the name in DCS.

The names used are taken from the variants section of the unit info files in the resources/units directory. For example, units/aircraft/FA-18C_hornet.yaml contains the following:

variants:
  CF-188 Hornet: {}
  EF-18A+ Hornet: {}
  F/A-18C Hornet (Lot 20): {}

In this example, there are three variants of the DCS F/A-18C Hornet unit. These "variants" are name only. The DCS unit type will be the F/A-18C module, but the name in the Retribution UI will be whichever variant is named in the faction file. This allows a Spain faction to pretend that an EF-18A+ is available in DCS.

Ground units use the same format, but are located in resources/units/ground_units. The same applies to naval units which are defined in resources/units/ships

Preset Groups

Ground and naval objectives (as opposed to front-line units) are defined using preset groups.. All available preset groups are located in resources/groups. They can be added to the faction by adding the name from the preset group in the list preset_groups. All units from the preset group will then be available to the faction. A more detailed description of the preset groups and the new layout system can be found in the corresponding wiki page.

name: Patriot # This name will be placed in the faction json
tasks:
  - LORAD
units:
  - SAM Patriot STR
  - SAM Patriot CR (AMG AN/MRC-137)
  - SAM Patriot ECS
  - SAM Patriot C2 ICC
  - SAM Patriot EPP-III
  - SAM Patriot LN
layouts:
  - Patriot Battery

Example file

Below is an example of a factions file :

{
  "country": "USA",
  "name": "US Navy 2005",
  "authors": "Fuzzle",
  "description": "<p>A modern representation of the US Navy/Marine Corps.</p>",
  "locales": [
    "en_US"
  ],
  "aircrafts": [
    "F-14B Tomcat",
    "F/A-18C Hornet (Lot 20)",
    "AV-8B Harrier II Night Attack",
    "AH-1W SuperCobra",
    "S-3B Viking",
    "SH-60B Seahawk",
    "UH-1H Iroquois"
  ],
  "awacs": [
    "E-2C Hawkeye"
  ],
  "tankers": [
    "S-3B Tanker"
  ],
  "frontline_units": [
    "M113",
    "M1043 HMMWV (M2 HMG)",
    "M1045 HMMWV (BGM-71 TOW)",
    "M1A2 Abrams",
    "LAV-25",
    "M163 Vulcan Air Defense System"
  ],
  "artillery_units": [
    "M270 Multiple Launch Rocket System"
  ],
  "logistics_units": [
    "Truck M818 6x6"
  ],
  "infantry_units": [
    "Infantry M4",
    "Infantry M249",
    "MANPADS Stinger"
  ],
  "preset_groups": [
    "Hawk",
    "Patriot"
  ],
  "naval_units": [
    "FFG Oliver Hazard Perry",
    "DDG Arleigh Burke IIa",
    "CG Ticonderoga",
    "LHA-1 Tarawa",
    "CVN-74 John C. Stennis"
  ],
  "missiles": [],
  "air_defense_units": [
    "SAM Hawk SR (AN/MPQ-50)",
    "M163 Vulcan Air Defense System",
    "M48 Chaparral"
  ],
  "requirements": {},
  "carrier_names": [
    "CVN-71 Theodore Roosevelt",
    "CVN-72 Abraham Lincoln",
    "CVN-73 George Washington",
    "CVN-74 John C. Stennis",
    "CVN-75 Harry S. Truman"
  ],
  "helicopter_carrier_names": [
    "LHA-1 Tarawa",
    "LHA-2 Saipan",
    "LHA-3 Belleau Wood",
    "LHA-4 Nassau",
    "LHA-5 Peleliu"
  ],
  "has_jtac": true,
  "jtac_unit": "MQ-9 Reaper",
  "doctrine": "modern",
  "liveries_overrides": {
    "F-14B Tomcat": [
      "VF-142 Ghostriders"
    ],
    "F/A-18C Hornet (Lot 20)": [
      "VMFA-251 high visibility"
    ],
    "AV-8B Harrier II Night Attack": [
      "VMAT-542"
    ],
    "AH-1W SuperCobra": [
      "Marines"
    ],
    "UH-1H Iroquois": [
      "US NAVY"
    ]
  }
}

Annex - Possible Aircraft

Warning: this list is probably incomplete and wrong. It is not kept up to date when Retribution changes. If you want the truth you have to look at the YAML files shipped with the version of Retribution you're using.