_this

This
====


I've made this short tutorial to give you a crash course on what exactly "this" or "_this" is.

There are basically three places where you see them:

In "init" fields of units
In scripts
In the condition fields of triggers & waypoints

Each of these three areas covers a different skill level of mission editing, so this tutorial is for editors of a wide range of skill.

If you are just starting out editing, you only need to understand the first part of the tutorial ("This" in Init Fields).
If you are starting to get into advanced editing or scripting, you should read and understand the entire tutorial.
There really isn't that much to it, because I'm only covering two little words...

  Now, let's get into it....



"This" in Init Fields
=====================

First off, what is an "init" field?
Basically, it is a place that you put little lines of code that will be run at the beginning of the mission.
I'm sure you've seen many bits of code that you can put in init fields, to do different things with that unit, like:

    	this setdammage 1  ->  kills the unit
    	this addweapon "m16"  ->  adds an m16 to the unit
    	this moveindriver helo1  ->  moves unit into driver seat of helo1

Now, the question is, how come you have to put these lines in a unit's init field?
Is there something special about the init field?
Could I put something in one unit's init field, and have it affect another unit?
Without getting into scripting, I'll just tell you that what you are looking at is almost exactly the same as the kinds of things you put in scripts.
The difference is, yes, there is something special about the init field of a unit.
And that thing is "this".

