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 |
|
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.
Script data relating to quest chains is set up in this script file, which lives in data\script\campaign\%campaign_name%\ for each campaign.
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.