Before continuing with this overview of GML, it's very important to observe that the formatting used in GML programs is snake case. Though it is not necessary to use this formatting, the built-in methods and constants of GML use it; so, for the sake of readability and consistency, it is recommended that you use snake casing, which has the following requirements:

As previously mentioned, the same variable can be assigned to any of the mentioned variable types, which can cause a variety of problems. To combat this, the prefixes of variable names usually identify the type of data stored within the variable, such as str_player_name (which represents a string). The following are the common prefixes that will be used throughout this book:

Within GML scripts, variables have different scopes. This means that the way in which the values of variables are accessed and set varies. The following are the different scopes:

The following example demonstrates the assignment of different variable types:

// Local variable assignment.
var a = 1;

// Global variable declaration and assignment.
globalvar b;
b = 2;

// Alternate global variable declaration and assignment.
global.c = 10;

// Instanced variable assignment through the use of "self".
self.x = 10;

/* Instanced variable assignment without the use of "self".  Works identically to using "self". */
y = 10;

Creating custom constants

Custom constants can be defined by going to Resources | Define Constants... or by pressing Shift + Ctrl + N. In this dialog, first a variable name and then a correlating value are set. By default, constants will appear in the same color as built-in variables when written in the GML code. The following screenshot shows this interface with some custom constants created:

As mentioned previously, some functions require arguments. When creating a script, these arguments can be accessed within the script using the keywords argument0 through argument15, allowing for up to 16 different values if necessary.

Expressions can be manipulated and evaluated using different symbols. The equals sign or assignment operator = sets the value of a variable as shown in the following code:

// Assigning a variable with a value.
a = 10;

/* Assigning a different variable with an expression, in this case, the sum of the previously declared variable and 7.5. */
b = (a + 7.5);

Expressions can also be combined with basic mathematical operations, as shown in the following code:

// Addition and subtraction, + and -
val = a + 20 - b;

// Multiplication and division, * and /
val = a * 20 / b;

/* Expressions encased in parenthesis, ( and ), will be evaluated first. */
val = (a + 20) * (b - 40);

// + can also be used to concatenate, or link, strings together. 
str = "hello " + "world";

Mathematical operations can be combined with = to create a compound assignment operator and perform relative addition, subtraction, multiplication, or division, as shown in the following code:

// Relative addition, +=
x += y; // equivalent to x = x + y;

// Relative subtraction, -=
x -= y; // equivalent to x = x – y;

// Relative multiplication, *=
x *= y; // equivalent to x = x * y;

// Relative division, /=
x /= y; // equivalent to x = x / y;

The main advantage of this code is its extreme simplicity. In the previous examples, x is a simple variable to type out, but if a variable name is longer, the preceding code cuts down on having to unnecessarily retype that name on both sides of the assignment operator.

Variables can also be incremented by one value as shown in the following code:

var a, b, c, d, str_a, str_b, str_c, str_d;
a = 1;
b = 1;
c = 1;
d = 1;

// The return string will be "1" but a's value is now 2.
str_a = string(a++);

// The return string will be "2" and b's value is 2.
str_b = string(++b);

// The return string will be "1" but c's value is 0;
str_c = string(c--);

// The return string will be "0" and d's value is 0;
str_d = string(--d);

In summary, if ++ or -- is included after the variable, the variable's current value is returned and then is incremented. If ++ or -- is set before the variable, its current value is incremented and that new value is returned.

Boolean comparisons, as shown in the following code, compare expressions and return the values true or false, which are GML constants equal to 1 and 0 respectively:

// Less than, <
if (a < 20) { instance_create(a, 20, obj_ball); }

// Less than or equals to, <=
if (a <= 20) { instance_create(a, 20, obj_ball); }

// Equals to, ==
if (a == 20) { instance_create(a, 20, obj_ball); }

// Not equals to, !=
if (a != 20) { instance_create(a, 20, obj_ball); }

// Greater than, >
if (a > 20) { instance_create(a, 20, obj_ball); }

// Greater than or equals to, >=
if (a >= 20) { instance_create(a, 20, obj_ball); }

Booleans can also be combined for evaluation, as shown in the following code:

// And, &&, will return true if both booleans are also true.
if (a == 20 && b == 40) { val = "and"; }

/* Or, ||, will return true if at least one of the booleans is true. */
if (a == 20 || b == 40) { val = "or"; }

