DrNick's Advanced Trigger Guide

A. Introduction:

This guide is for those people who have used the editor for a while and know what all the conditions and effects do pretty well. First, we will go behind the scenes to see how triggers actually work. Then we will learn how to create custom triggers and effects. Warning: While I will try and make this guide as understandable as possible, it is an advanced topic and, as such, may take some time to completely understand. I will try to be as comprehensive as possible, so to catch and understand everything it may take a couple of reads. It's also on the long side. But don't let the warning discourage you; The topics discussed here will increase your understanding of scenario design ten fold. And the ability to create custom Conditions and Effects is incredibly rewarding.

B. What You Will Need:

You may need to download AomEd by Ykkrosh. You can find it here. In addition, for this tutorial I have AOM:TT (though AOM Vanilla is just fine) and SomeNewXTriggers2 by Reyk which I would recommend to all designers anyway. In fact, if you get SomeNewXTriggers2 (or any version for that matter), you wont need to deal with AomEd and can skip an entire section of this guide. You will also need a text editor. Wordpad will work fine and it ships with Windows.

C. Triggers: Behind the Scenes

We should all know what Triggers are: A way to script events. To create a trigger, you simply open up the trigger editor, and click insert. Then you choose a condition and an effect and set all the parameters required for each. Enough review. Have you ever wondered what a trigger really was? The answer is in my original definition: A way to script events. What is a script? A script is a series of commands, like a mini-program. In actuality, when you create a trigger, you are adding code to your scenario. The trigger editor does this all behind the scenes. When you select a condition, there is code attached to it, code that then gets copied into your scenario. The same thing happens with an effect. One member (a condition or effect) can contain several lines of code.

The first point to note, is that this code is stored in your scenario file. Once you create a trigger, all the code associated with your condition(s) and effect(s) will be copied over. Once you play a scenario, the trigger code is then copied again, into a file called "trigtemp.xs". If you have the Titans, you can find this file in "My Documents\My Games\Age of Mythology\trigger2". If you open it up with your text editor you will see code. It is very similar to the language C, though it has some major differences.

Okay, so we know where the code goes when we create a trigger, but where does it come from? We didn't write it ourselves, it was associated with the conditions and effects that we chose. Luckily for you, I know the answer. There is a file, located under the AoM installation folder in the "trigger" (for vanilla installations) or "trigger2" (for chocolate). It is called "typetest.xmb" (or, if you've downloaded custom conditions and effects, "typetest.xml"). This file contains the names of all of the conitions and effects that you can select. And then, the code that should execute when these members are called upon. If you have only "typetest.xmb", you're going to need to read the next section, if you have a "typetest.xml", you get to skip to section E you lucky dog.

D. AomEd: Converting typetest.xmb

Okay, so you've downloaded AomEd. Open the zip and extract it to anywhere you'd like. Then run "aomed.exe". You should get a small window that says "Age of Mythology Data File Converter" on the top. Then there are three buttons: "Direct File Conversion", "Bulk Conversion", and "Advanced Options". Since we will be converting one file, go ahead and click "Direct File Conversion". Now you will get an "Open File..." dialog box. Navigate to the "trigger2" folder in your AOM installation folder and select "typetest.xmb" and click okay. You will get a dialog box confirming that AOMEd will be converting your file to .xml. Press okay and you will be given a "Save As..." dialog box. Type in: "typetest.xml" and click okay. You've now converted a file in AOMEd. Eat a cookie and celebrate. If you've already made a backup of your typetest.xmb (as described in the previous section), it's okay to delete it. The AOM Trigger editor can read .xml just as well as .xmb.

E. typetest.xml Structure

Okay, here's where things get fun. Fire up your favorite text editor and open typetest.xml. You will now be presented with something like this (first few lines only. Also note that I am using SomeNewXTriggers2, so mine may look different than yours.)

<?xml version = "1.0"?>
<trigger version="2">
  <!-- SomenewXtriggers Version 2 -->
<Conditions>
   <Condition name="$$22289$$Always">
      <Expression>true</Expression>
   </Condition>

