If you assign a script into this global variable, it will be called whenever an error occurs in Lua code.

So you could, for instance, make a script that displays a message box with error text,

/// scr_handle_lua_error(msg, state)
var state = argument1;
show_debug_message("A Lua error occurred: " + argument0);

and then link it up on game start:

lua_error_handler = scr_handle_lua_error;

Returns the current working directory (_wgetcwd on Windows, getcwd otherwise).

Previously called lua_chdir.

Changes the current working directory (_wchdir on WIndows, chdir otherwise).

This affects where the Lua code would be reading/writing files from by default.

A state is a subject to most of the Apollo's functions.

To put it simply, a state is the Lua program along with it's variables and current execution stack.

Creates a new Lua state and returns it's ID.

state = lua_state_create();

Lua's standard libraries are included by default.

If you don't want to expose certain API functions to the user, you can use lua_global_set to remove those entries:

lua_global_set(state, "io", undefined);

Destroys the given state, freeing up any resources used by it.

lua_state_destroy(state);

It is generally recommended that you clean up your states once they are no longer needed to avoid memory leaks.

Returns whether there's a state/thread with the given ID.

Destroys all existing Lua states and threads.

This also causes newly made states to have IDs start at 0 again.

Here's the deal: As you might know, reusing indexes can cause some really mysterious bugs if your code accidentally continues to use an index (which is now taken up by something else).