/* xor, ^^, will return true if one booleans is true and the other false. */
if (a == 20 ^^ b == 40) { val = "xor"; }

The if statement is probably the most common conditional statement that will be used while making these games. The if statements were introduced when discussing Booleans previously; the following is another example illustrating a simple if statement:

/* If the value of a is greater than the value of b, a is returned; otherwise, b is returned. */
if (a > b)
{
  return a;
}
else
{
  return b;
}

In the previous example, assuming both a and b are real numbers, if the value of a is greater than that of b, a is returned; otherwise, b is returned. One thing that should be noted is that b will be returned if it is less than or equal to a, since this is the opposite of greater than.

Now what if a variable needs to be compared against many different conditions? The following could be done:

/* Assigns the temperature of an object based on a color with multiple if-else-statements. */
if (color == c_green || color == c_purple || color == c_blue)
{
    temperature = "cool";
}
else if (color == c_red || color == c_orange || c == c_yellow)
{
    temperature ="warm";
}
else if (color == c_black || color == c_gray || color == c_white)
{
    temperature ="neutral";
}
else
{
    temperature ="other";
}

When there are a lot of objects, each with its own complex program that needs to be executed, the execution of these objects could become rather tedious and confusing. Instead of using long chains of if-else statements, a switch statement can be used. A switch statement is created with the keywords switch, case, break, and default, as shown in the following code:

/* Assigns the temperature of an object based on a color with a switch statement. */
switch (color)
{
  case c_red:
  case c_orange:
  case c_yellow:
    temperature = "warm";
    break;
  case c_green:
  case c_blue:
  case c_purple:
    temperature ="cool";
    break;
  case c_black:
  case c_white:
  case c_gray:
    temperature = "neutral";
    break;
  default:
    temperature = "other";
    break;
}

The previous switch statement is identical to the layered if-else statements created earlier. Each case statement is essentially testing whether or not the value of the variable supplied after switch is equal to its own. If the values are equal, the program is executed. If a default case is supplied, this program will be executed if none of the other cases satisfy the conditional statement. The keyword break, which will be discussed again in a later section, is used to end the program running within a case statement.

The repeat, while, do, and for statements are all examples of statements that execute a program multiple times and this is often referred to as a loop. The Repeat statement is used to execute the same program for a specified number of times:

// Creates 10 buttons at random positions between 0 and 100.
repeat (10)
{
  instance_create(random(100), random(100), obj_button)
}

The previous code will create 10 instances of obj_button at random positions. The while statement will execute a program until a condition is no longer met:

// Reduces x by 10 until it is no longer greater than 100.
while (x > 100)
{
  x -= 10;
}

In the previous code, the value of x will be reduced until it is less than 100. The do statements are very similar to the while statements, except they require an additional keyword—until:

/* Initially reduces x by 10 but continues until x is less than or equal to 100. */
do
{
  x -= 10;
}
until (x <= 100);

The difference between do and while is subtle. In a do statement, the program is executed first and then the condition is checked; in a while statement, the condition is checked first before executing the program. The for statements or for loops have built-in conditions as shown in the following code:

// Declares a local variable.
var i;

/* 10 buttons are created, evenly spaced apart horizontally by 100 units with an initial offset of 25. */
for (i = 0; i < 10; i++)
{
    instance_create(i * 100 + 25, 25, obj_button)
}

The first statement after the keyword for sets the local variable i to 0. Then, there is the condition that if the value of i is less than 10, the block of code within the loop is executed. The value of the variable i is then incremented and checked again within the conditional statement, running the program if the statement is still valid. Now the previous for statement is very similar to the repeat statement. The important difference is that i is incremented by the statement, making this a good way to loop through values in a one- or two-dimensional array, which will be covered shortly. The following sample code demonstrates this functionality with a two-dimensional array:

// Creates two local variables.
var i,j;

/* This is an example of a nested for loop in which a 10 by 10 grid with values ranging from 0 to 99 will be created. */
for (i = 0; i < 10; i++)
{
  for (j = 0; j < 10; j++)
  {
    grid[i,j] = i + j * 10;
  }
}

The following code shows the same functionality as the one performed using the repeat statements:

// Creates local variable and then assigns their values to 0.
var i, j;
i = 0;
j = 0;

