Lua TGWAI Scripting System

The Great War AI scripting system manages control of all common tactical environment activities related to the mission, and allows direct access to AI functionality. Features can also be overwritten in Lua for more specific control. You can find the core functionality for the system in \pglua\AI\EventManager. lua and the basic set of scripts in \lua\AI\data\EVENT_LIBRARY.lua. After adding a script you can utilize it by including it in the list at the bottom of the appropriate AI data file (for example, \current\lua\AI\data\ATTACK.lua houses all standard scripts for German Attack operations in skirmish and campaign).

Overview

By default the tactical AI always runs in the background. In standard skirmish or campaign play, the AI conducts all offensive and defensive actions using its built-in system. In scripted historical missions it commonly handles creating new reinforcements, allocating them to defensive trenches, and it also coordinates enemy targeting actions for all companies while relinquishing control of attack and defense coordination to the scripting system. It is further possible to disable the defensive default reinforcement entirely, and control specifically when and where all new companies arrive.

The Script Environment

All missions require a series of elements for operability:

A mission environment map created in the editor or selected from one of the premade maps.
Instance data for the mission set up in Instances.xml, which indicates the available corps/companies for the mission as well as other important parameters.
Trench templates which list the various prebuilt trenches that will be present in the map environment for the player and AI.
A mission script which contains basic data for the mission such as names of specific map control points, and a series of script events to conduct the mission.

This document focuses on the map data and mission scripting system, with specific instructions for building your own scripts.

Mission Script Data

The mission script data file (commonly located at Lua\AI\data) is a table comprised of the following sections:

Allocations: An indication of what percentage of AI supply is reserved for prebattle versus battle, and a list of spawn ratios for each company type you make available in the instance data. If the AI is used to spawn companies by default, it will use this table to determine the ratio of each type of company it spawns, in a randomly chosen distribution.
Air Missions: A list of the names of the various types of player balloons, enemy balloons, and enemy air missions which will be encountered. This list generally doesn't need to change from what is shown in the default data files for the appropriate side (ATTACK.lua for German, ATTACK_ALLIES.lua for Allied).
Attack Targets: The default order in which control points will be engaged. Usually your control points are listed first, to ensure they are recovered before attacking enemy points. This primarily affects companies which have completed a capture objective and are allowed to continue engaging other control points as a default action thereafter, they will check control points in this order.
AttackTargeting: Copying the default tables listed in ATTACK.lua or ATTACK_ALLIES.lua will cover all the standard unit types. This table tells companies and spurs what targets to shoot at in default order, if they are allowed to attack said target types. Note that companies may sometimes not respect this strict ordering of attack priorities, as it is occasionally overridden depending on the current battle situation.
AI Control Parameters: This series of parameters controls specific aspects of the AI, allowing you to modify its functionality to suit the mission needs. Each is explained in the section below. Script Events: This is the meat of your mission scripting, using the standard event scripting system. A list of events to be included can be pulled from the common event

AI Control Parameters

In the mission data file, various AI control parameters can be included which directly affect the way the AI operates in the mission environment. Not including a variable in your data file will leave it at its default value. Note that most of these values can be changed by a scripted event during the live missions, to alter game play on the fly.

