Additional Lances

Additional enemy and ally lances will spawn based on contract type, biome type, faction reputation, allies/enemies, percentage chances, maximum limits and lance configs.

Additional enemy and ally lances can be spawned in all contract types based on contract type, biome type, percentage chances, maximum limits and lance configs. These are controlled by the files under config/AdditionalLances. There is a file for each difficulty level. A single difficulty level is the equivalent to 1/2 contract skull value so, for example, the file Difficulty6.json would be used if you select a 3 skull contract - if the game actually gives you a 3 skull contract. Often you get +/- 1 difficulty level so you may get a 5 (2 and 1/2 skulls) or a 7 (3 and 1/2 skulls) difficulty contract instead without realising it).

Lances are defined using a similar configuration to how they are defined in the contract .json files. They can be lances with specific mechs, or make use of tags for the game to select an appropriate lance. You can find some predefined lance files used by MC under the lances folder. You can create your own and they will be loaded. You can create a folder structure of lances for organisational purposes and they will be loaded without issue.

Settings Breakdown

"AdditionalLances": {
    "IncludeContractTypes": [],
    "ExcludeContractTypes": [],
    "LancePool": {
      "ALL": ["GENERIC_BATTLE_LANCE"]
    },
    "RewardsPerLance": [
      {
        "Type": "ContractBonusRewardFlat",
        "Value": "3000000",
      },
      {
        "Type": "ContractBonusRewardPct",
        "Value": "0.4",
      },
      {
        "Type": "ContractBonusEmployerReputation",
        "Value": "1",
      },
      {
        "Type": "ContractBonusTargetReputation",
        "Value": "-1",
      },
    ],
    "Enemy": {
      "Max": 2,
      "ExcludeContractTypes": ["Rescue"],
      "ChanceToSpawn": 0.4,
      "EliteLances": {
        "Conditions": ["IsEnemy"],
        "Suffix": "_Elite",
        "Overrides": {
          "ChanceToSpawn": 0.6
        }
      },
      "LancePool": {
        "ALL": [
          "GENERIC_BATTLE_LANCE"
        ],
        "CONTRACT_TYPE:DestroyBase": [
          "BRAWLER_LANCE", "DEFENDING_LANCE"
        ],
        "CONTRACT_TYPE:DefendBase": [
          "HEAVY_MISSILE_LANCE", "ATTACKING_LANCE"
        ],
        "BIOME:DesertParched": [
          "BBQ_MASTERS"
        ],
        "BIOME:LowlandsSpring": [
          "IM_LIKE_A_TURRET_IN_WATER_I_RUN_SO_HOT"
        ],
        "FACTION:Davion:50:99": [
          "Heavy_Davion_Battle_Lance"
        ]
      },
    },
    "Allies": {
      "Max": 1,
      "ChanceToSpawn": 0.4,
      "EliteLances": {
        "Conditions": ["IsAlly"],
        "Overrides": {
          "Max": 2,
          "ChanceToSpawn": 0.6
        }
      },
      "LancePool": {
        "ALL": [
          "GENERIC_BATTLE_LANCE"
        ],
        "CONTRACT_TYPE:DestroyBase": [
          "HEAVY_MISSILE_LANCE", "ATTACKING_LANCE"
        ],
        "CONTRACT_TYPE:DefendBase": [
          "BRAWLER_LANCE", "DEFENDING_LANCE"
        ]
      }
    }
  }
PathRequired?DefaultExampleDetails
IncludeContractTypesOptionalAll available contract types["Rescue", "DestroyBase"] would limit lances to these two contract types

[] would fallback to default		When set, it overrides ExcludeContractTypes for this level
ExcludeContractTypesOptionalNo contract types["Assasinate", "CaptureBase"] would remove these two contract types from the entire list of available contract types.

