PMC Editing Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Array Tutorial ======

**What are arrays?**

Simplified, you may see them as list. A container that holds multiple parameters. You ca identify a array by it's surrounding square brackets [ ].
You surely already encountered arrays:
<code cpp>
[1,2,3,4] execVM "anyScript.sqf";
</code>
I see you remember. There is a array right in front of the execVM command. In this case, the array passes parameters to "anyScript.sqf" for further use. We will look on this particular array a bit later. Let's start inside scripts first.

**Creating a array.**

Inside a script, a array is build exactly the same way as a variable is defined.
<code cpp>
_myArray = [you, me, him];
</code>

Now we have a array, named "_myArray" and we filled it with 3 people.

**Selecting a specific parameter out of the array**

First, we have to know that index numbering is zero-based. So the very first parameter has index 0 and not 1. To select a specific parameter which position inside the array is known, we use the command select. Example based on the above created array:
<code cpp>
_myself = _myArray select 2;
</code>

Probably you already used the "getPos" command to get a unit's position. This command also returns a array, containing 3 parameters: [lattitude, longitude, altitude] So if we want to know the altitude above ground of any object, we use the select command:
<code cpp>
_myself = _myArray select 2;
_position = getPos _myself select 2;
</code>

"getpos _myself" returns a array from which we select the third parameter, the altitude.

**The "foreach" command**

Probably the most useful command when it comes to arrays. Let us rearm _myself, first without arrays;
<code cpp>
_myself addMagazine "30Rnd_556x45_Stanag";
_myself addMagazine "30Rnd_556x45_Stanag";
_myself addMagazine "30Rnd_556x45_Stanag";
_myself addMagazine "30Rnd_556x45_Stanag";
_myself addMagazine "1Rnd_HE_M203";
_myself addMagazine "1Rnd_HE_M203";
_myself addMagazine "1Rnd_HE_M203";
_myself addMagazine "1Rnd_HE_M203";
_myself addMagazine "15Rnd_9x19_M9";
_myself addMagazine "15Rnd_9x19_M9";
_myself addMagazine "M136";
_myself addWeapon "M4A1_RCO_GL";
_myself addWeapon "M9";
_myself addWeapon "M136";
</code>
It works, but "advanced scripting" looks a bit different.

<code cpp>
{_myself addMagazine "30Rnd_556x45_Stanag"} forEach [1,2,3,4,5,6];
{_myself addMagazine "1Rnd_HE_M203"} forEach [1,2,3,4];
{_myself addMagazine "15Rnd_9x19_M9"} forEach [1,2,3,4];
_myself addMagazine "M136";
</code>

Please take note of the variable "_x". It is part of the foreach command. The foreach command takes each parameter of the array separately, puts it on the place of _x and then executes the command(s).

**Removing elements from an array**

Well, i don't feel comfortable being in one array with _myself. So, let's take "me" out of it. And you don't belong there aswell:
<code cpp>
_myArray = [you, me, him];
_myArray = _myArray - [you, me];
</code>
After that, the array _myArray only holds him. You and me were removed from it.

**Adding elements to an array**

You can also add elements to arrays.
<code cpp>
_myArray = _myArray + [newElement1,newElement2,newElement3];
</code>

These new elements will be appended to the end of the array. So if _myArray began with 2 elements, newElement1 would be at index 2.

**The count command**

Maybe just as (if not more) useful than forEach. Count actually has 2 syntax's. The more common one is simply:
<code cpp>
_arrayLength = count _myArray;
</code>

It will give you the number of elements in _myArray.

The second syntax however is very powerful. It works a lot like forEach, only instead of just executing code, you can test a condition against all elements in the array and it will return the number of elements for which the condition was true.

Ex:
<code cpp>
_myArray =
[
	"30Rnd_556x45_Stanag",
	"30Rnd_556x45_Stanag",
	"30Rnd_556x45_Stanag",
	"30Rnd_556x45_Stanag",
	"1Rnd_HE_M203",
	"1Rnd_HE_M203",
	"1Rnd_HE_M203",
	"1Rnd_HE_M203",
	"15Rnd_9x19_M9",
	"15Rnd_9x19_M9",
	"M136"
];
_numStanagMags =
{
	_X == "30Rnd_556x45_Stanag"
} count _myArray;
</code>

Returns 4.

**Setting elements**

If you want to change the value of an array element without adding/removing (and thus reordering) it, you can use the set command. Set takes an array, an index, and a value as arguments. It takes the array, and replaces the value of the element at the given index with the new given value.
<code cpp>
_myArray = [you, me, him];
_myArray set [2, guy]; // replaces him with guy
</code>

I should also mention that you can use an index outside of the array's current size, and the array will be resized up to the given index (with some default/null value in all the other new indices).

**Nested/2D/XD arrays**

Arrays can contain any variable type, including other arrays. You can use this to create multidimensional arrays. For example, if you want to represent a 2D map with a coordinate system:
<code cpp>
_myMap =
[
[ 0 , 0 , 0 , 0 , A , 0 , 0 , B ],
[ 0 , 0 , C , 0 , 0 , D , 0 , 0 ],
[ 0 , 0 , 0 , 0 , 0 , 0 , E , 0 ]
];
_valueD = (_myMap select 1) select 5;
</code>

The index of the primary array would be your Y coordinate, and the index in the subarray at index Y is your X coordinate.

You can also use nested arrays to pass arrays to scripts along with individual arguments.
<code cpp>
_handle = [1, 5, [0, 1, 2], "Hello", [player, "goodbye"]] execVM "myScript.sqf";
</code>

Inside of myScript.sqf:
<code cpp>
_this select 2; // contains the array [0, 1, 2];
_this select 4; // contains the array [player, "goodbye"];
</code>

**Advanced**

Operator + is in fact very slow compared to the set command (10 times according to my last test).

If you are working with large arrays you might want to consider putting that little extra effort in. Adding 1 element to an array:
<code cpp>
_array1 = _array1 + [1]; // +
_array2 set [count _array2, 1]; // set
</code>
Adding elements from 1 array to another:
<code cpp>
_array1 = [0,1,2,3,4];
_array2 = [0,1,2,3,4];
_arrayAdd = [5,6,7,8,9];

_array1 = _array1 + _arrayAdd; // +
// set:
for "_i" from 0 to ((count _arrayAdd) - 1) do
{
     _array2 set [count _array2, _arrayAdd select _i];
};
</code>
PMC Editing Wiki

User Tools

Site Tools

Page Tools
