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

[Epistolary Richard]

How to: Toggle Perfect Spy

toggle_perfect_spy was one of those frustrating commands that we were told could be used through the RomeShell console but it turned out that we couldn't.

Fortunately it runs perfectly well from a script. Use the below in place of the mo_money script in Step Three above.

perfect_spy.txt

script
	console_command toggle_perfect_spy
end_script

This command is of great use to modders who want to observe how the AI is reacting to their changes. toggle_perfect_spy allows you to look inside each banner and settlement and look at the troop composition and characters therein. It is best used with the toggle_fow RomeShell command which lifts the shroud from the campaign map.

[Epistolary Richard]

How to: Create units ~ including unique units

The Client Kingdoms mod uses this in order to generate the troops the player is offered though there are many, many other uses.

Here's a sample script:

script
console_command create_unit Campus_Scythii "barb infantry briton" 4
end_script

In this case when the script is activated 4 units of the Briton Warband will be created in Campus Scythii.

It need not necessarily be a settlement, you can also use a character name. This example comes from the Prologue script.

script
console_command create_unit "Gaius Julius" "roman velite" 2
end_script

RomeShell provide these parameters:

create_unit (settlement/character_name) (unit_id) (opt: how many)(opt: exp/armour/weapon)

Here's the relevant points
- the troop description corresponds to their Type line in export_descr_unit
- character names must be in "quotes", settlements not
- double or triple-barrelled settlement names must have an _ instead of spaces
- importantly, the troops become owned by whoever controls the settlement or the character's faction, there is no need for a faction to be able to build the unit or even have ownership in export_descr_unit.

This gives us the potential to have unique units appear not just at the beginning of the game but also as it progresses as you can trigger this script based on date, the capture of a particular settlement, the construction of a building or anything else specified amongst the event identifiers.

And as no changes are needed to export_descr_unit it means that custom battles and bribery are completely unchanged.

[Epistolary Richard]

How to: Capture Settlements

