The Array module provides JavaScript-style array methods for manipulating arrays in GSC scripts. These functions follow ES5 array conventions.
Module Import
#include unleashed\array;
All array functions use self as the array to operate on. Call them using the [[function]]() syntax.
Iterator Functions
forEach()
Calls a function for each element in the array.
players = getAllPlayers();
players [[unleashed\array::forEach]](::printPlayerName);
printPlayerName(player, index, array) {
iPrintLn("Player " + index + ": " + player.name);
}
callback - Function to execute for each element. Receives (element, index, array)
Returns: Nothing
map()
Creates a new array with the results of calling a function on every element.
scores = [10, 20, 30];
doubled = scores [[unleashed\array::mapArray]](::doubleValue);
// Result: [20, 40, 60]
doubleValue(value, index, array) {
return value * 2;
}
The function is named mapArray (not map) to avoid conflicts with the built-in map keyword.
callback - Function to execute on each element. Receives (element, index, array)
Returns: New array with mapped values
filter()
Creates a new array with elements that pass a test.
scores = [50, 75, 30, 90, 45];
highScores = scores [[unleashed\array::filter]](::isHighScore);
// Result: [75, 90]
isHighScore(score, index, array) {
return score >= 70;
}
callback - Function that returns true to keep element. Receives (element, index, array)
Returns: New filtered array
find()
Returns the first element that satisfies the test function.
players = level.players;
target = players [[unleashed\array::find]](::hasHighScore);
hasHighScore(player, index, array) {
return player.score >= 1000;
}
callback - Test function. Receives (element, index, array)
Returns: First matching element or undefined
findIndex()
Returns the index of the first element that satisfies the test function.
names = ["John", "Jane", "Bob"];
index = names [[unleashed\array::findIndex]](::isJane);
// Result: 1
isJane(name, index, array) {
return name == "Jane";
}
callback - Test function. Receives (element, index, array)
Returns: Index of first match or -1
Test Functions
every()
Returns true if every element passes the test.
scores = [80, 90, 85, 95];
allPassed = scores [[unleashed\array::every]](::isPassing);
// Result: true
isPassing(score, index, array) {
return score >= 70;
}
true if all elements pass, false otherwise
some()
Returns true if at least one element passes the test.
scores = [50, 60, 80, 45];
anyPassed = scores [[unleashed\array::some]](::isPassing);
// Result: true (80 passes)
isPassing(score, index, array) {
return score >= 70;
}
true if any element passes, false otherwise
includes()
Determines whether an array contains a certain element.
weapons = ["ak47", "m16", "mp5"];
hasM16 = weapons [[unleashed\array::includes]]("m16");
// Result: true
item - Element to search for
Returns: true if found, false otherwise
Search Functions
indexOf()
Returns the first index of an element.
colors = ["red", "green", "blue", "green"];
index = colors [[unleashed\array::indexOf]]("green");
// Result: 1
-1
lastIndexOf()
Returns the last index of an element.
colors = ["red", "green", "blue", "green"];
index = colors [[unleashed\array::lastIndexOf]]("green");
// Result: 3
-1
reduce()
Reduces array to a single value by applying a function.
numbers = [1, 2, 3, 4, 5];
sum = numbers [[unleashed\array::reduce]](::add, 0);
// Result: 15
add(accumulator, value, index, array) {
return accumulator + value;
}
callback - Reducer function. Receives (accumulator, element, index, array)initialValue - Starting value for accumulator
Returns: Final accumulated value
reduceRight()
Same as reduce but processes from right to left.
words = ["!", "World", "Hello"];
sentence = words [[unleashed\array::reduceRight]](::concat, "");
// Result: "HelloWorld!"
Modification Functions
push()
Adds elements to the end of an array.
arr = [1, 2, 3];
arr = arr [[unleashed\array::push]](4);
// Result: [1, 2, 3, 4]
item - Single element or array of elements to add
Returns: New array with added elements
pop()
Removes the last element from an array.
arr = [1, 2, 3, 4];
arr = arr [[unleashed\array::pop]]();
// Result: [1, 2, 3]
shift()
Removes the first element from an array.
arr = [1, 2, 3, 4];
arr = arr [[unleashed\array::shift]]();
// Result: [2, 3, 4]
unshift()
Adds elements to the beginning of an array.
arr = [3, 4];
arr = arr [[unleashed\array::unshift]]([1, 2]);
// Result: [1, 2, 3, 4]
item - Single element or array of elements to add
Returns: New array with prepended elements
splice()
Adds and/or removes elements from an array.
arr = [1, 2, 3, 4, 5];
arr = arr [[unleashed\array::splice]](1, 2);
// Removes 2 elements starting at index 1
// Result: [1, 4, 5]
start - Index to start at (negative counts from end)deleteCount - Number of elements to remove (optional)items - Elements to insert (optional)
Returns: Modified array
slice()
Extracts a section of an array.
arr = [1, 2, 3, 4, 5];
sub = arr [[unleashed\array::slice]](1, 4);
// Result: [2, 3, 4]
start - Starting index (negative counts from end)end - Ending index, exclusive (optional)
Returns: New array containing extracted elements
Utility Functions
reverse()
Reverses the order of elements.
arr = [1, 2, 3, 4, 5];
reversed = arr [[unleashed\array::reverse]]();
// Result: [5, 4, 3, 2, 1]
join()
Joins all elements into a string.
words = ["Hello", "World", "!"];
text = words [[unleashed\array::join]]();
// Result: "HelloWorld!"
Unlike JavaScript’s join(), this function does not support a separator parameter. Elements are concatenated directly.
getLength()
Returns the number of elements in an array.
arr = [1, 2, 3, 4, 5];
len = arr [[unleashed\array::getLength]]();
// Result: 5
This is equivalent to using array.size but provided for consistency with JavaScript conventions.
Complete Example
processPlayerScores() {
// Get all player scores
players = level.players;
scores = players [[unleashed\array::mapArray]](::getPlayerScore);
// Filter high scores
highScores = scores [[unleashed\array::filter]](::isHighScore);
// Calculate average
total = highScores [[unleashed\array::reduce]](::add, 0);
average = total / highScores.size;
// Find top scorer
topScore = highScores [[unleashed\array::reduce]](::max, 0);
iPrintLn("Average high score: " + average);
iPrintLn("Top score: " + topScore);
}
getPlayerScore(player, index, array) {
return player.score;
}
isHighScore(score, index, array) {
return score >= 1000;
}
add(acc, val, index, array) {
return acc + val;
}
max(acc, val, index, array) {
if (val > acc) return val;
return acc;
}
See Also