/* Repeat functionality is performed 10 times and 10 more times within each repeat-statement. */
repeat (10)
{
  repeat(10)
  {
    // assign the grid value
    grid[i,j] = i + j * 10;

    // increment after each inner repeat.
    j++;
  }
  // increment after each outer repeat.
  i++;
}

As demonstrated, a for statement is much clearer than a repeat statement in situations like these.

Before moving on, it must be noted that the repeat, while, do, and for statements can create a situation known as the infinite loop. Infinite loops are very dangerous and cause a game to freeze up, ignoring input from the user and forcing them to shut down the game. The following are some examples of statements that can cause this; do not use these in actual code as they are just examples of what not to do:

/* Since the condition in the while-statement is always true, it will never terminate. */
while (true)
{
  x += 1;
}

// Declares a local variable.
var i;

/* This for-statement will never end since i will never be less than 0. */
for (i = 0; i >= 0; i++)
{
  x += i;
}

As previously mentioned, looping statements can sometimes cause a situation in which they do not terminate. There are two ways to resolve this issue. One is known as break, which was already demonstrated in the switch statements to break out of a case statement, but it can also be used to break out of a loop. The following is an example of a break statement:

// local variable used in the for loop
var i;

/* Iterates through 1000 enemies.  At the first undefined enemy, the loop is exited, otherwise, the enemy moves by a random value between 1 and 10 horizontally. */
for (i = 0; i < 1000; i++)
{
  if (enemies[i] == noone)
  {
    break;
  }
  enemies[i].x += random_range(1,10);
}

In the previous code sample, the for statement is broken out of and no longer continues running once the internal condition is met. Suppose break were to be replaced with continue, as shown in the following example:

// local variable for for loop
var i;

/* Iterates through 1000 enemies.  If an undefined enemy is encountered, the remaining enemies are still checked; otherwise, the enemy is moved by a random value between 1 and 10 horizontally. */
for (i = 0; i < 1000; i++)
{
  if (enemies[i] == noone)
  {
    continue;
  }
  enemies[i].x += random_range(1,10);
}

The for statement would proceed to checking the additional enemies, even if they are all undefined. The break and continue statements, however, are very useful because in both examples, an undefined enemy is to be encountered and the game will crash upon trying to add the value generated by random_range to its x value. The return statements are used most often in GML scripts that are created as resources. The return statement will not only end any script in its entirety, but also return whatever value follows it as demonstrated in the following code:

// This script will simply add and multiply two arguments
var result;
result = (argument0 + argument1) * (argument0 * argument1);
return result;

If you want to obtain a value using the previously shown function, it can be accessed through the following code, assuming that the function scr_add_multipy is a script resource:

// Execute the method and assign it to x.
x = scr_add_multiply(1, 2);

A two-dimensional array is created by adding two comma-separated integers within the brackets after a variable name. They are great to use when creating a grid system: the first index represents a column and the second represents a row, as shown in the following code:

/* A 2-dimensional array is declared and assigned four different values. */
var grid;
grid[0,0] = 10;
grid[0,1] = false;
grid[1,0] = "ab";
grid[1,1] = 95.5;

The following figure illustrates the data within the two-dimensional array created in the previous code block:

Only one sprite is needed to create this button. There are three important aspects of sprites: subimages, origin, and bounds. First, the subimages or frames of what will actually be displayed should be defined. By clicking on the Edit Sprite button, the Sprite Editor window will open. The button will be made from three frames representing three different states: a default state, a rollover state, and a down state, all of which are shown in the following screenshot. These sprites can be added using the images inside the sprites folder for this chapter's code files.

Once the sprites are loaded, the origin can be defined. The origin of the spr_button sprite is set to its center. This origin determines how the button is offset from its position. An origin of (0, 0) would align the button to the upper-left of its current position. This setting is displayed in the following screenshot with a crosshair on the sprite:

Finally, the bounding box of spr_button can be defined. The bounding box defines an area that the player will be able to interact with. This sprite will use a rectangular bounding box with an alpha tolerance of 128. The alpha tolerance determines how much of the sprite's transparency will be used to determine the definition of the automatic bounding box. The lower the value, the more of the sprites' alpha will be used—0 means that the entire image will be used and 255 means that the entire bounding box invalid. These settings are displayed in the following screenshot:

The obj_button object will represent the buttons that are going to be created. This object needs certain events that can be added by navigating to the following paths:

These different events will be explained and scripted later when creating the actual button. The sprite of obj_button should be set to spr_button, as illustrated in the following screenshot:

All games made within GameMaker need at least one room to run. This room is set to be 640 pixels wide and 480 pixels tall, but its size is irrelevant for this example. Additionally, the creation code will be used in this room, so do not add any instances of obj_button to it as one will be created with the code. The following screenshot shows the Room Properties page:

The Create event (Add Event | Create) is the first program executed when a new instance of an object is created. To create the event of obj_button, an Execute Code icon should be dragged-and-dropped in from the control tab of the Object Properties: obj_button panel. In the following script, the instantiation of the button's main variables will be handled:

/// Initializes main button components.

// Sets the image speed of the button to 0 so it will not animate.
image_speed = 0;

// Sets the image index to the first frame of the sprite set.
image_index = 0;

// Is this button currently down?
is_down = false;

// Is the mouse currently over the button?
is_over = false;

// Assigns the displayed text.
str_text = "Hello World";

// Scripts called during the different events.  
// The indices in this array are built-in constants that represent // different values and used for clarity. */

scripts[ev_left_button] = noone;
scripts[ev_left_press] = noone;
scripts[ev_mouse_enter]  = noone;
scripts[ev_left_release] = noone;

The Left Button event (Add Event | Mouse | Left button) will be executed for every frame for which the left button of the user's mouse is down and the position of the mouse is within the position of the object's sprite's bounds. The following code will be executed when the button triggers this event:

/* Executes the script when the button is being held down with the left mouse. */
if (scripts[ev_left_button] != noone)
{
    script_execute(scripts[ev_left_button]);
}

The previous code is an example of a conditional statement. The script at the index ev_left_button is then checked. If the index is assigned, the script will be executed.

The code for the Left Pressed event (Add Event | Mouse | Left pressed) will have a bit more functionality than the Left Button event. Unlike the Left Button event, the Left Pressed event will be executed only once while the user's mouse is clicked on when the cursor is within the button's bounds. The following code is executed when the specified script is assigned:

// If the specified script is assigned, it is executed.
if (scripts[ev_left_press] != noone)
{
    script_execute(scripts[ev_left_press]);
}

// Indicates that the button is down.
is_down = true;

// Sets the image index to the down state image index.
image_index = 2;

The previous code is similar to that of the Left Button event except for two minor differences. Firstly, a different index is used when testing for the presence of a script in the initial condition. Secondly, the is_down Boolean is set to true indicating that the button has been pressed, and image_index is set to 2, using the third frame of the sprite's animation.

Most buttons have a rollover state, indicating that the button is in the range of being clicked. The populating of the Mouse Enter event (Add Event | Mouse | Mouse enter) will be scripted similarly to the other events used thus far, as shown in the following code:

// Indicates that the mouse is currently over the button.
is_over = true;

// If the specified script is assigned, it is executed.
if (scripts[ev_mouse_enter] != noone)
{
    script_execute(scripts[ev_mouse_enter]);
}

/* If the left-mouse button is not down, the image index is assigned to the rollover frame. */
if (!is_down)
{
    image_index = 1;
}

The is_over object is set to true since the user's cursor is now hovering over the button. Then, the script indexed at ev_mouse_enter is tested and performed if assigned. Finally, the value of is_down is also tested. If the value is true, the button should stay in the down frame of its animation and not go to the rollover stage.

When the user's mouse leaves the bounds of the button, the Mouse Leave event (Add Event | Mouse | Mouse leave) will be triggered. This needs to be done to indicate that the cursor is no longer hovering over this button. The button should go to the first frame of its animation; however, this is only if the user no longer has the left mouse button held down. The following code explains the syntax for this event:

// Indicates that the mouse is no longer over the button.
is_over = false;

/* If not being held down, the image index is assigned to the default state frame. */
if (!is_down)
{
    image_index = 0;
}

The Global left release event (Add Event | Mouse | Global mouse | Global left released) will be triggered regardless of the user's position when the left mouse button is released. The releasing function, however, will only be executed if the cursor is currently hovering over the button. The button should always return to the first frame or the default state frame, which is why a Global left release event is used as opposed to a Left Release event. The following code gives the syntax for this event:

// Indicates that the button is no longer being pressed.
is_down = false;