DisableDefense: Defaults to false. Set this to true to prevent the AI from calling in defensive reinforcements. This value cannot be modified during play.
DefensePulse: Defaults to 5. The number of seconds between defensive system reinforcement check cycles. This controls how often the AI will attempt to pull additional reinforcements if low.
MinNumberDefenders: Defaults to 10. When requesting companies for an attack force from the AI, this is the minimum number of defensive companies it will try to retain despite your request.
SupportManualAttackersAfterCapture: Defaults to true. Companies which are given attack orders will continue to attack further targets in order of the Attack Targets in the mission script data, as described above. Companies will stop moving after capturing if this is disabled.
AvoidDangerousTrenches: Defaults to false. If you are letting the AI handle bringing in reinforcements, set this to true to have it avoid placing new reinforcements in trenches near enemies, with a few uncommon exceptions.
AggressiveRallying: Defaults to false. Forces the AI to bring reinforcements in at captured control points for more aggressive rallying on the enemy side.
UseTrenchPathfinding: Defaults to false. Causes companies to move toward enemies by using the trench network, with pathfinding solves over a longer distance. Companies are likely to enter trenches to approach targets where possible.
RetreatWoundedCompanies: Defaults to false. Regulated by game difficulty, this adds a chance of a company retreating if it is significantly wounded, with higher difficulties more likely to withdraw the company earlier to avoid losses.
DeprioritizeBalloons: Defaults to false. Set this to true to have companies put balloon trucks as their lowest priority target, ignoring trucks until other targets are cleared. Used in some tutorial situations.
ReinforcementTargetingDelay: Defaults to 40. Arriving player reinforcements which are only spotted by balloons will not be shot at by artillery until this amount of seconds has expired. Immediate spotting by companies, spurs, or approaching the command trench default vision radius does not respect this timer.
TrenchPreferredGarrisonAmount: The preferred amount of companies desired in a trench during battle, defaults to 1. Set this to 2 to encourage more doubling in trenches.
TrenchPreferredGarrisonOnAllocation: In prebattle, this value is used to regulate the preferred amount of companies desired in a trench. Defaults to the garrison amount value above (1).
MaxActiveTanks: If the AI is controlling reinforcements, this is the maximum amount of tanks it tries to target for the battle at any given time. It will refrain from building more if it detects too many, with a few exceptions. MaxPopulation: Defaults to the AI's maximum population count. This allows you to set it lower if needed.

Scripted Events

Scripted events are a combination of triggers and actions, implemented in the format indicated below. When all triggers for an event can simultaneously return 'true' the actions in the event are activated. The available triggers and actions are described below. In addition, an EventLibrary of common script events is available for inclusion (as shown in the LIBRARY_EVENT_NAME example below), or used as a reference when creating your own.

Events = {
  EVENT_NAME = {
    Name = "EventName",
    enablePrint = true,
    Triggers = {
      {
        Trigger = "TRIGGER_NAME",
        SetTargets = true,
        Parameter = value,
        enablePrint = true,
      },
    },
    Actions = {
      {
      Action = "ACTION_NAME",
      Parameter = value,
      enablePrint = true,
      },
    },
  },
  EventLibrary.LIBRARY_EVENT_NAME,
}

Common Parameters

One parameter is available to all triggers and actions: enablePrint = true/false. This activates debug print output for the trigger or action.

All scripted event triggers have SetTargets = true/false, to allow the trigger to collect targets for the following actions to use.

All scripted event actions have MinDelay = 1, Delay = 2, AdjustDelayByDifficulty = true/false, RepeatCount = 1, RepeatDelay = 1 as available parameters for setting a minimum and maximum variable delay before activating the action, and an option to adjust the delay by game difficulty which adds 0/10/20/30/40 seconds to the delay (the least being the hardest difficulty). Additionally, the action can be repeated if possible, with a separate delay in seconds imposed between repeat attempts.

Scripted Event Triggers

Triggers are conditions which must be met for affiliated actions to occur in an event. All triggers must return true for the event actions to occur.

Some triggers relate to game objects in the environment. These have the option of setting 'targets' which are then available to the actions in the event. Using multiple triggers which all collect targets will step on each other when they activate. The parameter SetTargets = false will stop a trigger from collecting targets, allowing you to choose which trigger provides the target list. Note that some target lists are cleared when an event trigger is reset. Reset is commonly called after the actions are fired for the event.

Below are descriptions of the available triggers and their various parameters.

ENABLED

Activates when the event is enabled. Events can be enabled and disabled during tactical play. This naturally triggers when the tactical battle begins, if the event starts Enabled = true.

