XComStrategyGame.UPK (EU2012)

XComStrategyGame.UPK is a Unreal Engine 3 file used to determine several functions of XCOM: Enemy Unknown related to the strategic layer of the game. XComStrategyGame.UPK is divided into several classes, each related to different aspects of the Geoscape/HQ view and described below. The contents of this file can be visualized using UE Explorer.

A complete catalog of the file can be found here: Nexusmods wiki page on XComStrategyGame.UPK.

This page will focus on the practical aspects of the file and how they affect playing the game. For details on how to mod the game, you're advised to check the XCOM section at the Nexusmods wiki.

XGStrategyAI

XGStrategyAI contains most of the functions used to generate UFOs and missions, determine type and composition of alien squads, panic changes and so on. The class is further subdivided into Structures, Variables, Functions and and Default Values. The most important functions will be mentioned below.

AddAIEvent

AddAIEvent is used to add a game event (kEvent) to the array of events generated each month (THQEvent).

Each kEvent added to the array consists a mission, its target (country) and the number of hours it will be available:

• eMission
• eTarget
• iHours

GetEvents

GetEvents generates the array of events for each month (<THQEvent> arrEvents) and uses AddAIEvent to fill it.

It checks for several conditions:

• If iCouncilCounter > 0, it adds a Council mission to the array (11, m_iCouncilCounter / 2, 0)
• If the all the entries on the array of objectives (arrObjectives) are marked as completed it does nothing, otherwise for each uncompleted objective it adds a mission (eMission):
  • If objective is 0 (Recon) it doesn't add a mission.
  • If objective is 1 (Scout) then eMission = 3 (Crash)
  • If objective is 3 (Flyby) and HQ doesn't have Facility 18 (Hyperwave Relay) then eMission = 0 (None), otherwise eMission = 12 (DLC)
  • If objective is 4 (Hunt), eMission = 5 (HQAssault)
  • If objective is 2 (Harvest), eMission = 4 (LandedUFO)
  • If objective is 5 (Abduct), eMission = 2 (Abduction)
  • If objective is 6 (Terrorize), eMission = 7 (TerrorSite)
• If there's no last mission (for the month it calls function AddAIEvent(eMission, 0, byte(m_arrObjectives[iObjective].m_iCountryTarget), arrEvents)
• Otherwise, it calls AddAIEvent (eMission, (m_arrObjectives[iObjective].m_iNextMissionTimer - m_iCounter) / 2, byte(m_arrObjectives[iObjective].m_iCountryTarget), arrEvents)
• Function loops until all objectives have a mission added to the array of events

InitNewGame

Used when a new game is started.

• Defines the start date based on the value located on XGDateTime as 00:00:00, January 1st, 2015
• Sets the array arrUFOsShotDown with 10 entries
• Sets the array TObjectives with 8 entries
• Calls BuildObjectives function
• m_kResistance.arrCountries.Add(36);
• m_kResistance.arrNoResistance.Add(36);
• m_kResistance.arrHunted.Add(36);
• LogResistance(HQ().m_arrSatellites[0].iCountry);
• CreateAlienBase - sets location of Alien Base
• Defines TerrorCounter as 2
• If ISCONTROLLED() is negative (no Tutorial active) calls function AIAddNewObjectives

MakeMonthlyPlan

Calls functions EndOfMonth and AIAddNewObjectives

Update

Calls funcions AIUpdateMission and UpdateObjectives

UpdateObjectives

Function defines iNumUnits = 1 and bPaydayUpdate = false

• If each objective (kObjective) on the array arrObjectives hasn't been completed, it calls function Update
• If the array FirstBlitzTargets > 0 (used to define the targets of Abductions)
  • FirstBlitzCounter is reduced by 1
  • If FirstBlitzCounter <= 0 then starts LaunchBlitz and remove entry from array FirstBlitzTargets