[] would fallback to default		Allows you to explicitly exclude additional lance spawns for all teams for the specified contract types. Not used if IncludeContractTypes is set
LancePoolOptionalALL situations will use GENERIC_BATTLE_LANCESee the above code as a full example.
Can match to ALL, CONTRACT_TYPE:{key}, BIOME:{key} and FACTION:{factionKey}:{startRepRange}:{endRepRange}		All matched conditions will be added to one list of lance pool keys. One key per lance spawn is selected at random for the specific lance. These lance keys reference the lances in the /lances folder. See Lance Definition Breakdown
RewardsPerLanceOptionalChildren defaults-Specifies which rewards to provide for every enenmy lance that the player destroys. Max 4.
EnemyOptionalChildren defaults-Controls enemy/target specific lance details
AlliesOptionalChildren defaults-Controls allies/employer specific lance details

RewardsPerLance

PathRequired?DefaultExampleDetails
TypeOptionalN/AContractBonusRewardFlat, ContractBonusRewardPct, ContractBonusEmployerReputation, ContractBonusTargetReputationReward type
ValueOptionalN/AValue for the appropriate type

Enemy or Allies

PathRequired?DefaultExampleDetails
MaxOptional13Maximum number of lances to attempt to spawn
ExcludeContractTypesOptionalNo contract typesSame as parent ExcludeContractTypesAllows you to specifically exclude additional lances for a team based on contract type
ChanceToSpawnOptional00.3Float number from 0 to 1 to represent percentage. 1 being 100%
EliteLancesOptionalNone-Specifies is elite lances should spawn based on set conditions
LancePoolOptionalEmptySame as parent LancePool exampleAdditive process. Adds to the parent LancePool

EliteLances

PathRequired?DefaultExampleDetails
ConditionsOptionalNone["IsAlly"]Checks if the player merc company is an ally or enemy to the faction. If this check is true then the settings specified in this object override the general settings. Can match IsAlly or IsEnemy
OverridesOptionalNone-Specifies the overrides to use if the Conditions return true

EliteLances - Overrides

PathRequired?DefaultExampleDetails
MaxOptional13Overrides the generic Max setting. Maximum number of lances to attempt to spawn
ChanceToSpawnOptional00.3Overrides the generic ChanceToSpawn setting. Float number from 0 to 1 to represent percentage. 1 being 100%

Lance Definition Breakdown

Lance definitions are defined in MissionControl/lances folder. Each .json file should be its own Mission Control lance. You can specify exact lances, or use tagged lances for the game to select an appropriate lance.

Each

{
  "lanceKey": "GENERIC_BATTLE_LANCE",
  "lanceDefId": "Tagged",
  "lanceTagSet": {
    "items": ["lance_type_battle"]
  },
  "lanceExcludedTagSet": {
    "items": []
  },
  "spawnEffectTags": {
    "items": []
  },
  "lanceDifficultyAdjustment": 0,
  "unitSpawnPointOverrideList": [
    {
      "unitType": "Mech",
      "unitDefId": "UseLance",
      "unitExcludedTagSet": {
        "items": []
      },
      "spawnEffectTags": {
        "items": ["spawn_poorly_maintained_50"]
      },
      "pilotDefId": "pilotDef_InheritLance",
      "pilotTagSet": {
        "items": []
      },
      "pilotExcludedTagSet": {
        "items": []
      }
    },
    {
      "unitType": "Mech"
    },
    {
      "unitType": "Vehicle",
      "unitTagSet": {
        "items": ["unit_vehicle_carrier"]
      }
    },
    {
      "unitType": "Mech"
    }
  ]
}
PathRequired?DefaultExampleDetails
lanceKeyRequiredN/AGENERIC_BATTLE_LANCEKey must be unique. It is used by the mod in the settings.json LancePools to specify the lance selection
lanceDefIdOptionalTaggedTagged, Manual or lance def id (e.g. lancedef_arena_light_fire)This specifies what type of lance this definition is. Tagged uses the lance tags to select an appropriate lance and Manual allows you to manually create a specific lance. If a specific lance def id is used then it ignores the units specified below and uses the full lance definition. lanceTagSet and lanceExcludedTagSet is ignored if a specific mech def id is set.
supportAutofillOptionaltrue-When set to false, if MC has Autofill set to true in ExtendedLances config, this specific lance config will not autofill to the specified EL lance size
lanceTagSetRequiredN/A"items": ["lance_type_battle", "lance_type_notallvehicles"]Allows the lance definition to specify what type of lance to select by tags
lanceExcludedTagSetOptionalNoneAllows the lance definition to exclude specific tags when selecting by tag
spawnEffectTagsOptionalNone"items": ["spawn_poorly_maintained_25"]Allows the lance definition to specify spawn specific tags that apply to the entire lance
lanceDifficultyAdjustmentOptional01+/- this amount for the lance difficulty
unitSpawnPointOverrideListRequiredN/AArray of lance members