Enabled = true/false: Set to false to have this event start disabled. It can then be enabled later by the ENABLE_EVENT action.
ForceResetOnEnable = true/false: Clear targets and reset triggers for the event when enabled.

LAST_FIRED

A time delay trigger which allows for looping events, or preventing events from happening too rapidly (by ensuring a time delay between activations).

InitialWait = true/false: If true, the event waits Time seconds and then activates automatically, allowing for looping of the event if no other triggers prevent actions.
Time = 1: The number of seconds to wait before activating again. Until this time is met the event is considered inactive.

BEGIN_ATTACK

Activates when an attack signal is received from the tactical AI after completion of a MANUAL_ATTACK scripted event action.

TriggerChance = 1.0: A chance from 0 to 1 for the trigger to not fire when receiving the attack signal.

COMPANIES_IN_NOMANSLAND

Activates when a number of companies enter the no-man's land region of the tactical map. Sets targets to the detected companies.

Player = "PLAYER" or "ALL" or "OWN": Which companies to respond to. TriggerChance = 1.0: A chance from 0 to 1 for the trigger to not fire.
MinCount = 1: The minimum number of companies in no-man's land this signal should activate for.
MaxCount = 1: The maximum number of companies in no-man's land this signal should activate for.

COMPANIES_IN_REGIONS

Activates when a number of companies enter a specified region of the tactical map, Sets targets to the detected companies. This trigger might slow the game if used too liberally (for example, checking all regions for all companies).

Player = "PLAYER" or "ALL" or "OWN": Which companies to respond to.
Regions = {"REGION_NAME" or "OBJECT_NAME"}: A table of region names, and/or control point object names (including command trenches) which are affiliated with regions.
TriggerChance = 1.0: A chance from 0 to 1 for the trigger to not fire. MinCount = 1: The minimum number of companies in the regions this signal should activate for.
MaxCount = 1: The maximum number of companies in the regions this signal should activate for.

BALLOON_CHANGE

Activates when the player's balloons raise or lower. Sets the targets to the balloons.

TriggerChance = 1.0: A chance from 0 to 1 for the trigger to not fire.
Value = "Added" or "Lowered": Whether the trigger reacts to raising or lowering of the balloons.

ARTILLERY_FIRED

Activates when the player fires artillery. Sets the target to the artillery which fired.

TriggerChance = 1.0: A chance from 0 to 1 for the trigger to not fire.

AIR_MISSION_LAUNCHED

Activates when the player launches an air mission. Sets the target to the aircraft.

TriggerChance = 1.0: A chance from 0 to 1 for the trigger to not fire.

RALLY_COMPLETE

Activates after successful completion of a MANUAL_RALLY scripted event action.

TriggerChance = 1.0: A chance from 0 to 1 for the trigger to not fire.

REINFORCEMENTS_CALLED

Activates when the AI calls reinforcements on to the map. Sets targets to the joining companies.

TriggerChance = 1.0: A chance from 0 to 1 for the trigger to not fire.

CONTROLPOINT_CHANGE

Activates when a control point is being contested. Sets the target to the control point.

__ControlPoints = "ALL" or "OWN" or "ENEMY": Which control point types to track for this particular trigger. Use a control point name to isolate this to a specific point.
EventType = "Attacking", "Reinforcing", "Captured": The type of capture event to activate for.

VARIABLE_CHANGED

A mission specific variable has changed. Actions are allowed if values return a positive result. Ensure the Name of each checking event is different or they will overwrite timers.

Variable = "VariableName": The name of the variable in the data set to monitor.
Operation = "EQUAL" "HIGHER" "LOWER" "NOTEQUAL" "EQUALORHIGHER" "EQUALORLOWER"
Value = 1 or "VariableName": The value to compare the variable to.

DIALOG_COMPLETE

Activates when a dialog box is closed. Dialog boxes (barks) are defined in XML.