• Calls World, FundingCouncil.UpdateSlingshotMission
• If the counter HQAssaultCounter > 0, it is reduced by 1
• if((m_iHQAssaultCounter < 2) && iNumUnits > 1) then m_iHQAssaultCounter = 2
• If the HQAssaultCounter is 0, and the Geoscape conditions isBusy and GetFinalMission are none, then AIAddNewMission(7, none)
  • Otherwise defines HQAssaultCounter = 1
• If PaydayUpdate is false, then calls function EXALT().UpdateObjectives(iNumUnits) and adds 1 to the Counter

CurrentlyHasObjective

For each kObjective on arrObjectives it sees if (GetType) is equal to the eObjective and if so, returns it as true. Otherwise returns false.

AddCouncilMission

Defines the Council counter used on GetEvents, using the values COUNCIL_DAY (20.0) and COUNCIL_RAND_DAYS (7.0) found on XComGame.UPK, XGTacticalGameCore. If the Tutorial isn't activated, the CouncilCounter is defined as:

• CouncilCounter = 20.0 * 48 (converts to half-hours)
• CouncilCounter + random number (7.0 * 48 *2) - random (7.0 *48)

AddHQAssaultMission

Sets counter for the Base Defense mission, using the values HQASSAULT_MAX_DAYS (21) and HQASSAULT_MIN_DAYS (14) found on XComGame.UPK, XGTacticalGameCore.

• HQAssaultCounter = random (HQASSAULT_MAX_DAYS - HQASSAULT_MIN_DAYS) + HQASSAULT_MAX_DAYS
• Multiplies final value by 48 to convert to half-hours.

AddLateMission

Used after the Alien Base is assaulted to add missions, generating the following integers: iNumCouncil, iNumTerror, iNumUFOs, iNumAbductions. It creates a local array of missions (arrMissions) then populates it according to the following:

• If there's no Terror (iNumTerror == 0) mission present, it creates 1 on the array arrMissions
• If there's no Council iNumCouncil == 0) mission present, it creates 1 on the array arrMissions
• If function DetermineBestAbductionTargets => 3, it creates 1 on the array arrMissions
• Roll for LATE_UFO_CHANCE is positive (50% odds) it adds 1 to iNumUFOs
• Afterwards it randomly chooses 1 mission type from arrMissions
  • If choice is 9 it calls functions AddNewTerrorMission and DetermineBestTerrorTarget and adds 1 to iNumTerror
  • If choice is 11 it calls functions AddCouncilMission and adds 1 to iNumCouncil
  • If choice is 2 it adds 1 to iNumAbductions

AIAddNewObjectives

Used by both the MakeMonthlyPlan and Update functions to generate missions using the following integers: iNumCouncil, iNumTerror, iNumUFOs, iNumAbductions.

• Checks for the game month (March = 0)
• If the condition ceil (month, 2) it calls AddCouncilMission and adds to iNumCouncil
• If the TerrorCounter is less or equal to 0 it calls AddNewTerrorMission and DetermineBestTerrorTarget, adds iNumTerror and resets the TerrorCounter to 2.
• Sets both iNumUFOs and iNumAbductions equal to 1
• If item 171 (Hyperwave Beacon) was ever present in storage it calls function AddLateMission
  • Otherwise adds iNumAbductions
  • If the month is April or May rolls for EARLY_UFO_CHANCE (50%), if successful, it adds again iNumUFOs for a 2nd UFO to appear during the month
  • It then runs AddNewAbductions and if the 2nd Abductions mission wasn't added, it adds +1 to iNumUFOs
  • It then ensures that the number of UFOs doesn't exceed the limit (2 UFOs), defined on UFO_LIMIT (on XGTacticalGameCore)
  • Creates an array of visible targets (with sats deployed) using DetermineBestVisibleTargets
  • Runs AddUFOs with the previously defined iNumUFOs and arrVisibleTargets
  • Runs AddNewOverseers

GetNumAbductionSites

