Main Index
This is the front page for the guide to scripting in Total War. On the page below you will find useful links to get you started. Welcome!
This documentation is split into four major sections.
- The main pages of this documentation, such as the page you are currently viewing, feature a light grey navigation bar and presents information relevant to all scripting environments. Links to documentation concerning specific scripting environments are shown in the Game Areas section of the navigation bar when viewing one of the main pages.
- Pages related to battle feature a light blue navigation bar and present information related to battle scripting.
- Pages related to campaign scripting feature a yellow navigation bar.
- Pages related to frontend scripting feature a pink navigation bar.
When viewing a page within a particular environment the main homepage of this documentation can be reached by clicking the Scripting Homepage link that is shown at the top of the navigation bar.
Links to other pages within the same environment are shown within the Code Pages, Script Pages or Script Topics sections of the navigation bar. Pages are sometimes duplicated betwen environments where appropriate.
The On This Page section on the navigation bar lists sections on the page currently being displayed.
Scripts are programmatical instructions that may be loaded and run by the game in order to modify its behaviour. Scripts are easier to read and write than game code, but execute more slowly and are limited in what game information they can access. By writing scripts, designers can do complex logical tests on the game state and then execute instructions based on the results of those tests.
Scripts in all Total War games since Empire have been written in Lua, version 5.1. This is a fast and lightweight interpreted language that is commonly used in videogames.
More information about the language is given on our dedicated page about Lua here: lua.
You may also learn about the language by following tutorials on lua-users.org. Follow the link to the Tutorial Directory on this page: http://lua-users.org/wiki/LuaTutorial
The official Lua 5.1 reference manual may be found at the following page. It is thorough, albeit daunting for the uninitiated: http://www.lua.org/manual/5.1/manual.html
Finally you may wish to bookmark this page, which allows you to try running fragments of Lua without having to install an interpreter: https://www.lua.org/demo.html
There are three main game environments in Total War games: the frontend, campaign and battle. All three support running Lua scripts in the background to modify game behaviour. There are many similarities in the way scripts work in these three environments, although there are many differences also. You may visit the homepages for each of the three main game modes here:
There is a fourth script environment which runs when the game is executed in autotest mode. Autotest scripting is beyond the scope of this documentation. Help should be sought elsewhere if you are unfortunate enough to find yourself in the position of needing to write autotest scripts!
The game can notify scripts of changes in the state of the game by triggering script events. Scripts can listen for these events by registering lua functions to be called when a particular event occurs in order to respond to changes in the state of the game. Examples of available events include FactionTurnStart, PanelOpenedCampaign, CharacterCreated and ComponentLClickUp. In addition to triggering the event and calling the registered script listeners, the game also provides a context object to each listener which may be queried by the listener script to find out more information about the event.
For more information about script events see the dedicated page here: scripted_events
Each game environment - frontend, battle and campaign - provides interface objects to which the script may make calls to query or modify the state of the game. For more information see the frontend_index, campaign_index and battle_index pages.
The core object is available in all game environments and can be used to query or modify information that crosses game modes (such as advice, difficulty level, and tweaker states).
The script libraries also provide significant extra functionality and quality of life improvements in each of the game modes.
Lua scripts can write text output to various debug console spools. These output spools are written to a series of tabs on the game console during development.. Be sure to check this console output while debugging scripted content to gain a better understanding of what the script is doing.
Script output can be enabled in the release version of the game, where no console is available, by create a file in the root of the data/script folder called enable_console_logging. If this file exists, all console output from script is written to a text file in the game's binaries folder.
For more information about outputting to the console see here: Output
The UI provides significant support for scripts to query or modify the state of uicomponents, which are the building blocks of the user interface. The UI hierarchy of uicomponents may be browsed in script, and, once a handle to it has been obtained, the state of an individual uicomponent may be queried or modified through the uicomponent interface. The ui scripting interface is provided in all game environments.
More information about UI Scripting may be found here: ui_scripting
Scripts can be run in multiplayer mode, although there are significant considerations that must be taken into account when creating multiplayer script in order to make script multiplayer-safe. Script that is not multiplayer-safe may diverge when run on different machines in the same game, which can cause a desync.
Check the UI scripting homepage here to read more information about creating multiplayer-safe scripts.