Dialog = "NAME": The dialog XML reference to look for.

ATTACK_FORCE_EMPTY

An existing AI attack force has been emptied. Ensure this is enabled after the attack force is created so it can find the attack force.

ForceName = "Name": Attack force name to check.

Scripted Event Actions

Actions occur when all affiliated trigger conditions are met for the event. An event can perform any number of actions. Targets for events are collected by the event triggers, and filtered by the SetTargets boolean in each.

ENABLE_EVENT

Enables or disables any specified event, allowing for chaining of events. Place the ENABLED trigger in an event to allow this action to function on said event.

EventName = "EventName" or table: The name of the event to enable or disable. Can also be this event. If a table of event names is used, one is chosen randomly ({"EVENT",}).
Enabled = true/false: To activate or deactivate the event. Defaults to TRUE.

REQUEST_ARTILLERY

A 'hands off' method of handling artillery, commonly used by the tactical AI. Calls for artillery strikes of certain styles, and let's the internal system handle the details. You can specify a spotter and target for a specific interaction. Leave out the target to let the system determine its own target related to the spotter. Leave out the spotter to let the system choose targets in a wider area instead of focusing on those around the spotter. Just specify a style of artillery to have the system fire at will. Specify no parameters for standard destruction bombardments anywhere. Any and all of the parameters below can be omitted.

Spotter = "NAME" or cObjectRef: A valid object which is used as the spotter for the artillery strike. Defaults to nil.
Target = "NAME" or cObjectRef: A valid object to fire the artillery at. Defaults to nil.
Style = "STYLE": The 'style' of the attack, defaults to DESTRUCTION:
- SUPPRESSION: Fire available suppression artillery attack at the specified target to reduce enemy fire from the target.
  - Specify just a spotter to suppress targets close to the spotter.
  - Specify nothing to let the manager choose a spotter and targets.
- DEMOLITION: Fire available barrage artillery at targets in the area of the target, focusing on clearing barbed and razor wire, with spurs as primary targets.
  - Specify just a spotter to demolish in an area closest to the spotter.
  - Specify nothing to let the manager choose demolition targets.
- DISPERSION: Fire available area denial artillery at the specified target to encourage the enemy to leave the area.
  - Specify just a spotter to disperse targets closest to the spotter.
  - Specify nothing to let the manager choose a spotter and targets.
- DESTRUCTION: Fire available destructive artillery at the specified target in an attempt to destroy it. Chooses abilities based on the target type.
  - Specify just a spotter to destroy the nearest target to the spotter.
  - Specify nothing to let the manager choose a target to destroy.
MaxFires = 1: Maximum number of artillery to fire. Defaults to 1.
RepeatCount = 0: Number of times to repeat this action.
RepeatDelay = 1: Delay between repeats. This delay is separate from the initial delay imposed above.
UseBalloons = true/false: Artillery will be deviated based on the number of intact AI balloons, compared to the number destroyed. More destroyed balloons causes artillery to target poorly. Defaults to false.
CheckSupply = true/false: Prevents firing is supplies are low, tactical AI tries to save enough supplies to reinforce defensive companies one time, about 100 supply. Defaults to false.
SpottedTargetsOnly = true/false: Only allows firing at targets which have been legally spotted by balloons or scouting companies. Defaults to false.
BalloonAwareness = 1.0: A chance from 0 to 1 to not fire artillery if no balloons are currently raised by the tactical AI. A binary toggle for artillery use. Defaults to 0.
Deviation = 0: A deviation range applied to the artillery shots, cumulative with other potential deviations.

FIRE_ARTILLERY

Fires artillery at a specified target, or the current targets gathered by the triggers for the event. A more specific method of handling artillery than the request action above.

