TW:WH Script Mod: Creating your custom script.

This guide shows you how to create a self contained custom script, maximising mod compataibility and reducing the risk of breaking vanilla scripts.

Preface:

I would recommend you utilise my newer guide. It documents script creation using a more robust method created by CA. 
I will leave this up becuase it still works - and may be used for niche scenarios.

This is not an in-depth guide on scripting, but will cover enough to get you started. This guide assumes you understand the basics of Total War modding and are looking to delve into scripting.

As such, you should understand how to create and edit pack files and be willing to do your own research into scripting fundamentals.

I should also take a moment to recognise Uriak, who originally proposed this method for script modding on the official forums and deserves the credit for it: Link here[forums.totalwar.com]

Introduction:

Script mods for Total War are very powerful. They allow you to do a large array of specific commands at specific moments or ‘Events’.

Unfortunately, unlike the table edits of regular mods, scripts are entirely contained entities and so editing a vanilla script makes your mod completely incompatible with any other mod who also edits that script.

As such this guide is here to help you create your own custom script to maximise compatibility and reduce the risk of your mod breaking the game.

But Why?

• Custom scripts massively reduce mod script conflicts by being self-contained.
  
• Custom scripts massively reduce the risk of breaking vanilla scripts by being self-contained.
  
• By being self-contained – your mod becomes more transparent – ensuring your changes are not hidden away amongst the masses of vanilla scripts.

Where do script files live in a pack file?

Total war script files are Lua script files and so have the .lua externsion. They are stored in a pack file under the script directory.

There are a number of sub folders in here and I would recommend you take the time to look through them – these should be a primary resource when looking at creating scripts.



Note that while many scripts are stored in data.pack, there are a few extra scripts associated with Mortal Empires in the data_gc.pack file too.



Note that the type of scripts this guide will show you to make will all live directly in the script directory.

Editing a lua file.

Script editing is at its core, text editing. I would recommend you use a tool like Notepad++ (although the editor you use is ultimately up to you).

The advantage of using an editor like this over, say notepad is:

• You can set the language to lua – which will recognise and colour code commands.
  
• It can help you with correct formatting (tabulating).
  
• Has nifty tools like line numbers, collapsing statements and MUCH more.

Click to expand.


With this tool you can edit vanilla scripts, or create your own from scratch.

Create the new script.

First things first, create your new file. Right click to create a new text file then, when renaming it do so as below.

 export_helpers__[MODNAME]_script.lua

Be sure that the file is now a .lua file and not a .txt file

Note: It doesn’t matter where you do this, but I would recommend you do so in a new folder you set up specifically to hold working files for your mod.

An explanation on the strict naming convention

Normally you need to “inject” your own created scripts by calling them within a vanilla script using a line such as..

required(modname_script.lua)

The drawback to this is that you have still edited a vanilla script, and as such any other mod which edits that script will not work with yours.

Expanation ends.

By naming your script as above (using the export_helpers_ prefix), you avoid this situation because the game engine automatically loads all export_helpers_ scripts. Thus you have a self-contained custom script for maximum compatability.

Building a script initialiser.

Although the game will automatically load your script – you still need to tell it how/when to initialise your script, that is – hit the ‘play’ button for your script. There are many ways this can be done, but this guide recommends you do so in the following way.


This will execute your start function at the start of a game, after a number of vanilla scripts. Note that this code also identifies the campaign so that if you want your script to only run for a specific campaign, you can.

Start function and the rest of your script.

Alas, this is where the scope of this guide ends. Start functions, events, conditions and listeners is a topic for another guide.

However until that guide is released, you should take a look at the vanilla scripts and other mod scripts to give you a pointer in the right direction.

Caveat & alternate method

Please note, there are some limitations with this script method that might require you to use an alternate system. I will return and edit this list as more limitations arise.

• cm:add_loading_game_callback() command is called before this script will initialise and so does not work, thus rules out saving/loading global variables in a manner used in vanilla scripts.

[Flamboyant Schemer61]

@thesniperdevil Thanks for the answer.

[IfThenOrElse]

@Flamboyant, you can get that information (and more) on the CnC discord channel. https://discord.gg/8HSp2p (locatred in the modding_resources channel

[Flamboyant Schemer61]

Thanks a lot for the guide, it really helps a lot. I have a dumb question though. Is there a place where I can see all the events like the scripts we are writing? I mean there is an event.lua in data, but it doesn't contain any codes, and it says "Automatically generated via export from C:/Users/Build\DaVE_local\branches/warhammer2/coast/warhammer/raw_data/db". I don't know where that is, and how can I go there and start digging events. If you can help me it would be great

[phazer]

Can you please show me a link to a reference to the game functions callable from .lue scripts? Thanks in advance.

[shaky_rivers]

No worries, thanks for the reply and all your great mods too.

[IfThenOrElse]

Hey Shaky, afraid not :(

[shaky_rivers]

Thank you for making all these great guides, I've got a quick question can settlement names be edited via a script?

[IfThenOrElse]

You might want to join up to the CnC modding discord https://discord.gg/ - the folks there might be able to help. Also, jsut to keep the comemnts section clean and related to the guide - I'll be deleting the previous comments - so don't take offense :)

[IfThenOrElse]

np - be sure to check the newer one out - it uses a slightly better system that CA created with TK update!

[Tomread]

thanks a lot for the guide