So, by default, Apollo will not do that. Which, in turn, means that after states are destroyed, 4 bytes worth of data (which were onece the state's address) will continue to be reserved per state.

While it would take about 500 000 states to run out of memory this way, you might prefer not to have that anyway.

So, calling this function will mark that memory as available again, causing Apollo to reuse the destroyed indexes for newly created states. This will only affect indexes of states that are destroyed as of calling the function.

In other words, while developing your project, you would not call this at all (so that if you use a destroyed state, you get an obvious error), and for final release version you would call it once in a while (such as during room transitions - to further reduce the odds of anything going strange).

The function returns the number of indexes that will be reused as result.

Attempts to compile the given snippet of Lua code, add it to given Lua state, and execute it. Returns whether all steps succeeded.

lua_add_code(state, "print('Hello!')");

Same as with other things, compilation/runtime errors are forwarded to lua_error_handler if it is defined.

Attempts to load and run a snippet of Lua code from the file at the given path.

The function mimics GM's file handling rules, preferring files in game's save directory over the files in game's installation directory.

It will, however, also accept absolute paths, bypassing sandbox restrictions.

So, if you added an included file called "some.lua", you could then load it with

lua_add_file(state, "some.lua");

If chdir is left at true, the function will automatically call lua_chdir when given a relative path so that the Lua code would work with files in that directory.

Technical: uses luaL_loadfile.

Returns the value of the state's given global variable.

Note that this returns undefined for unsupported types.

lua_add_code(state, "test = 'Hello!'");
show_debug_message(lua_global_get(state, "test"));

Changes the value of the state's given global variable.

lua_global_set(state, "test", "Hello!");
lua_add_code(state, "print(test)"); // 'Hello!'

Returns the type of a state's global variable as a constant.

Possible values are as following:

• lua_type_none: placeholder for type ID 0
• lua_type_nil: an equivalent of GML's undefined. Not-yet-set values are nil.
• lua_type_bool: a boolean value (true or false).
• lua_type_number: a numeric type, same as GML's real.
• lua_type_string: same as GML's string type.
• lua_type_table: a Lua table (array or dictionary).
• lua_type_function: a Lua function (that can be called via lua_call group).
• lua_type_thread: a Lua "thread"/coroutine.
• lua_type_userdata: an external reference (see Lua doc).
• lua_type_lightuserdata: an external struct (see Lua doc).
• lua_type_unknown: unrecognized type (never returns with normal Lua library)

If the state does not exist, an error is thrown.

if (lua_global_type(state, "test") == lua_type_function) {
    lua_call(state, "test");
} else show_debug_message("The state does not have a function called `test`!");

Returns the type of a state's global variable as a string.

Outside of debugging, you should prefer to use lua_global_type, as numeric comparisons are much faster than string comparisons.

The usual returned values are as following:

• "nil": an equivalent of GML's undefined. Not-yet-set values are nil.
• "boolean": a boolean value (true or false).
• "number": a numeric type, same as GML's real.
• "string": same as GML' string type.
• "table": a Lua table. You currently can't do much with these from GML side.
• "function": a Lua function - as such, a thing that could be called via lua_call.
• "thread": a Lua "thread"/coroutine (more on these later).

So you could use a snippet like this to check if a state has a function named "test":

if (lua_global_typeof(state, "test") == "function") {
    lua_call(state, "test");
} else show_debug_message("The state does not have a function called `test`!");

Attempts to call a Lua function stored in the given global variable of the state.

Returns the first of the function's returned values.

If an error occurs, calls lua_error_handler and returns undefined.

lua_add_code(state, "function greet(s) return 'Hello, ' .. s end");
show_debug_message(lua_call(state, "greet", "GameMaker"));

If the function returns multiple values, the first one returned (use lua_call_m / lua_call_xm / lua_call_wm / lua_call_wxm to support multiple returned values).

If the function returns no values, you get an undefined.

Like lua_call, but allows to pass in the arguments as an array.

lua_add_code(state, "function add(a, b) return a + b end");
var args = array_create(2, 7); // [7, 7]
show_debug_message(lua_call_w(state, "add", args)); // 14

Like lua_call, but packs returned value(s) into an array.

lua_add_code(state, "function multi(v) return v, 1, 2 end");
show_debug_message(lua_call_m(state, "multi", "test")); // ["test", 1, 2]

Returns the array with value(s) or an empty array if the function returned nothing.

Like lua_call_m, but instead writes returned value(s) into the specified array.

This allows to reuse the same array for frequently performed operations.

Returns the number of values written to the array.

lua_add_code(state, "function multi(v) return v, 1, 2 end");
var arr = array_create(5);
var n = lua_call_xm(state, "multi", arr, "test");
show_debug_message(arr); // ["test", 1, 2, 0, 0]
show_debug_message(n); // 3

A combination of lua_call_w and lua_call_m - takes arguments as an array and returns a new array with returned values.

A combination of lua_call_w and lua_call_xm - takes arguments as an array, writes results to another array, and returns the number of results written.

Exposes the given GM script to a Lua state as a global function.

For example, if you have some

/// scr_alert(text)
show_debug_message(argument0);

you could expose it to Lua via

lua_add_function(state, "alert", scr_alert);

If you want to organize your functions in Lua-like modules, you can use lua_add_code for that:

lua_add_function(state, "game_alert", scr_alert);
lua_add_code(state, @'
    game = { alert: game_alert }
');

which would then allow you to do

game.alert("Hello!")

on Lua side of things.

Lua allows to return multiple values from a function call at once.

This function helps to do that in scripts exposed to Lua via lua_add_function.

So, you could have

/// lengthdir_xy(len, dir)
var len = argument0, dir = argument1;
return lua_return(lengthdir_x(len, dir), lengthdir_y(len, dir));

expose it via

lua_add_function(state, "lengthdir_xy", lengthdir_xy);

and use it from Lua side like

local x, y = lengthdir_xy(30, 45)
print(x, y) -- 21.21, -21.21

Same as aforementioned lua_return, but returns the contents of an array as a value list instead. Note this will not work for nested arrays, however.

Add zero or more values to the list of returned values.

This is particularly handy for any GML operations that are done in a loop, e.g.

/// instance_find_all(obj)
with (argument0) lua_return_add(id);
return lua_return_add();

The last line with an empty lua_return_add is needed to return 0 values if loop matches no instances (as runtime would otherwise assume that you are going to return something with a regular return).

When a Lua state calls the exposed GML script, this variable holds the ID of the "caller" state.

Can be used if you want to do anything aside of just returning value(s).

Sends an error message to the currently executing Lua state.

This should only be used inside scripts exposed via lua_add_function.

/// scr_variable_global_get(name)
if (is_string(argument0)) {
    return variable_global_get(argument0);
} else lua_show_error("Expected a variable name to be a string.");

If you are building a medium-scale scripting API, you may find yourself needing to expose a large number of scripts (and/or built-in functions), as well as introducing argument type checking to prevent GML-side errors.

To save you from having to deal with that, Apollo includes a small utility that generates wrapper and loader scripts.

It accepts function definitions in funcname(arg1:type1, arg2:type2, ...):rtype,

• arg1, arg2, ...: argument names. Will be shown in errors returned to Lua.
• type1, type2, ...: argument types. Optional. If defined, code will be added to ensure that each argument matches it's type. Known types are real, bool, string; color, int, index, id can also be used, but are treated same as real.
• rtype: returned type, if the function returns a specific one. If set to bool, return-statement will be wrapped in lua_bool call.
• If prefixed with :, function will be marked as "instance function" and will accept an instance ID as first argument, also allowing to call it as inst.func(...) if instance access scripts are set up.

Constants can be defined either as name# (uses the value of same-named constant/variable) or name = value (computes the given GML value at inclusion time).

The tool is included with the extension as ApolloGen.exe;

A web-based version is available below:

Whenever the contents of above field are changed, updated loader script will be output into the field below:

You can then save them into a .gml file and import it to your project.

The rules for translating between GML and Lua values are as following:

GML➜Lua:

• real ➜ number (64-bit)
• int64 ➜ integer (64-bit)
• bool ➜ boolean (note: see lua_bool for details)
• string ➜ string
• array ➜ table
  Copied by-value recursively; adjusted for Lua array-tables being 1-indexed.
• struct ➜ table (GMS2.3+)
  Copied by-value recursively.
• method ➜ gml_method userdata (GMS2.3+)
  
• lua_byref ➜ gml_ref userdata
• Anything else ➜ nil

Lua➜GML:

• number ➜ real or int64 accordingly
• string ➜ string
• boolean ➜ bool
• table ➜ array or struct
  Copied by-value recursively.
  If length (lua_rawlen) is >0, the value becomes an array, else it becomes a struct (2.3+) or a 2d array of keys and values (pre-2.3)
• gml_method userdata ➜ original GML value
• gml_ref userdata ➜ original GML value
• Anything else ➜ undefined

As of Apollo V2, this function is equivalent to calling bool directly and is only here for backwards compatibility.

A thing to remember: unlike GML, Lua is stricter about use of boolean types (e.g. 1 + true is forbidden), therefore you may want to cast your values to appropriate types before passing them to Lua.

lua_true or a lua_false read-only variables hold values for boolean true and false accordingly - unlike the built-in true and false constants, which currently remain to be equal to 1 and 0 accordingly.

Primarily intended for use with pre-2.3 versions of GM, this function allows to hint a value so that upon handing it over to Lua it would become a function reference (rather than staying a script index).

Returns a tiny array with metadata including the given script index.

This allows to pack up an array of functions, for example.

lua_add_code(state, @'
    function test(f)
        f("hi!");
    end
');
lua_call(state, "test", lua_script(scr_show_debug_message));

This function hints a GML array/struct to be passed to Lua by reference!

Passing by reference means that when the source array/struct is modified, the changes will be reflected in any references to it automatically, and that modifying the contents from Lua will reflect changes on GML side.

If the optional recursive argument is set to true, any sub-items pulled from the array/struct will be passed to Lua by reference automatically (good for nested arrays/structs).

lua_add_code(state, @'
    function test(arr)
        print(arr[1]) -- "one"
        arr[2] = "hi!"
    end
');
arr[0] = "one";
arr[1] = "two";
lua_call(state, "test", lua_byref(arr));
show_debug_message(arr[1]); // "hi!"

lua_add_code(state, @'
    function test(o)
        print(o.one) -- 1
        print(o.miss) -- nil
        o.two = "hi!"
    end
');
st = { one: 1, two: 2 };
lua_call(state, "test", lua_byref(st));
show_debug_message(st.two); // "hi!"

If you are using GameMaker Studio 2 or an non-ancient version of GameMaker: Studio, you can have Lua directly read and write variables on GameMaker instances.

To do so, you would add three scripts to your project:

/// ref_variable_instance_get(context, name)
var q = argument0, s = argument1;
with (q) return variable_instance_get(id, s);
if (q < 100000) {
    lua_show_error("Couldn't find any instances of " + string(q)
        + " (" + object_get_name(q) + ")");
} else lua_show_error("Couldn't find instance " + string(q));
return undefined;

(reads a variable from an instance),

/// ref_variable_instance_set(context, name, value)
var q = argument0, s = argument1, v = argument2, n = 0;
with (q) { variable_instance_set(id, s, v); n++; }
if (n) exit;
if (q < 100000) {
    lua_show_error("Couldn't find any instances of " + string(q)
        + " (" + object_get_name(q) + ")");
} else lua_show_error("Couldn't find instance " + string(q));

(writes a variable to an instance(s)),

/// ref_variable_instance_init(lua_state)
var q = argument0;
lua_add_function(q, "variable_instance_get", ref_variable_instance_get);
lua_add_function(q, "variable_instance_set", ref_variable_instance_set);
lua_add_code(q, @'-- ref_variable_instance_init()
    __idfields = __idfields or { };
    debug.setmetatable(0, {
        __index = function(self, name)
            if (__idfields[name]) then
                return _G[name];
            else
                return variable_instance_get(self, name);
            end
        end,
        __newindex = variable_instance_set,
    })
');

(exposes the above scripts to a Lua state and sets it up to use them when trying to read/write a field on a numeric value (id)).

Then you can use them as following:

// create a Lua state:
state = lua_state_create();
// allow the state to work with GM instances:
ref_variable_instance_init(state);
// add a test function to the state -
// function takes an instance and modifies it's `result` variable.
lua_add_code(state, "function test(q) q.result = 'Hello!' end");
// call the test-function for the current instance and display the result:
result = "";
lua_call(state, "test", id);
show_debug_message(result);

A coroutine, in short, is a function that can pause/resume execution at arbitrary points.

These can be used for iterators, cutscenes (pausing/resuming allows to write timing in an intuitive way), tweening, AI, or anything else that benefits from maintaining the state across multi-call execution.

This set of functions enables you to use Lua coroutines in Apollo.

Creates a "thread" state for the given Lua state and returns it's ID.

Such "threads" share the global context (variables, functions, etc.) with their parent state, but have their own clal stack, meaning that they can do their own thing (namely, executing coroutines) while the parent state does something else.

thread = lua_thread_create(state);

Destroys a previously created "thread" state.

Does not free resources of the parent state, only what was owned by the thread itself. Is a convenience function and is interchangeable with lua_state_destroy.

Starts a coroutine call on the given sate, returns whether the operation succeeded.

Note that some functions will work oddly (or not work at all) on a state that is currently amidst the coroutine call, which is why you should generally create a thread for the coroutine call.

Same as lua_call_start, but takes arguments as an array.

Executes the next iteration on the given state and returns whether the coroutine call is ongoing (as opposed to finishing or encountering a runtime error).

The general scheme of performing coroutine calls is thus as following:

lua_add_code(state, "
    function test(num)
        for i = 1, num do
            coroutine.yield(i)
        end
        return 'rad!'
    end
");
th = lua_thread_create(state);
if (lua_call_start(th, "test", 4)) {
    while (lua_call_next(th)) {
        show_debug_message("yield: " + string(lua_call_result));
    }
    show_debug_message("result: " + string(lua_call_result));
}
lua_thread_destroy(th);

Holds the result of the last lua_call_next - yielded value when the execution continues, and final returned value when the execution stops.

"getting started" page on the Lua's website houses a large collection of links to tutorials, wikis, and other learning materials.

Lua Manual provides detailed explanations on how internal elements and all standard functions of the language work.

If you have pre-existing GML code that you'd like to quickly tweak for use with Apollo, I have also developed an online GML->Lua converter.

While automatic conversion won't make extensive use of Lua-specific language features, it produces functional code in vast majority of cases and the output is clean enough to tweak it manually if needed.

Apollo uses Lua 5.4 as of writing this.

In case you'd like a custom version (such as to use LuaJIT, or to use a Lua fork with different syntax), C++ source code is included - it should work with any Lua build down to 5.1 or so.

The extension runs on Windows, Mac, and Linux - linked dynamically in all cases.

Apollo v2 beta currently only comes with a Windows (GMS1,GMS2) binary, but you can compile it yourself (code is portable).

Mac may require additional tinkering (via install_name_tool - example), as library inclusion paths may vary depending on whether the game is running from IDE, whether YYC is enabled, and GMS version. If you are familiar with Mac extension development yourself, feel free to get in touch about better ways of handling this.

Internally, Apollo V2 uses a Lua C API function lua_yieldk to switch back and forth between GML and Lua code.

So, when you ask to call a GML script, the current Lua state pauses, writes arguments to a buffer, and returns execution to GML code. GML code then reads the arguments from a buffer, calls the script in question, writes the result(s) back into the buffer, and calls an extension function, which reads them from a buffer, hands them to the Lua state, and resumes execution.

There is a little caveat to this: in rare cases (most notably, inside __tostring, and ipairs) Lua does not support pausing the state, and you will get the aforementioned error.

When this happens, you can tweak the code to either not access GML side of things in the function itself (e.g. cache the result elsewhere) or change the code so that it does not rely on those features (e.g. add a separate toString function to your metatable or make a custom iterator).

Lua supports several additional reference types (such as Lua function references), but these cannot be safely sent to GML as pointers as they are garbage-collected, and thus may get recycled while still referenced on the GML side of things (resulting in hard crash when trying to use the passed back value).

A good way to deal with this is to make a pair of lookup tables - since Lua allows table indexes to be of any type, you can do something like the following:

ref = {
    __r2i = { },
    __i2r = { },
    __next = 0
}
function ref.toid(fn)
    local id = ref.__r2i[fn]
    if (id == nil) then
        id = ref.__next
        ref.__next = id + 1
        ref.__r2i[fn] = id
        ref.__i2r[id] = fn
    end
    return id
end
function ref.fromid(id)
    return ref.__i2r[id]
end
function ref.free(fn)
    local id
    if (type(fn) == "number") then
        id = fn
        fn = ref.__i2r[id]
    else
        id = ref.__r2i[fn]
    end
    ref.__r2i[fn] = nil
    ref.__i2r[id] = nil
end

Which allow you to use ref.toid(some_reference) to return/create a numeric ID for a reference, ref.fromid(index) to convert one of those back to a reference, and ref.free(index_or_reference) to remove the lookup pairs (allowing Lua to safely recycle the reference when it is no longer used).