So let's get into it. The file is written in xml which is a markup language. What does that mean? Well, It's similar to bb code. The main thing you should be aware of are "Tags"; tags are the things in pointy brackets: "<ATag>". Most tags must also "close". In other words, If you look far enough, you will find a matching tag with a slash in front of it ("/"), in the example above, "<Condition>" is a tag in line 5 (not counting blank space), it closes in the last line with: "</Condition>". Everything in between is the contents of <Condition>. Tags also have options. Notice in the "<Condition>" tag, there is a space and then "name=", this is an option. Different tags have different options and some don't have any at all. One last structural note is "nesting". "Nesting" refers to using tags in the contents of another tag. If you look above, you can see an "<Expression>" tag is used inside of our "<Condition>" tag. This is nesting and it is the most important part of the structure of "trigtemp.xml"; Once you understand how tags layer on top of each other, "trigtemp.xml" will cease to look like an alien wrote it.

F. Syntax: How to use Tags

Skip the first two tags, they're system tags and you wont ever need to edit them. In the above example, there is a tag that looks like this: "<!-- SomenewXtriggers Version 2 -->", this is known as a comment. Anything in a tag that starts with: "<!-- " and ends with: "-->" will be completely ignored by the game. When coding, comments add a human element. They're a way to say: "Hey! With this code, I'm doing this!" or (as in this example), "This is what this is". Once again, this is completely ignored by the game, it's purely for human benefeit.

Next, we come to "<Conditions>" included in the contents of the "<Conditions>" tag is every condition that the game will recognize. If you scroll down far enough, you will find the closing "</Conditions>" tag followed by the "<Effects>" tag which closes at the end of the file.

