GameMaker has some new functions that give you easier and powerful ways to read and modify arrays.
Many of these functions make use of "callback methods", which can be challenging to understand.
So let’s break it down!
What Are Arrays?
If you’re not familiar with arrays, this manual page should give you a good overview.
Many array functions make use of "methods", so I suggest reading about methods in the manual.
Callback Basics
The array_foreach() function is the simplest example using a callback.
You take an array, run array_foreach() on it, and give it a method/function to run. For each element in the array, your callback method runs.
The “callback method” is just a simple method you made yourself.
It basically flips each page in a book, telling you “here’s a page!”, along with information about that page.
Example
Let’s call array_foreach() on an array that has 4 elements (values). array_foreach() goes through the array and runs your callback for each element, as shown above.
array_foreach() also supplies two arguments to your callback: the value of that element, and its index (0, 1, 2, etc…).
Here is a code example:
var _array = [11, 22, 33, 44, 55];
array_foreach(_array, function(_val, _index)
{
show_debug_message("{0} at index {1}", _val, _index);
});This runs array_foreach on an array, printing the value and index for every element to the output log:
11 at index 0
22 at index 1
33 at index 2
44 at index 3
55 at index 4
You can write the same code in a cleaner way, defining the method first and then passing it into the array_foreach() call:
var _array = [11, 22, 33, 44, 55];
var _callback = function(_val, _index)
{
show_debug_message("{0} at index {1}", _val, _index);
}
array_foreach(_array, _callback);array_map
Let’s take it a step further.
array_map() works the same way as the previous function: it takes an array and a callback method, and runs your callback on each array element.
But this time, your callback method is actually allowed to return a value.
This allows you to change the element in the array. What your callback returns is applied back to the same element, but in a new copy of the array.
At the end of the function, it gives you the modified array. The original array is not changed.
Let’s use this function to double all values in our array:
var _array = [11, 22, 33, 44, 55];
var _callback = function(_val, _index)
{
return _val * 2;
}
var _new_array = array_map(_array, _callback);
show_debug_message(_new_array);The array is the same as before, and the callback just returns the value multiplied by 2.
Then we feed that into array_map(), which creates a new array with all values doubled, thanks to our callback.
The new array is then printed to the output log, so you should see this:
[ 22,44,66,88,110 ]
Predicate Method
Some array functions use a predicate method. Don’t worry, it’s just a callback method with one specific requirement.
If your callback method can only return true or false, then it’s a predicate method.
Such a function is used to tell whether an element qualifies or not. With this technique, you can do many kinds of operations on an array.
Finding An Index
You’ve got an inventory array, and you want to know if there’s a sword in it. You also want to know exactly where that sword is in the array.
array_find_index() does exactly that. It takes a predicate method, and when that method returns true, it gives you the index of the element where it returned true.
Let’s work with the array: [“shield”, “sword”, “potion”] and run array_find_index() to find the “sword” element. Here’s how it will work:
Here’s what the code looks like:
var _array = ["shield", "sword", "potion"];
var _predicate = function (_val, _index)
{
return _val == "sword";
}
var _sword_id = array_find_index(_array, _predicate);
show_debug_message(_sword_id);The predicate function here returns true when the value equals “sword”, otherwise, it returns false.
We then feed that into array_find_index(), which gives us 1, the index where the string “sword” was found.
All And Filter
array_all() lets you run a predicate method on all elements in an array, and returns true if your predicate was true for all elements.
This can be used to tell if every element in the array is the same, or qualifies a certain condition.
array_filter() also uses a predicate, and creates a new array with only the qualifying elements. This way you can filter an array, to remove anything you don’t need, using the predicate function as a condition.
Let’s say you have the array: [5, 11, 15, 6] and you only want the values above 10. array_filter() will do that for you:
Reduce
array_reduce() lets you run a callback on every element and return something. Whatever you return for one element, is passed into the next callback. This way you can process your array in a sequential order.
At the end, you get whatever your callback returned for the last element.
You can see how the callback doesn’t run for the first element. It starts with the second element (11) as the current "value", with the first element (5) fed into it as the “previous” argument.
The value returned by your first callback is passed into the next callback as the "previous" value, and then that callback's return is passed into the next callback, until it's gone through all elements.
You can optionally specify a starting value which is fed into the first callback, and if you do so, your callback will run for the first element too.
More Array Functions
array_create_ext() lets you create a new array with a callback method. This callback runs for each element and its return value is stored in that element.
This is useful when you want to generate an array with a range of values, or use some calculations to come up with your array elements.
var _array = array_create_ext(10, function(_index)
{
return 1 + _index;
});
show_debug_message(_array);This will create an array where each element holds its index increased by 1, giving you this array: [ 1,2,3,4,5,6,7,8,9,10 ]
There are some functions for joining arrays in different ways:
- array_concat() joins the given arrays into one array
- array_union() joins the given arrays, removing duplicates
- array_intersection() gives you the values that exist in all the given arrays
- For example, if you give it three arrays, and the number 64 exists in all arrays, it will be included
- However if the number 48 only exists in array 1 and 3, but not in the second one, it won’t be included
Check out more array functions in the manual.
Happy GameMaking!