TWX Scripting Guide, Part 3 - Trigger Theory
So far the scripts we've learnt how to write are limited to simple, linear, user driven scripts. To be able to write those big complex artificially intelligent wonders that can losely be called small programs, you'll need to understand how triggers work.
I pondered for a long time how best to explain the theory behind triggers and how they work. Working with triggers can get extremely complex, especially when working with a large number of them. The best way to think of a trigger is a catch in your script thats just waiting to happen. Triggers can only activate when the script is 'paused' and waiting for feedback from the trade wars server. There are two ways of doing this, one is using the waitFor command I discussed earlier, the other is with the pause command.
There are 4 different types of triggers in TWX Proxy:
Text Triggers - These are technically just like waitFors. They get activated as soon as certain text gets received from the game.
Text Line Triggers - These are like extended text triggers. The only thing that is different about them is that they will only trigger as soon as the certain text gets received, AND the full line with it. The reason for this is that very often a Text Trigger will activate when only half a line has been received. This means if we need to get info out of the second half of the line, it just isn't there. Text Line Triggers should always be used when we need to pick any specific info out of what the game is sending us.
Delay Triggers - Delay triggers automatically activate after a specific number of milliseconds.
Event Triggers - Event triggers are triggers that are activated by specific events, such as the connection being lost, a date or time being hit, etc. These triggers will be covered in a later tutorial.
Triggers can be set anywhere in our script, but we must remember that the script needs to be paused for them to activate. Also, they need to be killed so they don't get set off by accident. Here is an example of a very basic text trigger:
setTextTrigger myTrigger :sendStuff "INACTIVITY WARNING"
This works in the following sequence:
1. TWX hits the setTextTrigger command, and makes a new text trigger waiting for the text "INACTIVITY WARNING"
2. TWX hits the pause command. The script stops executing, relying on its triggers to pull it back into execution when it needs to.
3. The TWGS game server, after 4 minutes, sends an inactivity warning to TWX. TWX checks through the inactivity warning, and spots the text 'INACTIVITY WARNING'. Because there is a trigger set to activate on this, the script jumps to the :sendStuff label and starts executing again.
4. The script hits the send command, and sends the "#" text to the game server.
5. The script hits the goto command, and jumps back up to the top above where the trigger was set, thus it repeats.
This little keepalive script will function exactly the same as:
waitFor "INACTIVITY WARNING"
Now, lets get a bit more useful. The following code makes use of a Text Line Trigger to get the current sector from the game.
setTextLineTrigger getCurrentSector :getSector "Sector : "
getWord CURRENTLINE $sector 3
The sequence of this code extract should now be quite straight forward to you. The only real difference in the way this trigger works is that it won't activate until the line containing the text "Sector : " has been fully received from the game. This means we can safely grab the sector number out of the line, using the getWord command.
This is the first time we've used either the getWord command, or the CURRENTLINE constant. The getWord command is used to grab a specific word out of a line of text (for more info on this, check the TWX Proxy help file). The CURRENTLINE constant will always hold the last line received from the game server - it is the only way of getting information from the game.
Now that we know how to properly utilise Text and Text Line Triggers, lets get into something a bit more complex.
You can have as many triggers as you need to at one time within your script. This means you can use them to control how your script will react to text received from the game. For example, here is an extract of the 1_SSM.ts script in pack1:
# wait to see if we got busted. If we did, we'd better stop
setTextTrigger 1 :continue "Success!"
setTextTrigger 2 :stop "Busted!"
setTextTrigger 3 :stop "There aren't that many holds"
# move back to $sector1 ...
waitfor "Command [TL="
send $sectorNumber1 "*"
This script makes use of three Text Triggers to branch the script, depending upon whether or not the player was successful in making a steal. The killTrigger command is used to terminate an active trigger. Note that if the trigger specified doesn't exist, this command will just be ignored. Its not only good practice to kill all triggers when your done with a branch like this, its mandatory. If one of them stays active then there is always the chance of it activating later in the script and totally messing up your code.
Also, note that triggers are automatically killed after they activate.
Return to Tutorials Page