Campaign Script Structure
By convention, the scripts for each campaign are laid out in standardised structure. This page describes that standardised structure. It is intended to be useful for understanding how campaign scripts are put together or for getting scripts working for a new campaign for the first time.
| Relevant in Campaign |
|
| Relevant in Battle |
|
| Relevant in Frontend |
|
From Warhammer onwards, all campaign scripts can be found in data\script\campaign\ (as well as data\script\_lib\, for library scripts related to campaign). This data\script\campaign\ folder contains a number of subfolders, all of which may contain script files. Script files in those folders should contain functionality related to their location in the folder structure:
| Folder Path | Comment |
script\campaign\ | Scripts potentially related to all campaigns in this project. |
script\campaign\%campaign_name%\ | Scripts related to a particular campaign. |
script\campaign\%campaign_name%\factions\%faction_name%\ | Scripts related to a particular faction in a particular campaign. |
Only those scripts required for the current faction and campaign are loaded, by convention.
Prior to Warhammer, campaign scripts were found in the data\campaigns\%campaign_name%\ folder.
In projects prior to Warhammer the campaign automatically executes a script file with the path data\campaigns\%campaign_name%\scripting.lua, should it exist. From Warhammer onwards, however, the first script that is run when a particular campaign loads can be customised in the relevant record in the campaigns table, in the script_path field. The file specified in this field is data\script\campaigns\%campaign_name%\scripting.lua, by convention.
By convention the script in scripting.lua loads the script libraries, uses get_folder_name_and_shortform to automatically determine the campaign name, sets this name on the campaign_manager with campaign_manager:set_campaign_name, adds the campaign folder to the require file path and then loads required.lua. If this convention is followed then the scripting.lua file can be identical from campaign to campaign.
The scripting.lua file loads the required.lua file. The purpose of this file is to load in other files from both the data\script\campaign\ and the data\script\campaign\%campaign_name%\ folders. Files in data\script\campaign\%campaign_name%\factions\%faction_name%\ are not loaded at this stage.
By convention, a script file called xx_start.lua is created in data\script\campaign\%campaign_name%\ for each campaign, where xx is a shorthand prefix for the campaign or project in question. This file is the start of the custom scripted behaviour for this campaign. It is responsible for loading faction-specific files when the game is created - see the Loading Campaign Script Files section of the campaign manager documentation for more information.
The xx_start.lua file is also responsible for registering functions to be called when the game is created or when the first tick occurs - see the First Tick section of the campaign manager documentation for more information about this.
It is common to add lots of additional functions to this file that start listeners and other processes when the campaign script loads up.
Unlike in battle, campaign scripts begin to load near to the start of the loading sequence. This is to allow scripts to be present while the save file (or startpos file) are loaded - the scripts can save values into the savegame when the game is saved and it is during the loading sequence that these values are read back out. Being loaded at such an early stage presents some complications, however, as the game model is not initialised until much later in the load sequence. If the script attempts to access or interrogate the game model before it's created then the game will crash. Care must be taken to ensure that this doesn't happen.
The standard script architecture put in place for each campaign attempts to ameliorate this issue by providing loading sequence processes with which callbacks to be registered. These registered callbacks will then be called at key points during the loading sequence when certain new elements of functionality become available.
Use campaign_manager:add_loading_game_callback to register a function to be called when the LoadingGame event is triggered. This happens early in the load sequence, before the model is created. Scripts may load values in from the savegame at this point but may not access the model. Other methods of loading information from the savegame exist - see the Loading Game section in the campaign manager documentation.
Use campaign_manager:add_pre_first_tick_callback to register a function to be called when the game and ui have been created. The campaign model may be queried after this point in the loading sequence. It is only at this point that the local faction can be identified and any faction-specific scripts loaded in.
Use campaign_manager:add_first_tick_callback or a related function (see the list available in the First Tick section) to register a function to be called when time in the game first starts ticking. This event is triggered once loading is finished and the game becomes interactive.
The campaign model (and hence the campaign scripts) completely shut down when the game loads from campaign into battle. From the perspective of campaign script the load back into campaign after a battle is (nearly) indistinguishable from being loaded from a savegame.
The following script files live in the root of the campaign folder at data\script\campaign\. They are loaded by all campaigns, by convention.
| Script filename | Comment |
xx_campaign_setup.lua | This file contains scripts and function that set scripts up across all campaigns. Traits, ancillaries and experience triggers are loaded in this file using the command campaign_manager:load_exported_files. |
xx_campaign_interventions.lua | This file contains advice intervention declarations by convention. |
xx_campaign_help_pages.lua | This file contains data related to the setup of campaign help pages |
Many additional files that define custom behaviour for a particular project are typically added to this folder alongside the files above.
The folder script\campaign\%campaign_name%\factions\%faction_name%\ contains files related to the local player's faction. Only the set of faction-specific files related to the local player's faction should be loaded, by convention - other script files in script\campaign\%campaign_name%\factions\ are not loaded.
The %faction_name%_start.lua is loaded first, by default, with the command campaign_manager:load_local_faction_script. It contains the bulk of the faction-specific script such as any intro camera pans. Other files in the faction folder may be loaded by this file using campaign_manager:load_global_script.