There are two types of triggers. First one could be called a function, the second are interactions trigger, this mean that when an interaction happen, instead of transforming into other element like in BS1, you “trigger” a function. So instead of executing a normal interaction, it will execute your “trigger” or function.
First thing to do when creating a new functions is to clear any previous trace of the functions.
REMOVETRIGGER function_name
If you dont do this, and reload the mod without closing BS2, then it will be added to the existing function, doubling every line each time you reload it. If you create a new funtion you should ALWAYS use this.
Then to create the function you use this kind of syntax:
ON function_name Command
Command is the command you want to do when your function is called. So lets say you want to draw a Circle in your function, you should do it like this:
REMOVETRIGGER Draw_Circle ON Draw_Circle DRAW ELEMENT:Earth CIRCLE 210 210 50
In this example the function called 'Draw_Circle' will draw a circle at X,Y postion 210,210 and with a radius of 50.
Now lets just say i want to draw a line that will cut that circle in half:
ON Draw_Circle DRAW ELEMENT:Earth LINE (210 - 50) 210 100 0
Without the removetrigger the line will be added to the function Draw_Circle. So you can put this line anywhere in your code and it will just add the line to the function, but i greatly recommand grouping all line of a function all in one block.
Ok now let's say i want this to happen, when the user hit the “d” key. First of all, you must know that in BS2 there are lot of default function already created by Sieben. These include key function. So if you want the key already assigned by Sieben to be completly replaced, you must use the removetrigger, if not then dont use it. So all key are assigned like this KEY_ and then the key, this is when a key is pushed or down, then you release the key and it call KEYUP_ then the key.
In this example i want it on the “d” key, so here is how to do it:
REMOVETRIGGER KEY_d ON KEY_d EXEC Draw_Circle
The KEYUP_d is no use here and as you can see a function you have made can be called with the EXEC command. So the final code would draw a circle, then a line cutting the circle in half, the circle x,y are fixed at 210,210 and radius at 50. So each push of the “d” key, will draw the circle at the same position:
REMOVETRIGGER Draw_Circle ON Draw_Circle DRAW ELEMENT:Earth CIRCLE 210 210 50 ON Draw_Circle DRAW ELEMENT:Earth LINE (210 - 50) 210 100 0 REMOVETRIGGER KEY_d ON KEY_d EXEC Draw_Circle
Now, a little more advanced use of the function you create, is to use them with parameters. In the previous example x,y position of the circle was fixed to 210,210. Now if i want my function to draw this at any position i want, i will transform it to use parameters. Parameters come in the form of $ in a function. Each of them are ordered so in my example i want to be able to change the x,y. This would make me call my function like this:
EXEC Draw_Circle X Y
Replacing the X and Y by the value you want. In this example it would use the X,Y coordinate of the cursor. But for this to work i have to modify my function. Like i said each parameters are ordered and come with a $ before them. So here in the example the X would correspond to $0 and the Y to $1. Now lets replace all X,Y value in the function by these:
REMOVETRIGGER Draw_Circle ON Draw_Circle DRAW ELEMENT:Earth CIRCLE $0 $1 50 ON Draw_Circle DRAW ELEMENT:Earth LINE ($0 - 50) $1 100 0
Now each $0 will be replaced by the first parameter i give, and $1 by the second parameter. So now when my mod start, i want my function to be executed, drawing a circle at the position 100,200. I would call my function like this:
EXEC Draw_Circle 100 200
So pretty easy to understand now. Lets make the radius a parameter too. So X,Y are first and second parameters, Radius will be the third and represented in the function by $2:
REMOVETRIGGER Draw_Circle ON Draw_Circle DRAW ELEMENT:Earth CIRCLE $0 $1 $2 ON Draw_Circle DRAW ELEMENT:Earth LINE ($0 - $2) $1 ($2 * 2) 0
Again you call the function like in the previous example except that now you must add the Radius of the circle as the third parameters:
EXEC Draw_Circle 100 200 125
Now my function will draw a circle at position 100,200 on the sandbox with a radius of 125.
The finale code would be:
REMOVETRIGGER Draw_Circle ON Draw_Circle DRAW ELEMENT:Earth CIRCLE $0 $1 $2 ON Draw_Circle DRAW ELEMENT:Earth LINE ($0 - $2) $1 ($2 * 2) 0 REMOVETRIGGER KEY_d ON KEY_d EXEC Draw_Circle
Now you can try modify these little functions and experiment with it.
There are 2 kind of conditions: * IF condition * WHILE condition
Syntax:
ON Function_Name IF (Condition) <Trigger>
An 'IF' is very usefull to check for a condition. Let's take the previous example and add it a conditions.
REMOVETRIGGER Draw_Circle ON Draw_Circle DRAW ELEMENT:Earth CIRCLE $0 $1 $2 ON Draw_Circle DRAW ELEMENT:Earth LINE ($0 - $2) $1 ($2 * 2) 0
Ok now i want this function to work, but only when the user hold the SHIFT key.<br> First, the SHIFT key state in BS2, well it correspond to the var SHIFT. 1 the key is pressed, 0 key not pressed.<br> So here is the IF syntax for this:
ON Draw_Circle IF (SHIFT == 1) <DRAW ELEMENT:Earth CIRCLE $0 $1 $2>
Ok first every conditions should be between () and any action different than a trigger must be between <>.<br> If i had call a function instead of the DRAW command, i would have use this instead:
ON Draw_Circle IF (SHIFT == 1) '''''Function_To_Excecute'''''
So if it is a function you dont put it between <>.
But thats not the case so here is the finale function modified to work only when SHIFT is pressed:
REMOVETRIGGER Draw_Circle ON Draw_Circle IF (SHIFT == 1) <DRAW ELEMENT:Earth CIRCLE $0 $1 $2> ON Draw_Circle IF (SHIFT == 1) <DRAW ELEMENT:Earth LINE ($0 - $2) $1 ($2 * 2) 0>
This is one way of doing it, because this uses 2 line, but for a bigger functions, it could be painfull, so here is another way of doing it:
REMOVETRIGGER Draw_Circle ON Draw_Circle IF (SHIFT == 1) Draw_Circle2 REMOVETRIGGER Draw_Circle2 ON Draw_Circle2 DRAW ELEMENT:Earth CIRCLE $0 $1 $2 ON Draw_Circle2 DRAW ELEMENT:Earth LINE ($0 - $2) $1 ($2 * 2) 0
So i just rename the Draw_Circle function to Draw_Circle2, then remake a new Draw_Circle that execute Draw_Circle2 only when shift is pressed (1). This is very usefull if you have a lot of lines in your function.
Syntax:
ON Function_Name WHILE (Condition) <Trigger>
This command is used to make loop. Loop can be very usefull in some situation.
Lets just make a useless function now to demonstrate how it work. We will make a replica of the LINE command, using the POINT command. The LINE function draw a line from a starting point to another. The POINT function only draw 1 pixel at starting point. So if i would like to make a line 10 pixel long with the POINT command, i would have to make 10 POINT command, each time incrementing the X value by one. Lets see this in code:
REMOVETRIGGER LineReplica ON LineReplica DRAW ELEMENT:Earth POINT 100 100 ON LineReplica DRAW ELEMENT:Earth POINT 101 100 ... ON LineReplica DRAW ELEMENT:Earth POINT 109 100
So this will make a horizontal line 10 pixel long. Thats good, but what if i want a line of 100 pixel. Then the WHILE command come into play. So take a look a this:
REMOVETRIGGER LineReplica ON LineReplica SET tmp 0 ON LineReplica WHILE (tmp < 100) LineReplica2 REMOVETRIGGER LineReplica2 ON LineReplica2 DRAW ELEMENT:Earth POINT (100 + tmp) 100 ON LineReplica2 SET tmp (tmp + 1)
Now this may look a little confusing but lets just see this step by step.
So no you see how usefull it could be. Hope i make this clear enough to understant easily.
This example was not very usefull, but this is what Siben's use to make a usefull REPLACEFILLEDRECT function that everyone wanted.