SpecificTarget = "NAME"or cObjectRef: A valid target object to fire the artillery at. Defaults to nil.
Spotter = "NAME" or cObjectRef: A valid object to use as the spotter. This is primarily for artillery strikes like Rolling Barrage, which require orientation.
MinDelay = 1: Minimum amount of time to wait before activating, a way to delay artillery fire after the triggering of the event. Ensure your targets are not cleared if delaying artillery.
Delay = 1: Set both values to have a variable amount of delay.
RepeatCount = 0: Number of times to repeat this action.
RepeatDelay = 1: Delay between repeats. This delay is separate from the initial delay imposed above.
MaxFires = 1: Maximum number of artillery to fire. Defaults to 1.
ArtilleryType = "ARTILLERY_HEAVY" or "ARTILLERY_LIGHT"
Ability = "TYPE": Type of artillery ability to activate:
- HEAVY:
  - "UNIVERSAL_ARTILLERY_AREA_BARRAGE_ABILITY_ITEM"
  - "UNIVERSAL_ARTILLERY_GAS_ATTACK_ABILITY_ITEM"
  - "UNIVERSAL_ARTILLERY_AIR_BURST_ATTACK_ABILITY_ITEM"
- LIGHT:
  - "UNIVERSAL_LIGHT_ARTILLERY_SUPPRESSION_BARRAGE_ABILITY_ITEM"
  - "UNIVERSAL_ARTILLERY_ROLLING_BARRAGE_ABILITY_ITEM"
  - "UNIVERSAL_ARTILLERY_SMOKE_SHOT_ATTACK_ABILITY_ITEM"
FindTargets = true/false: Make artillery search the area around the primary target for other targets.
TargetRange = 1: Approximate area to search around the target for other targets.
SortTargets = true/false: Make artillery get targets by priority according to the target filter.
TargetFilter = {}: An optional table of target types used when targets are sorted. Others are rejected. The default filter is used is this is not specified.
UsePosition = true/false: Use exact position of target. False causes artillery to attempt to lead the target if it is moving.
UseBalloons = true/false: Artillery will be deviated based on the number of intact AI balloons, compared to the number destroyed. More destroyed balloons causes artillery to target poorly. Defaults to false.
SpottedTargetsOnly = true/false: Only allows firing at targets which have been legally spotted by balloons or scouting companies. Defaults to false.
BalloonAwareness = 1.0: A chance from 0 to 1 to not fire artillery if no balloons are currently raised by the tactical AI. A binary toggle for artillery use. Defaults to 0.
Deviation = 1: A value to apply to the artillery to cause it to deviate occasionally from the intended target position. Defaults to 0.

LAUNCH_AIR_MISSION

Launches an air mission of the specified type toward the current event target.

AirAwareness = 1.0: A random chance from 0 to 1 for the air mission to cancel if the player has active air superiority missions.

ADJUST_BALLOONS

Raises and lowers the AI balloons.

Raise = true/false: Raise or lower the balloons.
AirAwareness = 1.0: A random chance from 0 to 1 for the adjustment to cancel if the player has active balloon busting missions.

CALL_REINFORCEMENTS

Create reinforcements of a specific type. AI companies which can spawn are distributed to defensive trenches and made available for attack force creation.

Target = "NAME": a specific object to create reinforcements near, instead of distributing to trenches. Omit this for standard behavior.
Composition = {}: a table of object names for companies, with a number of each desired (i.e. COMPANY_INFANTRY_FRENCH = 10,). Omit for standard allocation.

Composition = {
  COMPANY_INFANTRY_FRENCH = 1,
  COMPANY_INFANTRY_BRITISH = 1,
}

MANUAL_RALLY

Tell the tactical AI to create a rally of attacking companies around a specified location. Companies are selected from the present defensive forces.

ForceName = "ForceName": A name for the attack force. Omit if an unnamed group is desired (not used for a later action).
Target = "NAME": A valid object to rally the companies around. Omit this to use the target gathered by the script event trigger.
Composition = {}: a table of object names for companies, with a number of each desired (i.e. "COMPANY_INFANTRY_FRENCH" = 10,).
StrictComposition = true/false: True if all of the composition above must be found before a group is formed. Fails if there are not enough to form.