/* If the mouse is over the button, the release script is executed and the image index is set to the over frame; otherwise, the image index is set to the default frame. */
if (is_over)
{
    image_index = 1;
    if (scripts[ev_left_release] != noone)
    {
        script_execute(scripts[ev_left_release]);
    }
}
else
{
    image_index = 0;
}

Now that the button's events have been coded, two scripts will be written. In the first script, a script resource named scr_create_button will be used to create buttons at runtime and provide simple information about them, such as their position and displayed text.

The scr_random_position script will be used as an example action for the button. It will randomly place an instanced object within the bounds of the room it is in.

Now that a script for instantiating buttons has been created, buttons can actually be created! Another object that executes scr_create_button during its Create event could be created, but to eliminate the need for a new object resource, a single line of code will be added to the room's creation code. Again, a room's creation code can be accessed by navigating to settings | creation code from the Room Properties window. In this script window, scr_create_button will be executed using the following code:

// Creates a button centered in the room that will move to a random position when clicked.
script_execute(scr_create_button, room_width * 0.5, room_height * 0.5, "1st Button", noone, noone, scr_random_position, noone);

Again, the previous function simply calls scr_create_button and supplies the seven required arguments. Though the third script ID argument is assigned to scr_random_position, the button is still pretty inactive since the script hasn't been created yet. This will be done next!

The scr_random_position script is mostly going to be used as an example, but it is still useful and can be applied to a variety of game types. As shown in the following code, this script will first determine the minimum and maximum positions that an object can be placed at while staying within the bounds of a room:

/* Declares the x and y ranges for places to stay within the bounds of the room. */
var x_min, y_min, x_max, y_max;

x_min = sprite_xoffset * image_xscale;
y_min = sprite_yoffset * image_yscale;

x_max = room_width - (image_xscale * (sprite_width - sprite_xoffset));
y_max = room_height - (image_yscale * (sprite_height - sprite_yoffset));

// Set the x and y to random position within the range.
x = random_range(x_min, x_max);
y = random_range(y_min, y_max);

/* If the object is within the bounds of the mouse, the Mouse Enter Event is triggered; otherwise, the Mouse Leave Event is triggered. */
if (position_meeting(mouse_x, mouse_y, self))
{
    event_perform(ev_mouse, ev_mouse_enter);
}
else
{
    event_perform(ev_mouse, ev_mouse_leave);
}

In the first portion of the code, four local variables were defined, representing the ranges of x and y without allowing the object to leave the bounds of the room. The minimum of the range is derived by using the x and y sprite offsets. Then, the maximum of the range is calculated by subtracting the difference of the sprite size and the sprite offset, which is then multiplied by its scale, from the size of the room, as shown in the following snippet:

var x_min, y_min, x_max, y_max;

x_min = sprite_xoffset * image_xscale;
y_min = sprite_yoffset * image_yscale;

x_max = room_width - (image_xscale * (sprite_width  - sprite_xoffset));
y_max = room_height - (image_yscale * (sprite_height – sprite_yoffset));

To determine a position, the supplied built-in function random_range is used, supplying the desired minimum and maximum values respectively, as shown in the following code snippet:

x = random_range(x_min, x_max);
y = random_range(y_min, y_max);

The final section, as shown in the following snippet, mostly deals with the button, but can be applied to any object. Once the object is placed, the built-in function position_meeting is used, which tests if the specified x and y coordinates are contained within the bounds of the supplied object. In this case, the keyword self is supplied, which represents the ID of the object instance executing this script. If the mouse positions meet, the object's Mouse Enter event will be executed; otherwise, the object's Mouse Leave event will be executed. The reason this script can be used by other objects is that even if they lack a Mouse Enter or Mouse Leave event, the script will still execute safely and not throw a runtime error. The following code shows the final section of the script:

if (position_meeting(mouse_x, mouse_y, self))
{
    event_perform(ev_mouse, ev_mouse_enter);
}
else
{
    event_perform(ev_mouse, ev_mouse_leave);
}

Now that the scripts have been properly set up, this game can be run. A button should be visible and centered toward the middle of the room. When the mouse hovers over it, it should go to the second frame and upon being pressed, go to the third. If the mouse is released while still hovering over the button, the button should move to a random spot and its bounds should remain in the room, signifying that scr_random_position has been called. If this works and looks similar to the next image, then the creation of this introductory button has been a success!