# Functions

Similar to how a variable saves a value to a name, a function saves a block of code to a name.

Many functions exist, (opens new window) to save you from needing to write everything you need from scratch.

To make them more flexible, functions can receive inputs (called 'arguments') and give an output (called a 'return value')

var the_maximum = max(1, 2, 3)
  • 1, 2, 3 are input arguments passed in to the function max.
  • max returns 3, which gets saved to the_maximum.
  • print takes the_maximum as an argument, and displays it to the screen (press ctrl 8 to see print output).

# Making Functions with Define

You can make characters without your own personal functions, so if you're a new modder, you can safely skip the rest of this page.

Once you're familiar with the other basics of the language, though, you can and should make your own functions!

You create new functions with a #define block. Like variables, you can name them almost anything, but should use a verb that helps the reader's understanding.

You must declare your functions at the bottom of the file they're used in. You can't put any normal code underneath a define.

#define stop_movement {
    hsp = 0
    vsp = 0

This makes a new function called stop_movement that you can use with stop_movement().

#define add_displacement(x_offset, y_offset) {
    x += x_offset
    y += y_offset

Notice the first line. This requires two inputs, and names them x_offset and y_offset.

# Why Create Functions

The most obvious use for a function is avoiding duplication, which makes your code easier to read, write, and change.

Functions also let you decompose your code into simpler layers, as a great way to manage complexity. Functions can help even when they're only used once, as a way of keeping your code simple.

# Advanced Defines

You can also allow an unknown number of input arguments.

The function body has two new variables.

  • argument is an array containing the input arguments.
  • argument_count is the size the argument array. The same as array_length(argument)
#define old_prints
    // Prints each argument to console, separated by spaces.
    var _out_string = ""
    for (var i = 0; i < argument_count; i++){
        _out_string += string(argument[i])
        _out_string += " "

You can use some arguments as variables and loop through the rest.

#define fancy_prints {
    //title, ...args
    // Prints the first argument as a title, then the others separated by spaces.
    var _out_string = argument[0]+":"
    for (var i = 1; i < argument_count; i++){
        _out_string += " "
        _out_string += string(argument[i])

These should always have a first line comment explaining what the arguments are, with the unknown quantity last, named ...args

(The GML documentation calls defines 'scripts', because in standard GML you write each user-function in a separate file.)