Sets to maximum limit of Abductions sites to 3.

AddNewAbductions

• Uses DetermineBestAbductionTargets to determine how many possible target countries are present. If there's only 1 or 0 it doesn't add any Abductions.
• If the boolean FirstBlitz is positive, it calls CreateAbductionBlitz (arrAbductionTargets, GetNumAbductionSites(), 1 + Rand(7) and removes 1 from iNumAbductions
• Sets iAbduction = 0 and if(iAbduction < iNumAbductions)
  • Defines iNumTargets as the minimum value between the one defined by GetNumAbductionSites and the length of arrAbductionTargets
  • If the the length of arrAbductionTargets < 2, removes 1 from iNumAbductions
  • Otherwise:
    • If playing on the Tutorial the date for the first Abductions is set for the 24th
    • If not, the 1st Abductions can take place on the first 8 days (randomly chosen), and the 2nd Abductions on 11 + random 14
    • It then calls AddAbductionObjectives with (iNumTargets, iStartDate, arrAbductionTargets) already defined.

AddNewTerrorMission

• Sets iStartDate as 0
• Runs ClearFromAbductionList
• Randomly chooses a city from that country
• Runs AIAddNewObjective and adds entry with the following values (6, iStartDate, CITY(iCityTarget).GetCoords(), eTarget, iCityTarget);

AddHuntTarget

AddHuntTarget is used to add an UFO on a Destroy Satellite mission and to determine the UFO type, depending on the difficulty level.

• Checks IsCountryBeingHunted
• If difficulty <= 1 (Easy/Normal) then iMonthCutoff = 3 (June)
• If difficulty = 2 (Classic) then iMonthCutoff = 2 (May)
• Else (Impossible difficulty) iMonthCutoff = 1 (April)
• If the current month => iMonthCutoff then eHunter (UFO type) = 8 (Battleship)
• Otherwise eHunter (UFO type) = 5 (Large Scout)
• Runs AIAddNewObjective with the following values (4, Rand(5), HQ().m_arrSatellites[HQ().GetSatellite(eTargetCountry)].v2Loc, eTargetCountry, eHunter);

IsCountryBeingHunted

Determines if a country is being targeted for a Destroy Satellite mission.

• If the Type 4 objective (Hunt) on the array of Objectives hasn't been completed and CountryTarget = eTargetCountry returns true.
• If the Type 4 objective (Hunt) on the array of OldObjectives hasn't been completed and CountryTarget = eTargetCountry returns true.
• Otherwise returns false.

ChooseOverseerTarget

• Creates an array of targets (arrVisible) using DetermineBestOverseerTargets
• Randomly chooses 1 target from the array

AddNewOverseers

The propose of this function is a bit confusing. It is run by AIAddNewObjectives to add Overseer UFOs each month but with a different mission than the one revealed once the Hyperwave Relay is built.

• Checks if Storage ever had item 180 (Psi Link). If positive, it doesn't add any Overseers.
• Uses DetermineBestVisibleTargets to create an array of targets (arrVisible)
• Determines the number of Overseers to be added by choosing the minimum value between 3 and the length of arrVisible
• Sets iMission = 0
• If iMission < number of added Overseers:
  • If the game difficulty > 1 (Classic/Impossible) randomly chooses a country (eTargetCountry) from arrVisible and removes the choice from the array
  • Else, determines eTargetCountry using ChooseOverseerTarget
  • Finally, adds entry using AIAddNewObjective with the following values (3, 5 + (10 * iMission), Country(eTargetCountry).GetCoords(), eTargetCountry, 9) and adds 1 to iMission
• Repeats until iMission = number of added Overseers.

OnEtherealFlyby

This function is empty and it is only used by OnObjectiveEnded. Basically an Overseer overflying a country will not generate any additional mission.

MakeUFO

MakeUFO creates an entry called kUFO, composed of 2 values:

• eUFO (type of UFO, taken from the EShipType list on XComGame.XGGameData)
• eObj (UFO objective, taken from the EAlienObjective list on XGStrategyActorNativeBase)

FillUFOPool

This function uses both AddUFOToPool and MakeUFO to create a monthly pool of possible UFOs types for the Scout Target and Harvest Live Specimens objectives.

• March
  • AddUFOToPool(MakeUFO(4, 1))
  • AddUFOToPool(MakeUFO(4, 1))
• April
  • AddUFOToPool(MakeUFO(4, 2))
  • AddUFOToPool(MakeUFO(5, 1))
  • AddUFOToPool(MakeUFO(5, 1))
• May
  • AddUFOToPool(MakeUFO(5, 2))
  • AddUFOToPool(MakeUFO(6, 1))
• July
  • AddUFOToPool(MakeUFO(6, 2))
• August
  • AddUFOToPool(MakeUFO(7, 1))
• September
  • AddUFOToPool(MakeUFO(7, 2))
• October
  • AddUFOToPool(MakeUFO(8, 1))

eUFO = 4 (Small Scout), eUFO = 5 (Large Scout), eUFO = 6 (Abductor), eUFO = 7 (Supply Barge), eUFO = 8 (Battleship)

FillDatePool

Adds 2 dates to the array arrDates with the values of 9 and 16.

AddUFOToPool

Adds an entry (kUFO) to the array arrPool, with kUFO consisting of 2 values, eUFO and eObj.

ChooseUFOTarget

Chooses a country (iCountry) for a UFO mission.

• If arrCountries > 0 then makes a 75 roll.
  • If positive, the country chosen (iChoice) is the first entry on arrCountries
  • Else randomly chooses from all countries present on arrCountries
  • Sets iCountry as iChoice
  • If arrCountries > 1, it removes iChoice from the array
• If arrCountries = 0 it uses World.GetRandomCouncilCountry to determine iCountry

IsGoodUFOMissionChoice

Checks if the eUFO value on the kUFO different from the one used on the last mission. Used by ChooseUFOMissionTypeto prevent the same UFO type appearing on two consecutive missions.

ChooseUFOMissionType

Checks to see if the UFO alien crew is compatible with the type of UFO.

ChooseUFOMission

Used to determine the iUFOChoice value for ChooseUFO

• Defines iUFO = 0 and iCounter = 4
• If iUFO < length of arrUFOs then
  • If the entry on arrUFOs has eObj = 1 (Scout Target) it adds the iUFO value as item to arrShootDowns
  • All other entries with eObj different from 1 are added as items to arrLanded
  • Adds 1 to iUFO and repeats
  • Defines iUFOChoice = -1
• If iUFOChoice = -1 and iCounter > 0
  • If length of arrShootDowns > 0 AND a positive roll of UFO_INTERCEPTION_PCT (75%)
    • iUFOChoice is determined using ChooseUFOMissionType (arrShootDowns, arrUFOs)
  • If length of arrLanded > 0 AND iUFOChoice = -1
    • iUFOChoice is determined using ChooseUFOMissionType (arrLanded, arrUFOs)
  • If iUFOChoice is still -1
    • iUFOChoice is determined choosing randomly from arrUFOs

ChooseUFO

Creates UFOs, used by AddUFOs.

• Defines iUFOMission using ChooseUFOMission (using the arrUFOs generated by AddUFOs for the type)
• Defines iDateChoice randomly choosing a date from the arrDates created by FillDatePool
• Determines iCountry using the arrCountries generated by ChooseUFOTarget
• Adds to AIAddNewObjective an entry with the following parameters: arrUFOs[iUFOChoice].eObj, arrDates[iDateChoice], Country(iCountry).GetCoords(), iCountry, arrUFOs[iUFOChoice].eUFO)
• Sets the iChoice entry on arrUFOs as LastUFO
• Removes date and UFO type from arrDates and arrUFOs