Contiained in the "<Conditions>" tag is a series of "<Condition>" tags (without the 's', don't get the two tags confused!). Each "<Condition>" tag contains information describing a condition. The information begins with the tag option, "name". As in: "<Condition name=...>". "name" is a string (of characters) that describe the name of the condition as it will appear in the trigger editor list. If you'll notice, the built in conditions have funny "name" options set. They begin with "$$" and then a series of numbers followed by "$$" and then the actual name. I'm pretty sure the number between the "$$"s is a reference the the "language.dll" file, which would allow the name to be displayed in the player's language. But the good news is, that part isn't required. You can just use the text at the end. So for your own effects, you wouldn't need: "name="$$22289$$Always"", you can just use: "name="Always"" and "Always" will display in the trigger editor.

Nested inside of your "<Condition>" or "<Effect>" tag is the code that defines it. The first thing we'll talk about is the "<Param>" tag. "<Param>" tags describe the parameters that the scenario maker can choose when they select the condition or effect. Lets look at an example:

      <Condition name="$$22290$$Timer">
      <Param name="Param1" dispName="$$22291$$Seconds" VarType="long">0</Param>
      <Expression>(trTime()-cActivationTime) >= %Param1%</Expression>
      </Condition>

This is the condition, Timer. The outside tag is the "<Condition>" tag. The second is the "<Param>" tag. The <Param> tag has several options, all of which must be set. The first is "name". Unlike in the <Condition> tag, "name" is not the name that is displayed in the editor, that job is taken by the next option "dispname". "name" is the name of the parameter that the condition code will use. If you look in the next tag down ("<Expression>" you can see the name given ("Param1") in "%" signs. That is how you reference a "Param" in your condition and effects. After the self explanitory "dispName" option, comes "VarType" which stands for variable type. This is a string that tells what type of parameter this is and how it will be diplayed in the editor. The options (and how they are displayed) are:

"long": An input box for numbers.
"float": An input box for numbers that allows decimal points.
"string": An input box for any type of text (not just numbers)
"stringid": Seems to be the same as string, but it may have internal differences.
"bool": A button that can be pressed in or sticking out. ("true" or "false")
"unit": A "select unit" style button.
"group": Army selection tools
"area": A "select area" style button.
"sound": Select sound style tools
"camerainfo": A set of "Cut to Scene" stye buttons
"camtrack": A dropdown list of camera tracks
"operator": A dropdown list of operators. ("==", ">", "<", etc)
"player": A dropdown list of player numbers
"tech": A dropdown list of technologies
"protounit": A dropdown list of different unit types.
"alliance": A dropdown list of diplomacies ("Ally", "Neutral" and "Enemy")
"kbstat": A dropdown list of statistics (as seen in: )
"godpower": A dropdown list of godpowers
"resource": A dropdown list of resources ("food", "wood", "gold", "favor")
"event": A dropdown list of triggers (in fire event type effects)
"techstatus": Dropdown list for "SetTechStatus" type effects ("Available", etc)
"unitstance": For unit stances used in Unit Set Stance ("Aggressive", etc)
"uicategory": Used in "Flash UI Category" effect.
"pufield": Used for the "field" parameter in the effect: "Modify Proto Unit"

Finally, we reach the contents of the <Param> tag. The value here will be the default value for a newly created trigger using this condition/effect. You can also leave it blank by using the closing tag (</Param> ) without typing anything in between.

The next thing to notice is the <Expression> tag. An "Expression" is a piece of code that is "evaluated", what that means is it can be computed to a value of either "true" or "false". <Expression> is generally only used in conditions. So if the <Expression> is evaluated to "true" than the condition has been satisfied and the effect of your trigger is fired. If it evaluates to "false" than it will try again the next time around, but the condition has not been satisfied. If you notice in the "Always" condition, the contents of the <Expression> is just "true". That's because "Always" is always true. The above example is a little more complicated, but I'll break it down for you:

<Expression>(trTime()-cActivationTime) >= %Param1%</Expression>

trTime() is a piece of code that gets the current time and cActivationTime is the time the trigger was fired. It subtracts the current time from the cActivationTime giving you the number of seconds since the trigger fired. Now we get to the evaluation. ">=" is greater than or equal to and "Param1" is the "name" option of the "<Param>" which is displayd as: "Seconds". So this can be translated like this: If the number of seconds since the trigger fired is greater than or equal to the number of seconds the scenario creator entered then then the condition is true. Otherwise, try again next time.

For code that does not get Evaluated (is not an <Expression> ) you use the tag <Command>. Unlike <Expression> which contains code, but also requires some interpretation by the game in order to become proper code, the contents of a <Command> tag are directly copied over without any real interpretation. Therefore the structure is a little different. Here's an example:

      <Effect name="$$20056$$Message">
      <Param name="Text" dispName="$$20494$$Text" varType="stringid">default</Param>
      <Param name="Timeout" dispName="$$22429$$Timeout (ms)" varType="long">-1</Param>
      <Command>trMessageSetText("%Text%", %Timeout%);</Command>
      </Effect>

First of all, <Command> tags are used in both conditions and effects as there should be only one <Expression> in a condition and sometimes they require a little more code to run properly. But effects use <Command> tags exclusively as there is no expectation of evaluation. Second of all, notice that the Param names are in quotation marks ("") as well as percent signs (%) and that the contents of every <Command> tag must end with a semi-colon (";").

If you've poked around a little, you may have realized that <Command> also has some options. "loop" and "loopParm". These two options go together. "loop" will always = "". Which just means nothing. The fact that this option exists in a given <Command> tag is enough for the game. "loopParm" is always present when there is a "loop" option. "loopParm" is the name of a Param. This seems to work like the clause: "for each". So it will run the <Command> once for each object in the Param. This may be confusing at first but consider this: For the "unit" parameter, multiple units can be selected. So the <Command> tag may have a "loop" option in effects using a "unit" Param so that it runs once for each unit in the "unit" param. In fact this seems to be the only time the "loop" option is used.

So that's it for syntax. Any other code is in XS and if you don't know it, this guide can't teach it. That doesn't mean you can't make your own conditions and effects as we'll go over below

G. Methods of Creating Custom Members

There are three basic ways of creating your own conditions and effects. In this section we'll go through all three.

1. Synthesis - Combining two existing conditions or effects. Let's go over an example: Let's say you want to create a new effect that allows a unit to work on an army. We'll name it "Unit work on Army" (simple enough). We know there's a "Unit Work" effect so we'll copy that. and paste it after the last effect closes, but before the closing <Effects> tag (between </Effect> and </Effects>. You should end up with the following code:

<Effect name="$$22417$$Unit Work">
<Param name="SrcObject" dispName="$$22295$$Source Units" varType="unit">default</Param>
<Param name="DstObject" dispName="$$22296$$Target Unit" varType="unit">default</Param>
<Param name="EventID" dispName="$$22362$$Trigger" varType="event">-1</Param>
<Command>trUnitSelectClear();</Command>
<Command loop="" loopParm="SrcObject">trUnitSelect("%SrcObject%");</Command>
<Command>trUnitDoWorkOnUnit("%DstObject%",%EventID%);</Command>
</Effect>

There are many triggers that deal with armies. We'll pick the simplest one. There's no need to copy and paste this code. We'll be only taking the parts we need:

<Effect name="$$22468$$Army Work">
<Param name="SrcArmy" dispName="$$22348$$Army" VarType="group">default</Param>
<Param name="DstObject" dispName="$$22296$$Target Unit" varType="unit">default</Param>
<Param name="EventID" dispName="$$22362$$Trigger" varType="event">-1</Param>
<Command>trArmySelect("%SrcArmy%");</Command>
<Command>trUnitDoWorkOnUnit("%DstObject%",%EventID%);</Command>
</Effect>

So, the first thing we need to do is change the name of our new effect, so in the <Effect> tag at the "name" option, delete everything between the quotes ("") and enter in "Unit Work on Army".

Next, we need is to be able to select a Target Army instead of a target unit. A quick scan of the "Unit Work" effect will show that the Param with name "DstObject" is the one we need to change, so lets copy the line "<Param name="SrcArmy" dispname="$$22348$$Army..." from the second effect and paste it over the "<Param name="DstObject" dispname="$$22296$$Target Unit...". Now lets review the options of our new Param. First it's "name" option. Let's change it back to "DstObject" so that it will work with the later <Command> code. Then the "dispName", "Army" is fine, but maybe "Target Army" would be better. So delete all the information in the quotes ("") and enter in "Target Army" remember to delete the numbers between the "$$". Finally, get rid of the "loop" and "loopParm" options from the second <Command> tag. The scenario designer can only choose one army, so this isn't required.

That's it. You should now have an effect that looks like this:

<Effect name="Unit Work on Army">
<Param name="SrcObject" dispName="$$22295$$Source Units" varType="unit">default</Param>
<Param name="DstObject" dispName="Target Army" varType="group">default</Param>
<Param name="EventID" dispName="$$22362$$Trigger" varType="event">-1</Param>
<Command>trUnitSelectClear();</Command>
<Command>trUnitSelect("%SrcObject%");</Command>
<Command>trUnitDoWorkOnUnit("%DstObject%",%EventID%);</Command>
</Effect>

2. Fragmenting - The second method for creating a new effect or condition is taking just a piece of an existing effect. For this example, let's take a closer look at the "Unit Work" effect. Notice the line "<Command>trUnitSelectClear();<Command>" If you think about the name of the command trUnitSelectClear() is seems like this deselect any units that the player may have selected. Let's test it out by making a new trigger.
This time, instead of copying, we'll start from scratch type this in just before the <Effects> tag closes but after the last </Effect>:

<Effect name="Deselect Units">
<Command>trUnitSelectClear();</Comman>
</Effect>

This is an extremely simple example. We don't even need any <Param> tags. If you test it out, you'll see that our guessing was right. Any units that the player has selected will deselect when a trigger containing this event fires.

3. Creation - The final method involves knowing the available XS and RMS commands and crating a trigger from scratch. Of the three methods, this one requires the most thought and planning. Genearlly, when you get to this point, you have a clear idea of something you want to create and you just need to try stuff until it works.

H. Conclusion

Through this guide, you should now have an intimate understanding of how the trigger editor works. You should know that trigger code originates in the "typetest.xml" file and gets copied over to the scenario file, eliminating the need to distribute an .xml file with your scenarios. You also know the strucure of the "typetest.xml" file and you understand some ways of creating custom conditions and effects. If you didn't understand everything, that's alright; Experamentation is the key. Don't worry about messing anything up. If you make an unfixable mistake, you should still have your backup. I nor anybody else here can give you the understanding you need, that comes from experience.

So that's it. My latest guide. Any suggestions, corrections, or questions can go here. I won't snap your head off.