ExtendedContracts.md

Extended Contracts

In addition to existing Raids and Attacks, there are now "extended contracts", as defined by ExtendedContractType and ContractOverride definitions. These are loaded via modtek, like other things that modtek can load. Though similar in some ways to Flareups, extended contracts do not use / track combat forces, nor do they appear on the map or have lasting effects on the galactic stage.

Extended Contract Types

Extended Contract Types are defined each in their own json files, loaded as any other ModTek resource. Any mod can include them by having a entries in its mod.json similar to

"Manifest": [
  { "Type": "ContractOverride", "Path": "contracts" },
  { "Type": "ExtendedContractType", "Path": "extendedContracts" }
]

All the top-level properties explained below are required. See the included Garrison Duty.json for an example.

• The name is displayed to the player in various ways as the contract progresses.

• This type of extended contract can only spawn if companyRequirements is met. StarSystem scope requirements are checked against the location of the extended contract, not against the player's current location.

• hireContract is the ID of the contract WIIC will use to let the player get involved - you need to create this, see the contracts/ folder for examples. This is always spawned as a travel contract, and no combat drop will occur.

• When WIIC decides to spawn a extended contract, it does so based on their weights. Higher weights are more likely to be selected.

• If travelContracts is true, then WIIC will generate a travel contract in the command center, pointing the user to fly to the system and get involved. If false, then a contract in the command center is only generated when the user arrives in this system.

• If blockOtherContracts iis true, then WIIC will disable all contracts in the command center while the player in participating; only contracts generated by the schedule will be available. The exception is contracts offered by factions in settings.json under neverBlockContractsOfferedBy - those factions are, you may be unsurprised to hear, never blocked.

• Relatedly, if mapMarker is defined, then WIIC will create a pulse on the galaxy map at the EC's location. Note that you cannot customize the system description (as Attacks/Raids do), so there's no way to indicate to the user what the pulse means; thus the vast majority of Extended Contracts should have "travelContracts": true, and no mapMarker set.

• employer is an array of one or more strings, with exact meaning determined by spawnLocation. See below.

• Each ExtendedContractType has a spawnLocation, which describes the relationship between the owner of the star system and the employer. Each combination is explained below.

  • spawnLocation: Any, employer: [Allied]: The extended contract can spawn on any world. The employer will be any faction faction the player is allied to.

  • spawnLocation: Any, employer: [Any] is not valid.

  • spawnLocation: Any, employer: [OwnSystem]: The extended contract can spawn on any world. The employer will be the system owner.

  • spawnLocation: Any, employer: [ClanJadeFalcon]: The extended contract can spawn on any world. The listed faction will be the employer.

  • spawnLocation: NearbyEnemy, employer: [Allied]: The contract can spawn on any world controlled by an enemy of a faction the player is allied with. The employer will be the player's ally.

  • spawnLocation: NearbyEnemy, employer: [Any]: The contract can spawn on any world whose owner has an enemy that controls a system within one jump. The employer will be an enemy of the system owner (that controls a world within one jump).

  • spawnLocation: NearbyEnemy, employer: [OwnSystem] is not valid.

  • spawnLocation: NearbyEnemy, employer: [ClanJadeFalcon]: The contract can spawn on any world controlled by an enemy of the given faction and within one jump of a world controlled by the faction. The listed faction will be the employer.

  • spawnLocation: OwnSystem, employer: [Allied]: The extended contract can spawn on any world whose controller is allied to the player. The system owner will be the employer.

  • spawnLocation: OwnSystem, employer: [Any]: The extended contract can spawn on any system whose owner is not in ignoreFactions / wontHirePlayer. The system owner wyll be the employer.

  • spawnLocation: OwnSystem, employer: [OwnSystem] is not valid.

  • spawnLocation: OwnSystem, employer: [ClanJadeFalcon]: The extended contract can spawn on any world controlled by the listed faction. They will be the employer.

  If multiple employers are listed, WIIC will consider all possibilities and select one at random. Eg, spawnLocation: OwnSystem, employer: [Comstar, Allied] will spawn at a system owned by Comstar or any faction the player is allied with.

• And finally, there is target - this is determined after the employer and system are chosen, and is an array of one or more of:

  • Employer: The OpFor will be the same as the employer.
  • NearbyEnemy: The OpFor will be a randomly chosen enemy of your employer that control a system within one jump.
  • SystemOwner: The OpFor will be the whoever owns the system.
  • A faction ID (eg. ClanJadeFalcon). The target will be this faction, even if they don't control any systems in the area.

• availableFor determines how long the travel contract will be available, min and max days. Once it expires, the extended contract disappears, never to be seen again (unless the player has accepted the travel contract and is already en-route).

• schedule is an array of strings, each one referencing an item in entries (see below). These occur each day in order, and when the player reaches the end, the extended contract is over.

• entries is an object of "day definitions", expanding on what each entry in the schedule means. These objects have a large number of options, described below in their own section.

entries

