Lua Modding Documentation

Mod Support Lua Elements

New Campaign Lua

Strategic AI Tech Progression

Once the new campaign elements are established in XML, the appropriate technology progression for the AI must be included. All tech trees for the various campaigns can be found in lua\AI\Data\StrategicTechTreeData.lua, showing the order the AI will attempt to research. Add your own tech progression table there.

In lua\AI\TGWStrategicAI.lua near line 470 is the campaignInstances table. Add the new campaign instance name there and give it a unique number, or give it the number of another campaign to share the same tech progression. Next, around line 1160, you can change which tech tree is used based on the custom campaign number. Set self.EnforcedTechProgression = false to ignore the forced tech progression unlocks the AI normally utilizes.

By default, the AI adjusts its economic tech progression based on game difficulty, unlocks the espionage abilities, and forces research tech progression for showcase items at specific dates to ensure they are viewed by the player as the game progresses (siege weapons, undermining, gas, airburst, and concrete spurs). This accommodates the normally limited number of tech points combined with the need for showcase items to arrive by certain dates, such as tanks and tank missions in late 1916. Feel free to adjust these defaults if desired, starting around line 780. Note that tech cannot be initialized until the AI has been cleared to start by the game engine.

Campaign Events

The file \lua\MapScripts\FAR_STRATEGIC_EVENTS_FACTION_01.lua contains all the data for campaign events. Add your campaign name around line 90, and give it a unique number if you want to use a separate set of campaign events. Around line 350, you can add your unique number and indicate which three tables of events are loaded: the system loads a unique table based on the player faction (Allied/German) then adds a common table of events shared by both. Any or all of these can be modified. If you have hard choice events in your campaign and wish to display the results screen, add your campaign name to \UI\UI_StrategicEvent_HardChoice.lua, as some environments do not display hard choice results for particular reasons. If you have a campaign intro which plays immediately upon campaign start, add that around line 475.

If you are making new event tables, add them next to the others at the top of the file. Each event table has a series of event names from XML, and a set of parameters for the event:

• eventType: What type of event this is. System events are always shown, headline and historical events are chosen as priority notifications, objective and choice provide missions or hard choices, and regional events affect specific regions (like Holiday or Revolt). Weather events can also be called through the event system, but weather is handled separately by the strategic AI to regulate how many regions are affected on the active front line based on the season and difficulty.
• startTurn, endTurn: The possible starting and ending turns this event might occur within.
• active: Set this to false to initially disable the possibility of offering this event. Often accompanied by enemyResearch or previousResearch, below.
• enemyResearch: Activates this event if the AI researches this technology. previousResearch: Allows this event to be offered if the player has researched this technology already.
• research: Disables the possibility of offering this event if the technology is researched by the player, used to prevent offering missions which can no longer be completed.
• delay: Used for sorting the order in which events are displayed at the beginning of the turn, often to ensure hard choice events are at the end so they are adjacent to their results pane. This waits a number of seconds before showing the event.
• targetRegion, requiredRegions, priority: Used by PrimaryMission events exclusively. The targetRegion must be owned by the AI and the requiredRegions must be owned by the player for this event to occur. Only the highest priority available PrimaryMission events will be selected from, randomly.

Only one primary mission is offered at any time, and up to two other secondary missions may be offered. The various types of events are described below.

• Headline, Historical: Headline and historical events are displayed first, denoting significant occurrences during the campaign.
• System: System events are mandatory occurrences which often offer specific rewards, like the American corps arriving in late game.
• Regional: Regional events affect specific regions, usually chosen randomly. Examples are Black Market, Revolt and Holiday.
• Choice: Hard choice events are offered last in the event display sequence, as they have a follow-up event showing their results. These require the player to choose between two options.
• PrimaryMission: If conditions are available during the campaign, one primary mission is offered at a time. These are focused on capture of enemy regions to conduct larger operations, and are chained together in priority sequence to help encourage story flow.
• SecondaryMission: One or two secondary missions are also active at any time if the conditions for them are met. These are chosen from a larger random pool of missions, and focus on optional actions such as defeating specific enemy company types or researching tech.

Tactical AI

File Structure

The primary AI file \lua\AI\TGWAI.lua initializes all other systems. This file contains all the main control variables for the AI, and a standard list of object type definitions. This is the first file which runs when the AI is loaded.

If a data file for overriding parameters is not provided the AI uses one of the standard data files depending on whether it is currently attacking or defending: ATTACK.lua, ATTACK_ALLIES.lua, DEFEND.lua, and DEFEND_ALLIES.lua. These contain the default targeting priority and unit allocation tables used in tactical. At the end of these files are the specific parameters being overridden for the AI given the situation, and a series of scripting system events which handle all the standard AI operations.

The following additional files hold the majority of the AI's functionality:

