Emanuele Feronato

Talking about HTML5, Javascript and Phaser.

Since Phaser is mainly a HTML5 framework, you may think you can use it to draw, animate and tween stuff on canvas to create your games, while other kind of routines like array management must be scripted directly with pure JavaScript.

It’s not true, because Phaser comes with some interesting utilities which will help you during the creation and the manipulation of arrays, handling some commons operations such as array population, picking a random array item, and some other interesting stuff we are going to see in this post.

The class responsible of array operations is ArrayUtils, and you can find the official docs at this page, however I found this class very interesting so I decided to write a more detailed guide.

We start with the creation of an empty array called testArray:

var testArray = [];

Launching a console.log of the array, we get:

[]

Now that we have an empty array, let’s see what can we do with it.

POPULATING ARRAYS

With numberArray(start, end) we can populate the array with the inclusive range of numbers from start to end, determined increasing start by one.

testArray = Phaser.ArrayUtils.numberArray(0, 10);

This way we get 11 items in the array, with integer numbers from 0 to 10, both included

[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

What if we pass non integers arguments?

testArray = Phaser.ArrayUtils.numberArray(0.5, 10);

While start is included, this time end is not included and the array ends with the highest number lower than end:

[0.5, 1.5, 2.5, 3.5, 4.5, 5.5, 6.5, 7.5, 8.5, 9.5]

What if start and end have the same value?

testArray = Phaser.ArrayUtils.numberArray(10, 10);

We’ll have an array with one item:

[10]

What if start is greater than end?

testArray = Phaser.ArrayUtils.numberArray(10, 0);

We’ll have an rmpty array:

[]

numberArrayStep is a bit more complete than numberArray because it allows us to define a step during the creation of the array, so if we want start to be greater than end, for example, we just have to write:

testArray = Phaser.ArrayUtils.numberArrayStep(10, 0, -1);

Look, this time is not inclusive:

[10, 9, 8, 7, 6, 5, 4, 3, 2, 1]

end is never included in the generated array in using numberArrayStep:

testArray = Phaser.ArrayUtils.numberArrayStep(0, 20, 2);

look, there’s no 20 in the array

[0, 2, 4, 6, 8, 10, 12, 14, 16, 18]

You can also use float numbers:

testArray = Phaser.ArrayUtils.numberArrayStep(0, 20, 1.5);

and you’ll get:

[0, 1.5, 3, 4.5, 6, 7.5, 9, 10.5, 12, 13.5, 15, 16.5, 18, 19.5]

Just remember JavaScript has some inaccuracy with float numbers, and this code:

testArray = Phaser.ArrayUtils.numberArrayStep(0.5, 1, 0.1);

Won’t return the result you may expect:

[0.5, 0.6, 0.7, 0.7999999999999999, 0.8999999999999999]

Also, both numberArray and numberArrayStep methods do not add items to an array but they actually create an array with such items, so these two lines of code:

testArray = Phaser.ArrayUtils.numberArray(1, 10);
testArray = Phaser.ArrayUtils.numberArray(11, 20);

Will return:

[11, 12, 13, 14, 15, 16, 17, 18, 19, 20]

You can also create multi-dimensional arrays, such as:

testArray = [Phaser.ArrayUtils.numberArray(1, 10), Phaser.ArrayUtils.numberArray(11, 20), Phaser.ArrayUtils.numberArray(21, 30)];

Which will return

[[1, 2, 3, 4, 5, 6, 7, 8, 9, 10], [11, 12, 13, 14, 15, 16, 17, 18, 19, 20], [21, 22, 23, 24, 25, 26, 27, 28, 29, 30]]

SHUFFLING ARRAYS

To shuffle an array, shuffle method will apply the Fisher-Yates algorithm to return the shuffled array. The Fisher–Yates shuffle is an algorithm for generating a random permutation of a finite set. In plain terms, the algorithm shuffles the set and you can find a lot of interesting information in this Wikipedia page.

Long story short, it’s a good way to shuffle arrays, here it is:

testArray = Phaser.ArrayUtils.numberArray(1, 10);
Phaser.ArrayUtils.shuffle(testArray);

And the result is the shuffled array.

[1, 3, 2, 4, 7, 5, 9, 8, 10, 6]

Results vary each time you call shuffle method

shuffle is also not recursive, so it will work partially when shuffling multi-dimensional arrays:

testArray = [Phaser.ArrayUtils.numberArray(1, 10), Phaser.ArrayUtils.numberArray(11, 20), Phaser.ArrayUtils.numberArray(21, 30)];
Phaser.ArrayUtils.shuffle(testArray);

Will return something like

[[11, 12, 13, 14, 15, 16, 17, 18, 19, 20], [1, 2, 3, 4, 5, 6, 7, 8, 9, 10], [21, 22, 23, 24, 25, 26, 27, 28, 29, 30]]

Where inner arrays aren’t shuffled.

PICKING RANDOM ITEMS FROM ARRAYS

When we need to pick random items from an array, Phaser gives us two opportunities: we can simply pick a random item or we can pick a random item and remove it from the array.

getRandomItem method will return a random item in the array

testArray = Phaser.ArrayUtils.numberArray(1, 10);
var item = Phaser.ArrayUtils.getRandomItem(testArray);

this code once execute will store into item variable a random testArray item.

We can also specify another argument which is the start index

testArray = Phaser.ArrayUtils.numberArray(1, 10);
var item = Phaser.ArrayUtils.getRandomItem(testArray, 9);

now item will be null if the random item is one of the first 8 items in the array (numbers from 1 to 9), or a random item from the 9th on, which in this case can only be 10.

The last argument we can specify is the number of values we want to randomly select.

testArray = Phaser.ArrayUtils.numberArray(1, 10);
var item = Phaser.ArrayUtils.getRandomItem(testArray, 2, 3);

in this case item will be the item with index greater or equal to 2 chosen among the three items with index 2, 3 and 4.

removeRandomItem works in the same way as getRandomItem but it also removes the item from the array

testArray = Phaser.ArrayUtils.numberArray(1, 10);
var item = Phaser.ArrayUtils.removeRandomItem(testArray);

if item is 4, then testArray will be [1, 2, 3, 5, 6, 7, 8, 9, 10]

removeRandomItem accepts the same extra arguments as getRandomItem working in the same way, and both getRandomItem and removeRandomItem do not work recursively on multi-dimensional arrays, so

testArray = [Phaser.ArrayUtils.numberArray(1, 10), Phaser.ArrayUtils.numberArray(11, 20)];
var item = Phaser.ArrayUtils.removeRandomItem(testArray);

will return for example item as an array [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] and testArray as the remaining array [[11, 12, 13, 14, 15, 16, 17, 18, 19, 20]]

FINDING ITEMS

If you have a sorted array, you can find the closest item to a value with findClosest method.

testArray = Phaser.ArrayUtils.numberArray(1, 10);
var item = Phaser.ArrayUtils.findClosest(5, testArray);

Will return 5 while

testArray = Phaser.ArrayUtils.numberArray(1, 10);
var item = Phaser.ArrayUtils.findClosest(5.6, testArray);

will return 6

ROTATING ARRAYS

Arrays can also be rotated with rotateLeft and rotateRight methods.

testArray = Phaser.ArrayUtils.numberArray(1, 5);
var item = Phaser.ArrayUtils.rotateLeft(testArray);

At the end of the script, testArray from [1, 2, 3, 4, 5] will be [2, 3, 4, 5, 1] and item will be 1.

Following the same concept, with

testArray = Phaser.ArrayUtils.numberArray(1, 5);
var item = Phaser.ArrayUtils.rotateRight(testArray);

Will make the array be [5, 1, 2, 3, 4] and item to be 5

ROTATING TWO DIMENSIONAL ARRAYS

This is by far the most interesting feature of ArrayUtils class as it works on two-dimensional arrays. A two-dimensional array is also called a Matrix. With rotateMatrix method we can rotate a two-dimensional array of an angle of 90, 180 or 270 degrees.

testArray = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
testArray = Phaser.ArrayUtils.rotateMatrix(testArray, 90);

will change testArray from

[
[1, 2, 3],
[4, 5, 6],
[7, 8, 9]
]

to

[
[3, 6, 9],
[2, 5, 8],
[1, 4, 7]
]

actually rotating it counter clockwise

testArray = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
testArray = Phaser.ArrayUtils.rotateMatrix(testArray, 180);

will change testArray from

[
[1, 2, 3],
[4, 5, 6],
[7, 8, 9]
]

to

[
[9, 8, 7],
[6, 5, 4],
[3, 2, 1]
]

flipping it horizontally and vertically and

testArray = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
testArray = Phaser.ArrayUtils.rotateMatrix(testArray, 270);

will change testArray from

[
[1, 2, 3],
[4, 5, 6],
[7, 8, 9]
]

to

[
[7, 4, 1],
[8, 5, 2],
[9, 6, 3]
]

actually rotating it clockwise.

Finally transposeMatrix method will transpose the two-dimensional array:

testArray = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
testArray = Phaser.ArrayUtils.transposeMatrix(testArray);

and testArray will change from

[
[1, 2, 3],
[4, 5, 6],
[7, 8, 9]
]

to

[
[1, 4, 7],
[2, 5, 8],
[3, 6, 9]
]

Basically rows become columns and columns become row.

I hope you will find all these methods useful in your projects.