A Beginner's Guide to Scripting & Scripting "How To"s

[Epistolary Richard]

This guide was developed from the research of several members of the modding community. The research thread can be found here

A BEGINNER'S GUIDE TO SCRIPTING

Scripting allows modders a way of changing the game’s mechanics in ways that are impossible by other means.

What is a script?
A script is simply a text file that contains series of commands, similar to those that can be entered into the RomeShell console.

There are two types of script, referred to as Campaign scripts and Show Me scripts.

Campaign scripts are scripts that are launched at the very beginning of a new campaign – the most famous example (and indeed the only one provided in the original game) is the Prologue script which runs throughout most of the Sons of Mars prologue campaign and controls much of the automated activity within it.

Show Me scripts are scripts that are activated by the player through the ‘Show Me How’ button on the advisor interface. They were intended to be used to help demonstrate how to do certain actions within the game, but they will run any script and can be used for the modder’s own evil purposes *bwa*ha*ha*ha*

Due to limitations on Campaign scripts (they only activate at the start of campaigns and you can’t save while one is running) they have only a few uses to the modder and so by far the most common kind of modded script is the Show Me script.

The most significant limitation on the Show Me script is that they can’t be run without the player’s consent (ie, if they don’t click on the show me how button then the script will never be run). But then why the hell are they playing a scripted mod if they’re not prepared to run the scripts in the first place?

In this guide, however, we’re going to walk-through a simple Show Me script (the Mo Money script) in order to familiarise ourselves with a script’s components and terminology.

Components of a Show Me script
A Show Me script is just a text file contained within the data\scripts\show_me\ folder, however to implement a script other components are required:
- a Trigger – contained within export_descr_advice.txt
- an Advice Thread – also contained within export_descr_advice.txt
- a Script – a text file itself contained within data\scripts\show_me\ folder

The Trigger tells the game what actions or events it should be looking for evaluating whether the advisor should appear.

The Advice Thread is a control which sets the number of times a trigger can be activated and other criteria before the advisor appears.

The Script is the series of commands which are run when the player clicks on the ‘show me how’ button in the advisor’s window.

For this example we’re going to work forwards through these steps, just to illustrate the process flow. When you actually come to making your own scripts it may be easier to work backwards or forwards through the steps.

Step One – The Trigger
The triggers are contained within the bottom section of export_descr_advice.txt. There you’ll find the 1,019 triggers that come with the basic game. Most of these are entirely useless to us and so we often have to define our own. In this case, however, we’ll be using a trigger that’s already there.

 ;------------------------------------------
Trigger 2137_Help_Campaign_Keyboard_Shortcuts_Scroll_Trigger
    WhenToTest ScrollAdviceRequested

    Condition ScrollAdviceRequested help_scroll

    AdviceThread Help_Campaign_Keyboard_Shortcuts_Scroll_Thread  0

This is just for your information at the moment; no adjustments need to be made as the trigger already exists. We’ll get into the technicalities of what the individual lines mean on another occasion. Suffice it to say that it should be obvious that this trigger is activated when the player clicks on the request advice button on the Help Scroll (otherwise known as the Keyboard Shortcuts scroll). This scroll can be accessed simply by pressing F1 during the game.

Trigger 2137 is very useful for testing out other components because it is slightly tucked away and therefore unlikely to be clicked during the course of play and it is completely within the player’s control. Press the request advice button once and the trigger will be activated once – so a modder can tell if the other components are working properly.

Step Two – The Advice Thread
The advice threads are contained within the top section of export_descr_advice.txt. They provide the connection between the trigger and the script that we want to run and determine whether the activation of a trigger actually results in the appearance of the advisor.

This is the normal version of the advice thread that is connected to Trigger 2137

 ;------------------------------------------
AdviceThread Help_Campaign_Keyboard_Shortcuts_Scroll_Thread
    GameArea Campaign

    Item Help_Campaign_Keyboard_Shortcuts_Scroll_Text_01
        Uninhibitable
        Verbosity  0 
        Threshold  1 
        Attitude Normal
        Presentation Default
        Title Help_Campaign_Keyboard_Shortcuts_Scroll_Text_01_Title
        Text Help_Campaign_Keyboard_Shortcuts_Scroll_Text_01_Text1

Again, we’ll have a look at this line-by-line on another occasion. The significant things to note here are the Advice Thread line at the top – which is how this Advice Thread is linked to the Trigger and also the Title and Text lines at the bottom which are refer to blurb contained with export_descr_advice_enums.txt.

But at the moment this advice contains no reference to a script and therefore we are going to have to add one.

This is the new version:

 ;------------------------------------------
AdviceThread Help_Campaign_Keyboard_Shortcuts_Scroll_Thread
    GameArea Campaign

    Item Help_Campaign_Keyboard_Shortcuts_Scroll_Text_01
        Uninhibitable
        Verbosity  0 
        Threshold  1 
        Attitude Normal
        Presentation Default
        Title Help_Campaign_Keyboard_Shortcuts_Scroll_Text_01_Title
        Script scripts\show_me\mo_money.txt
        Text Help_Campaign_Keyboard_Shortcuts_Scroll_Text_01_Text1

The only line we’ve added is the one that begins Script and this refers to our script text file that we are just about to place in the show_me folder.

Step Three – The Script
Create a new text file within data\scripts\show_me\ and copy and paste the following into it.

script
	console_command add_money 1000
	campaign_wait 5
	console_command add_money 1000
end_script

Then save the file as mo_money.txt
In case it’s not obvious, when activated this script adds 1,000 denarii to the player’s treasury, will wait for 5 seconds and then add another 1,000. Big whoop, but it does make it easy to tell when the script has been activated and so again is useful for testing other components.

Congratulations, you have now installed your first script. Launch a campaign as normal, then press F1 to get to the keyboard shortcuts scroll, click on Request Advice and the advisor should appear. Click on the ‘show me how’ button and the script should run as described.

NB - the full parameter for the add_money command is:

add_money (opt:faction) (amount)

so you can also specify which faction gets the money if you wanted to make it a reward for a mission (similar to a senate mission) or to represent a general time of prosperity or donations from clients or allies in times of distress.

More Scripting How tos
How to: Toggle Perfect Spy
How to: Create units ~ including unique units
How to: Capture Settlements
How to: Create Buildings
How to: Change the Date
How to: Spawn an Army



Scripting links
Events, Conditions & Commands - this is a list of all the Identifiers, Conditions and Events from files included in the RTW demo
Research: Parameters for commands & console commands - an attempt to compile a definitive list of command parameters
Console commands & command line options - this is a list of many possible console commands some of which can be used through scripting
Scripting research thread
Hot Seat Mod - Beta Release
More than two turns a year - release
Client Kingdoms expansion mod