This script ousts whatever garrison is in the settlement and gives it to the local faction (ie, the player's faction)

script
console_command capture_settlement Londinium
end_script

It can be used in conjunction with the create_unit command to provide an instant garrison loyal to the player, or equally with a negative add_money that would represent the player purchasing the settlement or sponsoring an uprising.

Because this command only gives the settlement to the player, it can't be used on the player's own settlements.

[Epistolary Richard]

How to: Create Buildings

script
console_command create_building Londinium muster_field
end_script

The building name is referenced from the entry export_descr_buildings.

There are no limitations on which buildings can be given to which faction - even buildings which aren't normally available (such as Royal Barracks or Amphitheatres for the Britons). You can even have duplicate buildings.

Combined with a date trigger, this allows you to build a unique building at a specific time in the game and therefore could be used for "Wonder"-like buildings.

[Jason]

Ok please pardon my newbishness but I have never done a mod before and I am trying out what you have outlined here in this thread.

This btw was a very well written thread and I found it very easy to understand with only one problem. It doesnt appear to work for me. Im not sure why.

I have no other mods on my system, just the vanilla game, with patch 1.2 installed.

Now as far as I can tell the problem resides in the line:

Script scripts\show_me\mo_money.txt

that is put in the advicethread portion of the file export_descr_advice.


When I install this line in the file and then save, Rome will start up, show me the first Activision screen and then promptly crash to desktop.

When I take the line out and save it plays as normal.

I have been over the lines very carefully in an attempt to spot any typos or other stupid things that might have caused the problem and as far as I can tell I have followed your directions to the letter (litterally).

I have even gone so far as to compare my line with other Script lines in other advicethread sections to see if I messed up my syntax somewhere but to no avail.

[Kraxis]

Interesting, but will the change of ownership always end up in favour of the player? I was thinking along the lines of a city changing hands to another at some point (obviously early).

[Epistolary Richard]

Jason - I'm sorry to hear you're having problems. I've noticed that the board formatting has put a couple of spaces in between Title and Text1, but that doesn't sound like what's going wrong if just removing the script line gets it working again.

Can you use show_err in your shortcut line and tell me what the error message is (if there is one)?

Kraxis - yes, it's always in favour of the player as far as I can tell but maybe there's an optional ownership parameters in there.

[Meneldil]

My question might sound obvious, but I'm trying to create a script that would order a AI character to attack a given settlements during AI turn, but I can't really find out what I should do. Is it a campaign or a show me script ?

[Epistolary Richard]

It would depend on whether or not you wanted the player to be able to save either before the script ran or while it was running. If it was something that happened at the very start of the campaign you can use a campaign script.

What you can do is what Myrddraal does with his scripts and that is use a campaign script to start a show_me script. This means that the script starts running at the beginning of a campaign without player involvement, but all the campaign script does is advance the advice thread and simulate the show_me buttons being pressed. So a second into the campaign, the campaign script has finished running and therefore the player can save. After that, the show_me script is in control and the player can save as normal.

The campaign/show_me division solely relates to how the script is initiated. Show_me scripts are then further divided into event scripts and background scripts.

The difference between the two is essentially whether the script is intended to have a single, instantaneous effect on the game (such as creating a unit or giving more money) or whether the script is designed to be constantly running in the background of the game (such as the multiple turns script).

Both rely on the player to activate them, however an event script requires player interaction on each and every occasion it wants to make a change to the game, whereas once a background script has been activated it can make lots of changes to the game without the player's approval or even knowledge.

Generally speaking, it's better to use a background script for anything that involves the AI.

[Jason]

Richard,

Yes I noticed the spaces the board put in your notes but after comparison with the file I saw that they werent supposed to be there so I didnt put them in. So I guess I didnt actually follow your instructions to the letter

I will try that show_err command when I get home and report back then.

Jason

[Jason]

Alas show_err did not give me any errors. It just simply crashes to the desktop whenever I put that script line in AdviceThread Help_Campaign_Keyboard_Shortcuts_Scroll_Thread.

[Epistolary Richard]

Hmmm... I really can't think what it might be. You are putting the mo_money.txt file in data\scripts\show_me\ and not just in data\scripts\ right? If all else fails, try referencing the advicethread to one of the scripts you get with the original game.

[Jason]

Yay! I found what my problem was. And this took some finding by the way.

Ok so when I made the mo_money.txt file I right clicked in the show_me folder to create a text file. I then named the file mo_money.txt

This created the problem. It confused the hell out of my poor copy of RTW because even though MS thought it was a txt file it was actually labeled improperly. Once I deleted the file, and named the new one simply mo_money and cut and pasted what was in the original post everything worked as advertised.

So all that being said Im going to go over here and hide in the corner with my stupidity. Thank you for your help and hopefully I will be able to pull of other mods with a little better success rate.

Jason

[Epistolary Richard]

You know what? I made exactly the same mistake once when messing around with custom tiles. I think our computers must be on a setting where they conceal the extension so that you actually named it mo_money.txt.txt.

[Jason]

Yes Im going to fix that setting really fast.

One last off the wall question. Are there lists of all the cities (maybe a map) and units and buildings somewhere online so I can try writing scripts while Im here at work waiting for everyone else to get thier acts together so I can get something done?

Jason

[Epistolary Richard]

A chap named rumcajsz does rather a good line in RTW maps, try searching for his name and see if you come up with one of his links. As for units & buildings etc. you can find quite a nice unit list here. Of course I'm very rarely able to be with a copy of RTW so I have all the data folder's text files on a data key.

[Jason]

Another random question from the modding newb.

I seem to have difficulties making ports. Well that is I can make a port and the port will show up in the view with all the other city buildings but the graphic of the port never shows up on the campain map. And when ever you go to make some boats (it does in fact give you the option to do so) the game crashes. I dont seem to have this problem with any of the other buildings I make. Just ports. I even use the same line from the other buildings just cut and pasted in and then take out the building name and put in port. ex:

console_command create_building Londinium port

I am aware there is show_err and I have put this in my shortcut but it never seems to show any errors.

Also as a side note, how do you upgrade a city and its population?

Jason the Newb

[LorDBulA]

Also as a side note, how do you upgrade a city and its population?

I think that there is no simple way to upgrate city.
But you can try to add population with console_command add_population, and spawn apropriate Gavernor building.

[Epistolary Richard]

How to: Change the Date

script
console_command date -220
console_command season summer
end_script

This will change the date to summer 220BC.
Note that you'll get all the historical event messages for the events between the date you jumped from and the date you skipped to.

This command is primarily useful for people who want to skip to the Marian Reforms or change their date altogether. It is also the foundation for Myrddraal's Multiple Turns a Year mod.

[Hans Kloss]

Here is another quick question for Richard :

is there any way that script can be generated to speed up building process and recruiting for any settlements.So far I have managed to create units but current script only works for one character

[Epistolary Richard]

No, building and recruitment times are determined in export_descr_building.

[Ianofsmeg16]

How to: Change the Date

script
console_command date -220
console_command season summer
end_script

This will change the date to summer 220BC.
Note that you'll get all the historical event messages for the events between the date you jumped from and the date you skipped to.

This command is primarily useful for people who want to skip to the Marian Reforms or change their date altogether. It is also the foundation for Myrddraal's Multiple Turns a Year mod.

what file is this in???

[Epistolary Richard]

Please read the first post in this thread - see Stage Three.

[Hans Kloss]

Does "console_command create_unit" work for naval units too ?

I have experimented a bit but it does not seem to working

[Epistolary Richard]

I've never tried it, but the problem I would see with it would be where are you going to put them? Scripting tends to be very blunt, and more than likely it's trying to put them in the settlements themselves rather than in their ports. Try creating them on an existing admiral as you would do on an existing captain or family member.

[Hans Kloss]

I have tried geograhical location

script
console_command create_unit Athens "naval triremes" 2
end_script


and character :

script
console_command create_unit "Admiral Cassius" "naval triremes" 2
end_script

without much luck

In campaign naval units are sometimes given as reward for completion of Senate missions so there is got to be way of creating them with use of scripts at particular settelments

[mike^_^]

hello

I'm having trouble implementing a script, Script Error in export_descr_advice, Line 28986 , column 61 more specifically. " Advice thread increment not supplied "

I copied the samples exact, and fixed the board formatting errors.

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

    Condition ScrollAdviceRequested help_scroll

    AdviceThread Help_Campaign_Keyboard_Shortcuts_Scroll_Thread  0

;------------------------------------------
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

Line 28986 is in red, what's going on here?

[mike^_^]

why can't I edit my post?

anyway, the line that is getting the error is the AdviceThread string

AdviceThread Help_Campaign_Keyboard_Shortcuts_Scroll_Thread

I can't figure out what's going on.. the format is fine, it compares with the samples, and the other advice thread strings in the eda file

It says, "Advice Thread increment not supplied"

I'm really at a loss

[LorDBulA]

In campaign naval units are sometimes given as reward for completion of Senate missions so there is got to be way of creating them with use of scripts at particular settelments

If you find a way to do this please post it in this thread. I would also like to know how to do that.

I copied the samples exact, and fixed the board formatting errors.

This AdviceThread already exists, did you copy onother one or did you just edited existing one?

If you copied it then there are now two AdviceThreads with the same name and this can be a problem.