• PreBattleManager.lua: Before battle, this system uses the provided trench template and allocated supply to purchase the trench layout for the AI side.
• DefenseManager.lua: This system regularly checks the defenses to determine if more reinforcements need to be called in. It handles all spawning and allocation of companies to trenches. The standard clock cycle for the defense manager update check is once every 5 seconds. This timer can be extended to have reinforcements arrive slower, or disabled to prevent further reinforcements. The DefensePulse value can be changed in data to a slower clock cycle and can be changed during run time.
• OffenseManager.lua: Two systems reside in the offense manager, one which runs every 2 seconds and handles targeting and order updating for all AI companies, the other which runs every 15 seconds and processes all offensive planning for the battle (evaluating control points to determine potential attack locations, planning assaults and ambushes, choosing rally locations etc.). The offense manager can be disabled entirely to avoid regular attack planning, allowing for scripted control of provided companies with the defense manager handling reinforcements. This is how all the historical missions operate as a standard - these standard AI cycles are handled through the event system and activated via the data files above, so omitting them prevents the AI from cycling normally.

These script events handle the offensive activity of the AI, as seen at the bottom of the ATTACK.lua file:

• OFFENSEMANAGER_UPDATE
• OFFENSEMANAGER_RALLY_COMPLETE_GERMAN (or ALLIES)
• OFFENSEMANAGER_RALLY_COMPLETE_INFANTRY
• OFFENSEMANAGER_RALLY_COMPLETE_ALL
• OFFENSEMANAGER_ATTACK_GERMAN (or ALLIES)

Primary AI Controls

Here are some of the primary AI controls, found in TGWAI.lua and overridden via the AI data files (\current\lua\AI\data\ATTACK.lua etc.). Many of the standard parameters, distances, and attributes for AI functionality can be overridden in this fashion, all are sorted at the top of the TGWAI file for readability.

• DisableAttack: Set to true to shut down the OffenseManager's planning and attack control. All companies will remain on defense until given specific orders to do otherwise.
• DisableDefense: Set to true to shut down the DefenseManager's spawning of reinforcements and allocation to trench positions. No new companies will arrive automatically.
• OffensiveMode: Set to true if the AI is to be on the attack, false if it is on the defense. DisableAttack must be false for this to have any impact, so the OffenseManager can conduct attacks.
• AllowTrenchSorting: Set this to false to deliberately build everything in the provided trench template in linear order. Set this to true to allow the AI to use the Prebattle Manager to sort the trenches and build according to its internal priorities.
• AvoidDangerousTrenches: Set this to true to help prevent the AI from filling trenches which have recently been marked as dangerous by other companies which died in them or spotted enemy companies nearby. Part of the systems which help prevent companies from spawning near the enemy.
• AggressiveRallying: Set to true if the AI is allowed to use enemy control points to aggressively rally. This is disabled internally by the AI if it detects Verdun fort turrets.
• UseTrenchPathfinding: When in trenches or near trenches, companies may use the trenches to move toward enemies at range if this is set true.
• RetreatWoundedCompanies: Set to true if the AI is allowed to withdraw wounded companies. The chance is dependent upon game difficulty, with a higher chance for higher difficulties.
• DeprioritizeBalloons: Set to true if the AI is to practically ignore balloon targets, or treat them as a last possible attack resort. For historical missions.
• SupportManualAttackersAfterCapture: Attack forces created through the scripting system will continue to assault other available enemy positions (control points) after achieving their primary objective, if this is set to true.
• SpawnReinforcementsAwayFromEnemies: Forces the AI to try to move the spawn position of companies away from combat range of enemies.

Adding New Companies

After establishing new companies in XML, they must be added to the AI to allow them to be recognized in battle. Locate the file \lua\AI\data\ModCompany Data.lua and add your new companies there.

Each parameter is distributed automatically to the proper place. For more detail on where these values are stored and what they affect:

• In each AI data file (ATTACK, DEFEND, etc.) if the unit is affiliated with the file's faction it must be added to the DefensiveUnits Allocations table, with a value indicating the frequency at which the object will be purchased in relation to all other company types in the table. If the unit is not affiliated with the file's faction it must be added to the default AttackTargeting table, and given a value for default targeting priority related to all other company types in the table.
• Next the AI needs to know the type of unit being added. In the standard TGWAI.lua add the unit to the ObjectsToTrack table, and assign it an object type from the types available (INFANTRY, INFANTRY_STORMTROOPER, TANK, TANK_LIGHT).
• To ensure the AI can spawn the new companies, add the count value from Attributes.xml to the InitializeReinforcementsData table in TGWAI. lua around line 650.

Finally the announcement manager (\pglua\Design\AnnouncementManager.lua) has various separate tables of object types for tactical announcements of various types (lost units, etc.). Add your unit to these tables if you need local announcements to function for your new companies.