Each entry is defined by an ID (the key, used in the extended contract type's schedule to say when this entry occurs), and a value with a large number of possible properties. All properties are optional - just leave out any that you don't need. An entry of {} is perfectly valid.

The first entry occurs immediately upon accepting the extended contract - it's "Day 0".

• workOrder is an optional string. While the extended contract is running, the first upcoming entry with a workOrder is shown to the user in the timeline; Use this to notify them of upcoming events / provide a greater sense of "actually doing something" to the player. It has no mechanical effect.
• triggerEvent is an array of event IDs. Starting at the beginning, WIIC finds the first event with matching conditions and triggers it. If an event triggers, then everything else that could happen on the day is ignored - no contract or reward will be generated. If none of the events' conditions match, other properties will be checked as normal.
• If no event occurred, here is a contractChance chance that a contract will be offered to the player on this day. 0.5 = 50% chance, 1 = 100% chance. This defaults to 0 - if you want a contract to spawn, set it! The rest of the options control what sort of contract will be generated.
  • Only define ONE OF contract, randomContract, allowedContractTypes. Multiple options will be ignored.
  • contract: A list of contracts to choose between in order, ignoring planetary difficulty but respecting each contract's requirementList (unless ignoreContractRequirements is set). If empty or not present, then a contract will be chosen by vanilla logic (respecting allowedContractTypes below).
  • randomContract: A list of contracts to choose between at random, ignoring planetary difficulty but respecting each contract's requirementList (unless ignoreContractRequirements is set). If empty or not present, then a contract will be chosen by vanilla logic (respecting allowedContractTypes below).
  • ignoreContractRequirements: If set true, then the contract's requirementLists are ignored (see above). Has no effect on contracts chosen randomly via allowedContractTypes.
  • allowedContractTypes: A list of contract types the extended contract will select between. If the list is empty or not present, then any contract type (including those from vanilla and in WIIC's settings.json customContractEnums) is valid. Useful Vanilla contract types:
    • AmbushConvoy: 15
    • Assassinate: 10
    • CaptureBase: 7
    • CaptureEscort: 8
    • DefendBase: 11
    • DestroyBase: 6
    • Rescue: 9
    • SimpleBattle: 3
    • FireMission: 50
    • AttackDefend: 53
    • ThreeWayBattle: 52 Mission Control contract types (may be out of date / incomplete, but included here for reference):
    • SoloDuel: 10000
    • DuoDuel: 10001
    • Blackout: 10002
  • contractPayoutMultiplier: Pay for this contract is multiplied by this amount.
  • contractBonusSalvage: Added to the salvage this contract pays out. Can be negative. The final value will be clamped between 0 and 28 (so as not to break the UI).
  • contractMessage: A string to display in the popup offering the mission to the user. You do not need to explain the declinePenalty in here - WIIC will display that to the user separately. This can contain HBS madlib replacements, such as {TEAM_EMP.FactionDef.ShortName} and {TGT_SYSTEM.Name}. Notably, you can also access the contract itself under {RES_OBJ.Name} and {RES_OBJ.ContractTypeValue.FriendlyName} and similar.
  • If the player declines a generated contract, they're given the declinePenalty, which is one of:
    • No declinePenalty defined: No penalty for declining.
    • BadFaith: Reputation penalty as if they'd performed a bad-faith withdrawal.
    • BreakContract: Declining this mission terminates the Extended Contract as if the player had flown away.
  • If the contract is accepted and completed, then if postContractEvent is defined, this event will replace the contract objectives on the after action report screen.
• If no contract triggered, then any popupMessage will display. This is a "system alert", similar to the way ECs / flareups offer contracts (though there's only one button, "Continue", rather than accept / decline. The string will be mad-libbed; you can use COMPANY, COMANDER, TGT_SYSTEM, TEAM_EMP and TEAM_TARGET to fill in text.
  • popupTitle will be used if present, otherwise WIIC will use the name of the extended contract type for a title.
  • Sumire is always the one speaking. Sorry, being lazy right now and I like her.
• Finally, if no event and no contract triggered, rewardByDifficulty gives a reward to the player, based on the half-skull rating of the planet - they will receive the highest value they met or exceeded. For example, if on an 8 difficulty world, WIIC will look for 8, then 7, 6, etc. until that key exists and give them that.
• invokeMethod is developer-only, and its usage requires writing C# code. An explanation is beyond the scope of this documentation; ask BlueWinds on the BTA discord or read the code.

Generating Extended Contracts

Each day, after checking for flareups and raids if there are fewer than maxAvailableExtendedContracts available, WIIC decides if it should generate a new one. If there are currently no extended contracts available, it uses dailyExtConChanceIfNoneAvailable as the chance. If one or more already exist, it instead uses dailyExtConChanceIfSomeAvailable.

• If it decides to offer the player a new extended contract, it generates a list of all the extended contract types for which the player qualifies (based on their companyRequirementss), weighted by their weights, and picks one.
• Builds a list of all valid employer and location pairs, as described by spawnLocation and the employer array. These are weighted by the distance multiplier, as Flareups: 1 / sqrt(distanceFactor + distanceInLyFromPlayer), and limited to systems within maxExtendedContractDistance ly from the player. Systems near the player are more likely to be chosen than those far across the map.
• Finally, it determines the target of the contract based on the target array.