Matrix Games Forums

I have never seen an accessible guide on "how to do event scripting" for the SC series. So, here goes! My 1911 mod uses scripts extensively so for the last 6 weeks or so I have been teaching myself this. Here is what I have learned, with some worked examples.

The structure of the events is really similar across all the SC3 series games, so this guide should work for all of them. There will be differences of detail though.

Background & tips
Event scripts live in: "C:\Users\You\Documents\My Games\Strategic Command Version Name\Campaigns\_ScenarioName\Scripts\Events" - at least mine do.

There are about 22 files in that folder, each for a different format of event. AI scripts are in a separate folder - I won't cover that for now. There are also localisation subfolders with names like DE, EN, ec, you can safely ignore them too.

You can also locate the scripts in the Editor via >Campaign>Edit Event Scripts . You can open them from here as well but they will probably open in Notepad.

I recommend that for effective scripting:
1. Have the Editor itself open - you will need it heavily to find locations etc
2. Open the script files from your file folder (not via the editor) using a good text editor. I recommend Notepad++ - it has tools like multiple tabs, line numbers, and automatic bracket completion that is really helpful for this work.
3. Also have the Manual open, as it has some helpful reference notes.

Script file structure
The top of the file is a Usage Guide for each event type. This is really helpful to guide you as to what to do with each kind of event file - it will have more technical detail than I will cover here.

Then there are a list of reference values e.g. Nation IDs.

Then there are the events themselves.

Note that a line that starts with a ; is a comment line - you can leave notes for yourself for instance with
; note to self

Updating, Debugging, Saving
Changing the contents of the script file by itself does not update the scenario. What you need to do to put your changes into effect is:
a) Save the text script file you have been working on.
b) In the Editor, open Edit Event Scripts
c) You will see that the file you've worked on (and maybe others) now has a * at the end in the left-hand column. This means the Editor thinks it needs to be re-integrated with the campaign file before it will load.
d) You will also see two Update buttons and an Update All button.
e) The bottom left Update button will debug your file and give an error message for the first error it encounters (if it encounters any). These messages are usually pretty handy. They tell you the line number of the event that failed, and which field behaved unexpectedly. If you have missed brackets or put in an invalid ID or something, it will tell you. If there are no errors, the Editor will be happy and will remove the * from the file on the list, indicating that the updated script file is good to go.
f) the right-hand Update and Update All buttons do the same thing more quickly. But they do not report errors. If there are errors, you will know because there will be files whose *s remain in place, but the errors found are not reported to you. You need to go back over them with the other Update button.
g) Once your script has no * in the list, you can then save the campaign you are working on in the Editor. The new script is now updated in the campaign file and will load when you start a new game using your campaign.

If you start a campaign and events you created are not appearing, there is a possibility you didn't complete these steps.

OK - now on to the fun part - actually editing events!

I'll start with a simple Unit event and illustrate how to chain it to a Decision.

I've picked a Unit event because they can have fairly straightforward triggers, and are also easy to test in the game because the results are obvious.

Unit events do what they say on the tin: Create units.

Each Unit event can create one or more units, of any different kind, for one power. Units may only be placed at friendly resources, and all the event's units will show up at the same time. If you want to have lots of different units arrive at different places and times, then simply use more Unit events.

Here is the event. It creates a British Cavalry Division at Tehran.

If you're new to this, then the list of components may look bafflingly long. What do all of these do, and why?

The good news is you don't have to understand all of these to have a viable event. Most of it you can just copy forward from this event, or another existing one in the file from the vanilla game. I'll mark the ones you really need to change for your first event with a *

Here are some that are fairly simple:
#NAME* is the internal name, not displayed to players, so you can use whatever's convenient.
#POPUP* is the popup text that displays to players (if any). This must be descriptive. Most of the vanilla events have references to <<TAG>> numbers in localisation files, but just writing text here is much simpler.
#IMAGE and #SOUND refer to media. I have been lazy here and left in some media from the event I copied forward to create this one. Later I will have to go back and replace it, as this media is not actually very appropriate for the event.
#FLAG is a marker for whether the event is 'default for the campaign'. Safe to keep this as 1. (I have never seen it not be 1!)

Next is #TYPE. For now you can just leave it as 1. There is a lot to say about this, but not for this post!

Next, two variables about how AI interacts with the event. There is no need to change either of them.
#AI controls whether the event fires exclusively for certain AI or multiplayer game types.
#LEVEL controls what AI skill level the event fires for.
Both of these are mainly for AI-helper events. I recommend just leaving these as 0 until you start to try to balance the game for the AI.

Then we have two complex event triggers, one less important, one really important.
#GV is another kind of trigger %. You should leave this as [1,100] unless you want to do some advanced things using the Global Variables to create branching event paths.

#LINK* means this event is chained to a Decision Event.
In this case I have set this to [1000, 1]. That means it will check DE 1000 and this event will only fire if that event was selected.

I'll come on to what DE1000 does in the next post! But for now you are safe to change this to [0,0] so the event you create will be possible to test.

#TRIGGER is the % or % per turn chance that the event will happen. What this means depends on the #TYPE -but for now leave it at 100.

#PRIVATE sets whether the event message appears for the other side in the game.
#DISPLAY_TURN defines whether the event happens on the 'Axis' or 'Allied' turns. or if it has a 0 it can appear on either. Usually I'd leave this as 0.

#COUNTRY_ID*tells you which Country ID number will benefit from this event. You must, of course, use the ID number not the name. In this case it's 112, meaning United Kingdom. Feel free to pick another country ID!

#FULL_RESEARCH states whether the units that appear from this event will appear with upgrades applied, or not. As this event is meant to fire on Turn 1 and the UK has no research, the point is moot. But I set it to 0.