"This" (or "this", or "tHiS"; capitalization doesn't matter) is a special word ("command"). When you put it in the "init" field of a unit, "this" is just another way of saying "the unit who's init field I'm editing right now".

Lets look at one of the above lines again:

    	this setdammage 1

The line has three parts.
The middle part is the command ("setdammage").
What is put in the rest of the line, and what it all does, depends on the command you are using.
In this case, the command will hurt a certain unit to a certain damage level.
The right part of the line is what damage level we hurt the unit to (0 being no damage, 1 being full damage).
The first part of the line is what unit we are going to hurt.

In this case, we put "this" in as the "unit" we want to hurt.
Since we are putting this in a unit's init field, that unit will be hurt.
Again: "this" is another way of saying "the unit who's init field I am editing right now".

Instead of using "this", we could simply name a unit (by entering something in his "name" box), and then use that name in one of the code bits we looked at above.
So we could make a unit, and name him "bob".
Then we could place a new unit, and in his init field, put:

    	bob setdammage 1

In this case, the first unit we placed ("bob") would be killed, NOT the unit who's init field we put that line in!
So really, "this" is just a way to save us time, because it lets us refer to a unit without using his name.

To give you an example of this, let's say we want to make all the units we place stand up, all the time.
To do so, we could place a unit, name him "a", and then put this in his init field:

    	a setunitpos "up"

Then we could make a unit, name him "b", and put in his init field:

    	b setunitpos "up"

Then make a unit named "c", and one named "d", and so on.
This would be a real pain, wouldn't it?

Well, instead of doing all that, we could just make one unit, and put in his init field:

    	this setunitpos "up"

Then we could just copy and paste that unit to our heart's content, without ever changing his init field.
Doesn't that seem easier?


A last word on init fields:

There is nothing else special about them, except that they run code at the start of the mission, and "this", which I just talked about.
Lines of code that don't use "this" can be put anywhere, the only difference is when that code is run.
Init fields always run at the start of the mission, while "on activation" fields of triggers will run when that trigger goes off.
That is really all there is to know about "this" and init fields.
You likely won't understand the rest of the tut unless you know a little about scripting. For those of you who do, I'll go on.



"This" in Condition Fields
==========================

Place a new trigger.
Open it up, and all you will see in it's condition field is "this".
So what the heck does that mean?

It isn't the same as in init fields, that wouldn't make any sense.
Well, you know all those conditions that you set in the "activation" part of the trigger? Those are "this".
Okay, I know that doesn't make sense, so a little explanation is in order:


The Quick and Dirty on Boolean Expressions
------------------------------------------

The "condition" field uses something called a boolean expression.
"Boolean" (named after the English mathematician George Boole) means that it is either TRUE or FALSE.

You likely have seen something similar in algebra classes:

      	x > 7

In this case, the above expression is TRUE when x is greater than 7, and is FALSE when x is less than or equal to 7.
Many OFP commands return "boolean" values (true or false).

For example, "alive player" will return true when the player is alive, and false when he is dead.

Boolean expressions can be more complicated than one little operation.

That is where the commands "and" (same as "&&") and "or" (same as "||") come in.
They mean the same thing as they do in english.

"AND" means "this condition AND that condition must be true", while "or" means "this condition OR that condition must be true".

For example:

    	(x > 7) AND (alive player)

The entire expression will return true when x is greater than 7, AND the player is alive.
If either the left or the right statement is false, the expression as a whole will be false.
"OR" works in a similar way:

    	(x > 7) OR (alive player)

This will be true when EITHER x is greater than 7, OR the player is alive.
If either side (or both) of the expression is true, then the whole expression will be true.

There is one last boolean operator, as they are called, in OFP: NOT (same as !).
"NOT" will return the opposite of whatever is next to it.

So for example:

      	NOT (x > 7)

The part in parenthesis (x > 7) will be true when x is above 7.
However, since the NOT is there, the expression as a whole will be FALSE when x is above 7.

Generally you should avoid using NOT if you can, since it can be confusing.
In the above example, we could have just said (x <= 7).

But sometimes we have to use NOT, like if we want to return true when the player is dead:

	!(alive player)

There is no limit to how much you can use boolean operators.
And remember, there are 2 different ways to "spell" each one (AND + &&, OR + ||, NOT + !).

For example:

    	((x > 7) || (alive player)) && (!(alive bob))

My last word of advise when using boolean expressions is to USE LOTS AND LOTS OF PARENTHESIS!
Just like in normal math, there is an order of operations for boolean expressions.
If you don't use parenthesis, the expression may be evaluated differently than you expect!


Back to "This"
--------------

The condition field of triggers use boolean expressions, like we learned about above.
The trigger will only "fire" once the boolean expression in it's condition field is true.

So what about "this"?

"This" refers to everything you set in the "activation" part of the trigger.
If you make a trigger that is set for "west present", then "this" will become true once a west unit is in the trigger area.
Normally there is only "this" in the condition field, so normally the trigger will only fire when the condition ("west present") is met.

However, using the stuff we learned above, we can now make more complex triggers.
For example, we could set a trigger to activate when you radio "alpha".

In it's condition field, we could write:

    	this && (alive bob)

Now, the trigger will only "fire" when you radio, AND bob is alive.

As you can see, you can now make much more complex conditions for your triggers!

One last note is that if you erase "this" entirely from the condition field, it then doesn't matter what properties you set in the 'activation' section of the trigger, it will only depend on what is in the condition field.


Waypoints are very similar.
With waypoints, "this" is true when the unit goes to the waypoint.

So if we made a waypoint with the condition:

    	this && (alive bob)

The waypoint would only be "completed" (meaning the unit will go to his next waypoint, and the 'on activation' field of the waypoint will be executed) when the group goes to the waypoint, AND bob is alive.
If bob died before the group made it to the waypoint, then the waypoint would never be completed, and the group would never move on.

 Simple, right?
Well, now you know all there is to know about condition fields and using "this" in them.
You'll be happy to know that boolean expressions are also HIGHLY useful in scripting (in the ? command), so if you didn't know about them or understand them before, you are now ready to learn more about scripting from your favorite scripting tutorial.

Now, onto the next section, which deals exclusively with scripts.



"_This" in Scripts
==================

Alright, if you're still with me, it means you have started to make your own scripts.
That's good; now I'll clear up something that seems to be confusing for most beginning scripters, and is even slightly misunderstood by many experienced scripters.

In every script, we have access to a special variable called "_this".

What is held in that variable changes depending on how you call the script, and by using and understanding that variable, we can move beyond just making a list of commands, and into really making a script.

First, lets take an example:

      	player exec "myscript.sqs"

That will execute myscript.sqs.
Now in that one instance (a script can be run multiple times at the same time, each one that is running is called an "instance") of myscript.sqs, the variable "_this" will refer to the player.
Why?
Because the player ("player") is what we put next to "exec"; so that is what is passed into "_this".

Notice that "_this" has an underscore next to it, which means that it is a local variable.

If you don't understand what that means, you need to go back and read your scripting tut again, because it is CRUCIAL that you understand the difference between a local variable and a global variable.

I'll say it again, whatever you put next to "exec" when executing a script, will be passed to the script in the variable "_this".

One important thing worth noting, is that if you put a variable next to "exec", the value currently in that variable will be sent to the script (not the actual variable).

For example:

    	VAR exec "myscript.sqs"

Will pass whatever the current value of VAR is to the script.

If you then make changes to that value (_this) in the script, VAR will not change.
Likewise, if VAR changes after you run the script, the value in the script (_this) will not change either.

You can put any type of variable next to exec.
An object, a number, an array, etc.
Most of the time, arrays are used, because you can then pass more than one piece of data to the script.

For example, if we say:

  	[player, 5] exec "myscript.sqs"

Then "_this" in that instance of the script will be an array, that holds the player and the number 5.
If we want to access certain elements in the array, we need to use the "select" command.

For example, to get the first element of the array (the player, in this case), we need to type:
    	_this select 0

Usually (but not always) you will want to save all the elements in the "_this" array to new variables, to make things easier for yourself, which is why most scripts look something like this:

    	_unit = _this select 0
    	_count = _this select 1

But keep in mind that you don't have to 'extract' all the elements of the array to their own variables.
If you only use a certain part of the array once or twice, it is better to not make a new variable, because variables just take up CPU power, which believe it or not makes a difference when you are using lots of scripts.

So, in the above example, if we only needed to use "_count" one time, we could do it like this:

    	_max = 2*(_this select 1)

One final thing, is that functions use _this just like scripts do, as you will see if you begin writing functions.


Special Scripts and _This
=========================

There are two special scripts where you can't specify the value of _this, because it is defined for you.

First, there are scripts run by actions, added via the addaction command.
For these scripts, _this is always an array with three elements:

	The object the action was attached to
	The unit that used the action
	The index of the action

Next, there are eventhandlers.

Each different eventhandler has different values for _this.



The Last Word
=============

I hope you found this tutorial useful.
It is the first OFP tutorial I have written, but I hope it is understandable.

Please post some comments and suggestions, such as what was unclear, what needs to be explained better, what to add, etc, so that I can revise the tut in the future.

Have fun editing!