Array Guide

An Array is like a variable with multiple "slots." Each slot can be considered a space on a shelf, i.e: if you had a shelf that was ten slots across and two high, then you could put an object (or number) in any of those slots.

Array Index

Each of the slots are accessed using an array index. The array index is a number that identfies each slot, for example : slot 1, slot 2, slot 3, etc. In GML this appears as :

// GML Array Index Code Example

an_array[1] = "slot 1";
an_array[2]= "slot 2";
an_array[3] = "slot 3";

The array index must be a positive number. Using a negative number (i.e. -5) will cause an error. The lowest an array index can be is and the highest is 32,000. 2d arrays have a limit of 1,000,00 total array slots.

Creating Arrays

You can create an array just like you create a variable — just give one of it's slots a value :

an_array[1]  = "This array has been created."

After the line of GML code has been executed, the array will be created with one slot that contains This array as been created. To add more indexes, just give more indexes values.

2D Arrays

2D arrays are just like 1D arrays (above) except they have two indexes which allows it to hold a "grid of data." Compare the grid and 2D array declaration below :

1 2 3
1 1-1 1-2 1-3
2 2-1 2-2 2-3
3 3-1 3-2 3-3
anArray[1,1] = "1-1";
anArray[1,2] = "1-2";
anArray[1,3] = "1-3";

anArray[2,1] = "2-1";
anArray[2,2] = "2-2";
anArray[2,3] = "2-3";

anArray[3,1] = "3-1";
anArray[3,2] = "3-2";
anArray[3,3] = "3-3";

Uses and Applications

Keeping Track of Multiple Objects

Arrays are very useful when you are looping or doing some repeated jobs.

for( i=0; i<100; i+=10 )  //repeat the whole action ten times
    bullets[i]  =  instance_create(x+i,y,obj_bullet)
    bullets[i].vspeed  =  -7

The above code will generate ten bullets right side of your character, each have 10px spacing, and running upwards at speed 7.

Holding Menu Choices

Arrays are commonly used in making menus. They hold each menu choice (or selection) which then can be displayed with draw_text(). Here is how an array would be used to hold the options for a simple title menu :

menu_options[1] = "Start";
menu_options[2] = "Options";
menu_options[3] = "End Game";

Choosing Data Randomly

You can use an array to choose a piece of data randomly.

Choose a Random Name

names[1] = "Bob";
names[2] = "Zippy";
names[3] = "Drizzt";

random_index = ceil(random(3));

random_name = names[random_index];

If the units of data you have to randomly choose from are less than 16, a more simple way to do this is to use the choose() function.

Built In Arrays

Game Maker has a number of built-in arrays that serve various purposes and have different scopes, depending on the intended purpose. For a list of these arrays, see list of arrays.

Array Length

There seems to be now certain way to check the length of an array (length being the total number of indexes, this also being referred to as the size of the array). Game Maker's array support is known to be notoriously bad in comparison with other tools and languages. To make up for this, several advanced data structures were created and added to Game Maker : lists, queues, stacks, maps, priority queues, and grids — all of which have very good functions to help you manage and use them. Unfortunately, all of these data structures became pro features as soon as they were introduced.