unitSpawnPointOverrideList

PathRequired?DefaultExampleDetails
unitTypeOptionalMechMech, Vehicle or TurretType of lance member
unitDefIdOptionalUseLancemechDef_None, mechDef_InheritLance, vehicleDef_None, vehicleDef_InheritLance, turretDef_None, turretDef_InheritLance, Tagged or a specific mech def id (e.g mechdef_orion_ON1-K)Determines how the unit is selected. unitTagSet is ignored if a specific mech def id is set
unitTagSetOptionalNone"items": ["unit_vehicle_carrier"]Tags for selecting the unit if Tagged is selected
unitExcludedTagSetOptionalNoneAllows the unit definition to exclude specific tags when selecting by tag
spawnEffectTagsOptionalNone"items": ["spawn_poorly_maintained_25"]Allows the unit definition to specify spawn specific tags that apply to the specific lance member
pilotDefIdOptionalpilotDef_InheritLancepilotDef_InheritLance, UseLance, Tagged, pilot_default, pilot_commander or a specific pilot def id (e.g. pilot_d7_defender)Allows for selection system for pilots. pilotTagSet and pilotExcludedTagSet is ignored if a specific mech def id is set
pilotTagSetOptionalNone"items": ["pilot_npc_outrider"]Tags for selecting the unit if Tagged is selected
pilotExcludedTagSetOptionalNoneAllows the pilot definition to exclude specific tags when selecting by tag

API Access

The Additional Lances feature can be accessed and controlled by other mods via the Mission Control API. teamType is either enemies or allies to represent target or employer respectively.

Using MissionControl.Instance.API. you get the following AL methods.

PathParamsDetails
HasOverriddenAdditionalLancesteamType - allies or enemyReturns true or false if the AL lances for the team have been overridden with the API
GetOverriddenAdditionalLanceCountteamType - allies or enemyReturns the count of lances to be created as part of the overridden ALs
SetOverriddenAdditionalLancesteamType - allies or enemy

count - number of AL lances to set		Used to override the number of AL lances but allowing Mission Control to generate the lances with the usual AL rules
SetOverriddenAdditionalLancesteamType - allies or enemy

lanceOverrides - list of MC MLanceOverrides

objectiveNames - list of enemy objective names		Used to provide a list of MC MLanceOverrides to use for Additional Lances.

If objective names are provided they will override the default AL enemy objective names, if teamType is enemy. They are used in order and fewer can be provided if the modder only wants to override a single objective name, for example.
SetOverriddenAdditionalLancesteamType - allies or enemy

lanceOverrides - list of LanceOverrides

objectiveNames - list of enemy objective names		Used to provide a list of LanceOverrides to use for Additional Lances. Converted to MLanceOverrides internally.

If objective names are provided they will override the default AL enemy objective names, if teamType is enemy. They are used in order and fewer can be provided if the modder only wants to override a single objective name, for example.
GetOverriddenAdditionalLanceteamType - allies or enemyUsed to get the list of MLanceOverrides, no matter if set using MLanceOverride or LanceOverride API method

See the github feature page for more in-depth discussion.