#DESTINATION_RESOURCE* is the place that the units will arrive at. You can have several destination resources, the units will try to appear at the top one first. But at least one of the Destination Resources must be controlled by the same side as the country the event is for (defined in #COUNTRY_ID). NB, units can only appear at resources.

To find the coordinates of resources, go to the Editor and hover your mouse over the hex you want the units to appear. In this case, (248, 115) is Tehran. Of course in most scenarios Tehran is not controlled by the United Kingdom, so if you're trying this for the first time, pick a resource that makes sense for you!

#DATE* is the date the event is first checked on. Again, what this means depends on the #TYPE you set earlier. #DATE will be the date the event happens on, or happens on or after.

I've set this to be the start date of the scenario, as I want this unit to appear on turn 1. You are recommended to change this to the start date of whatever scenario you're working on, to make it easy to test.

#FAILSAFE_DATE* is the date when the event will trigger if it has never previously triggered. I'd only use this if what I was intending was for the event to happen on or before a specific date (usually you are looking for 'on or after'). As a dummy, put this after the end date of your scenario!

Now, finally, we get on to the section that tells you what unit goes where and under what circumstances!

We have two Conditions that determine whether the event actually fires:
#VARIABLE_CONDITION* is based on country politics. In this case I have 112 [1] [100] [0]: the UK is on the Axis side, fully mobilised, and not surrendered. Those are easy condition to fulfill in the scenario I've made; the UK is already set to be the only fully-mobilised Axis major on turn 1. I suggest updating this so that it checks that the country you defined in COUNTRY_ID is on the side it actually is (1 for Axis/Central Powers, 2 for Allies/Entente).
#CONDITION_POSITION would let you define a trigger based on there being a certain number of units near a certain resource. For now, leave this as all 0s.

And finally, the Units that will arrive!
#UNIT defines a unit that will arrive in the event. If you want more than one unit, add more #UNIT= rows. Each one needs to define a unit type, strength, experience, and optionally a name. 11 [8] [1] [Persian Gendarmerie] means a Cavalry Division at Strength 8 with 1 experience point, called Persian Gendarmerie. The list of Unit Types is towards the top of the event file.

Of course the units have to be valid for the resource type. If the resource is a port then you can only tell the event to create naval units. If it's anything other than a port, then only land or air units are possible.

If you're experimenting with the event scripts, this post should give you enough info to create a Unit script with a simple trigger that will fire for one nation at the start of the game.

Next up: How to chain the event script to a Decision Event so that the unit costs MPPs.

Good initiative!

Still thinking to write: "How to chain the event script to a Decision Event so that the unit costs MPPs."?

ORIGINAL: Tulius Hostilius

Still thinking to write: "How to chain the event script to a Decision Event so that the unit costs MPPs."?

The best thing to do is to open up both the Decision and Unit script files from an official campaign, and use those as examples to base your own on.

So if you find a Decision that creates a unit, then search the unit file for the Decision number, and go from there.

So here is the Decision event I mentioned!

Much of this structure is the same as for the Unit event. I won't repeat everything, so here are the key differences.

#DECISION= sets the internal number of the event (1-1100). Vanilla events have numbers already, so I started from 1000 to keep the new events I'm creating together and not conflict.

You will see that the #LINK statement in the unit event above refers to this event with [1000,1]. Which means that the unit event will only fire if this Decision Event has appeared and been accepted. If I'd said [1000,0] that would mean it depended on this decision being rejected. If for some reason you want to trigger something based on a DE appearing and then being EITHER accepted OR rejected, then I think you need 2 events with both variant triggers.

Many events for many different nations can be triggered by the same DE. If you want a decision to give Germany submarines, reduce France's national morale, and spawn partisans in Libya then go wild!

As DEs also have a #LINK value, you can link one DE to another, and make complicated branching trees of Decision Events.

#MPP_UPDOWN= -25
#MPP_TURNS= 1
#MPP_TEXT=

This defines the cost or benefit of saying YES for the power whose event this is (defined in COUNTRY_ID). The MPP_UPDOWN value is applied for MPP_TURNS number of turns; in this case 25 for one turn. If you have more turns to spread the cost over the total cost will be MPP_UPDOWN x MPP_TURNS. If you want a positive benefit from saying YES then remove the - sign.

If you want something that costs MPP now, but then gives you more MPPs in the future, you could achieve this with chained Decision Events.

If you want several nations to pay MPPs, then you have to set up DEs for all of them. (There are some other ways to raise/reduce MPP income using convoys or resource events - but that's a separate subject, and this is the cleanest way to do it!)

Finally, note that the Decision Events have more options for triggers:

#ALIGNMENT_POSITION= 248,115 [1]
;Set National Morale Trigger (dummy value)
#NATIONAL_MORALE_TRIGGER= 0 [0]
;Set variable conditions:
; 1st Line - UK politically aligned with Anglo Germany and not surrendered
#VARIABLE_CONDITION= 112 [1] [100] [0]
; 2nd Line - Germany politically aligned with the Central Powers and not surrendered
#VARIABLE_CONDITION= 45 [1] [50] [0]
;Dummy condition position (always satisfied)
#CONDITION_POSITION= 0,0 [0,0] [0,0] [0] [0]

These are all in effect dummy triggers. I want this event to definitely fire on Turn 1, so have selected things I know will happen on Turn 1 without fail. Still, there are options to make DEs depend on National Morale, on who owns what hex, on where units are positions, and on the political alignments of different powers. More on triggers in a later post...

Hi - this guide is really helpful! Any chance you might resume writing it? I would enjoy reading the promised post on how to write trigger conditions and how to use the Global Variables.