MANUAL_ATTACK

Tell the tactical AI to send an attack force toward the target. After engagements are complete, attack forces will continue on to the next listed viable target in the Attack Targets list if SupportManualAttackersAfterCapture = true.

ForceName = "ForceName": The name of the attack force. If existing that attack force will be used instead of making a new one. = nil if a new, unnamed group is desired.
Target = cObjectRef: Any object with a coordinate position. Omit this to let the system choose the next viable attack target.
Composition = {}: A table of objects names for companies, used if no pre-existing attack force has been named in ForceName. Same convention as above.
StrictComposition = true/false: True if all of the Composition must be found before the group is formed.

RETURN_TO_DEFENSE

Returns an attack force to the defensive, for use in later attack forces. Companies will return to defensive trenches if they can.

ForceName = "ForceName": Name of the attack force to return.

ADJUST_DEFENSE

Tells the tactical AI to pull defensive companies closer to the average position of the script event targets, adjusting their defensive trench positions.

Target = "NAME": A specific target to adjust toward, which overrides the collected script event targets.
useNearestControlPointAsTarget = true: Use the nearest control point to the average position of all the current trigger targets. Uses the nearest defensive trench if this is false. Defaults to false.
TrenchRadius = 4000: The radius within which trenches are to be selected for filling by distant companies.
MaxNumberOfDefenders = 10: The maximum number of defenders required for filling the trench radius. If enough companies are present no more are called forth.
MaxNumberOfReinforcements = 10: The maximum number of reinforcements allowed to be pulled from other locations.
ReinforceRange = 10000: The maximum range at which distance companies will be called to this location.
AdjustExistingCompanies = false: If true, companies within the trench radius may adjust their positions to move closer to the target location if possible. Otherwise they stay in place.

SET_TRENCHES_DANGEROUS

Sets trenches in an area around the scripted event trigger target as dangerous for the AI companies, either for a short duration or permanently. This prevents the trench from being selected as a destination for reinforcements or some other minor situations.

Distance = 5000: The approximate radius of the area trenches will be set dangerous within.
Dangerous = -1: Set this to a positive value for a timed decay of dangerousness, and -1 for permanent danger. Set to 0 to clear dangerous trenches.

SET_VARIABLE

Allows you to set mission specific variables of your own naming, and check them later with the VARIABLE_CHANGED trigger.

Variable = "VariableName": The name of the local mission variable to alter or create.
Value = 1 or "VariableName": The value to apply to the variable. You can reference another data variable for the value. Uses numbers.
Addition = true: If true, the value is added to the current variable value instead of replacing it. Defaults to false (replacement).

SET_PARAMETER

Allows you to modify a game play data parameter for the AI. Be cautious with this as it can overwrite critical values.

Parameter = "ParameterName": The name of the gameplay data parameter in the game play data to alter.
Value = value: The value to apply to the variable. Set parameters according to their type to maintain functionality.

ACTIVATE_DIALOG

Activates a dialog box or 'bark'.

DialogName = "NAME": The name of the XML reference for the dialog to display.

START_STRATEGIC_EVENT

Starts a strategic campaign event, defined in XML.

EventName = "NAME": The name of the XML reference for the event to activate.

PREBATTLE_BOMBARDMENT

Calls for a number of days of prebattle bombardment. The AI must have siege weaponry available for this to operate.

Days = 1: Number of days of prebattle bombardment. Typically ranges from 1 to 4, 8 is the common maximum.

UNDERMINE

Conduct an undermining explosion at the target location. Omit a target to use the script event trigger provided target. AI must have undermining tech and supply available.

Target = "NAME": A specific location to fire the undermining explosion. Finds the nearest trench to the location which isn't near a control point.