Introduction to Creating Extensions in GameMaker

This guide provides the step-by-step process to create a GML-type Extension from scratch which will work with GameMaker. It shows how you can use the Extension Editor within GameMaker to create a new function to extend GameMaker's pre-made instance_create() function and use this new one you made in your own games.

There is a pre-made project available for download at the bottom of this page, but we would strongly recommend you follow along with the guide and only use the supplied copy as a sanity-check if things aren't working correctly in your own attempt.

What Is An Extension?

As well as being a way of adding your own custom function libraries, extensions are often used to provide extra in-game functionality (such as integrating an external ad provider, analytics, or social features) and consists entirely of source code files - no other form of GameMaker assets are allowed.

You can create a simple GML extension (as we will show in this FAQ) or more advanced "library" extensions for desktop platforms, such as Windows .dll, macOS .dylib, and Ubuntu .so files.

Additionally, Android and iOS/tvOS have the ability to import an entire source code folder into your project builds - for this, you can find an introduction to creating extensions for these platforms in this guide. But for more practical examples and more advanced knowledge once you have followed this guide you should see our own Marketplace assets for Google/Apple/Amazon/etc., and learn the structure from them. (Each SDK will have its own packaging requirements and be mostly custom code, so it's not really possible for us to put together a useful guide for this advanced level and generally we would say to just refer to your chosen SDK's own docs.)

However, if you're just starting out with Extensions we wouldn't suggest you dive right into analysing a full SDK. Instead, please read on.

Why Create GML Extensions?

A common example of an extension is to create yourself a library of functions that you frequently use across all your projects - instead of adding the scripts for each function into every project, or copying and pasting code into objects in every project, you simply add the one extension file and you are good to go.

The advantage of a GML extension is that you can target any platform GameMaker supports with that one bit of code.

Code Your GML

You may already have the code you wish to use in your extension, or know what you want to write, so how do you get this into a suitable state for GameMaker to use it? You can write the code out first of all within GameMaker itself, but this will require a fair amount of copying and pasting to get it to work, and your file needs to be a plain text one anyway, so it is recommended that you just write the code once in a basic editor such as Notepad/Textedit. (Note, if using TextEdit, do not use the default of a .rtf file - ensure you save as a .txt file!)

So, in the following example we will show the simple use-case of "I want to take the existing GameMaker functionality for creating an instance, but extend this with a custom alpha value I will pass in later".

The code in GameMaker would look like the following:

myInst = instance_create_layer(x, y, layer, obj);

with (myInst)
{
 image_alpha = alphaVal;
}

In its current form, this syntax cannot be used in an extension because it is lacking a function declaration and a return statement, plus the arguments are fixed ("hardcoded") values we can't change later.

In our extension it would have to be like this:

#define instance_create_alpha
myInst = instance_create_layer(argument0, argument1, argument2, argument3);
with (myInst)
{
  image_alpha = argument4;
}
return myInst;

As you can see, it's similar but with some key differences:

#define instance_create_alpha

This #define line identifies the following code as a function with the name instance_create_alpha. This is the name we will put into the extension editor inside GameMaker and then the game will know to run this piece of code.

argument0, argument1...

We changed the hardcoded values into arguments, as this allows us to pass information to the extension whenever we call the function. 

return myInst;

And this final line passes the instance the extension just created back to the game - while not strictly necessary in all types of function, for the purposes of our guide here it is pretty important for other code in the game to be able to access this new instance.

Now close your text editor and ensure you save that file as a .gml file in an easy-to-access location. (You may need to fix the file extension after you save it as a .txt file within your editor - this is fine also.)

Create Your Extension Asset

Within GameMaker you now need to create an Extension asset inside a project. This can be done by right-clicking on the Asset Browser, selecting Create and then Extension, as shown below:

You will now be shown the Extension Editor (shown below). For this section the only items we are concerned with changing are the Name, Version number fields, and the Resources picker.

The Copies To area tells GameMaker which platforms this extension should be available for. As we are making a GML extension it will be fine cross-platform and so there is no reason to untick any of these, but if you don't want your extension running on certain platforms you're free to do so.

It's time to give your extension a name. For this extension "InstanceCreation" seems appropriate as we are providing extra methods to extend the abilities of creating instances. 

Now add the .gml file we created to the extension, this is done by clicking the burger menu on the Resources/Files section and selecting Add File, an open dialog will be presented and you should find and select your .gml code file.

Important Note: This will copy your .gml code file into the Extension in your project directory, as such further changes to your original .gml file won't matter and instead you should open this new copy in a text editor to make further changes. You can easily locate the correct file by right-clicking on the Extension in the Asset Browser and selecting Open In Explorer.

You will now be presented with a new dialog box chained to the Extension Editor. GameMaker tries to populate the values in this new screen automatically, but note that it may not be exactly what you require, so you may well need to edit accordingly.

For the purpose of this guide only one of these entries will be getting changed, but a quick explanation may give inspiration to you for how you could expand our little demo to try more things later on:

• "Name" is simply the name of your file and you shouldn't need to edit.
• "Init Function" lets you pick a function that runs on startup of the game.
• "Final Function" lets you pick a function that runs when the game is closing down. However, this is not available for all platforms and so the manual should be consulted before using this.
• "Proxy Files" this allows you to add extra library files for different platforms without having to re-specify all the functions and macros for each. However, they must follow specific naming conventions which are covered in more detail in the Manual.
• "Copies To" lets you pick which platform this individual file should be used on, as its conceivable your extension contains many files, but not all will be desired for all platforms.
• "Macros" lets you define constant values to be used in-game by GameMaker later on.
• The "Functions" section is the focus of this guide, as this lets you provide the information required to call the correct function from this code file.

(If no function was present for some reason, click the burger menu button in Resources/Functions and select Add Function. However, if this still fails, then it implies you did not create the text file correctly.)

As you can see, the extension editor has already made a good attempt to add our function already, but it has appended a "_1" to the function name, and this is not desirable. So let's fix this now.

Simply double-click the function name entry to open the function editor:

• "Name" is what you want to call your function inside GameMaker anytime you type it in your code. This does not need to be the same as the function name as declared inside the extension file.
• "External Name" is the name of the function as taken from the #define line in our extension file. If you ever edit the name in the extension itself, you will need to make the same edit here also.
• "Help" this lets you specify code help that will be shown in the code editor of GameMaker and will let you give information about the arguments this function may require.
• "Return Type" is a choice between a double (a number) or a string (a series of characters). In our case we want a double, as we are returning an instance id from our function.
• Clicking the "Arguments" plus symbol adds a new argument each time, and as you see in the image below the "Key" is the same as what we specified in our GML file. The "value" is which type is expected by that individual argument - again, its a choice between a double or a string. 
• If "Variable Length Arguments" is enabled, then you are saying your function contains optional arguments and so later on in the code editor you omit some when calling this function.

Below is how you need to configure this extension file in order to work with the example GML code we wrote earlier in this guide:

And that's it - you can close all the extension editor windows, as this extension is now ready to use. 

Use Your New Extension In Your Game Code

Inside the project, create 2 Objects and a Sprite. The sprite needs to have some content of your choice and then be assigned to Object2.

Add Object1 to the instance layer within Room1 and then just close the room editor again. Do not add Object2 to the room, as that will just confuse our results!

Back in the workspace, give Object1 a new Create event. Now simply type in your extension function name and you should see it appear in the code help (here we show all the arguments, but these will only appear if you provided that information during the last section of this guide):

Finish off typing the full line we require here:

instance_create_alpha(x,y, layer, Object2, 0.5);

"x", "y" and "layer" are built-in variables that take the values from the Object1 instance we placed in the room. "Object2" is the name of the object we want to create an instance of (the one which has the sprite). "0.5" is simply the alpha value we want the new instance we create to have.

Once that line is typed out, run your game. You should see an instance of Object2 is now in your room exactly where you placed Object1 inside the room editor, like so:

It works!

But now that you can supply arguments, you can easily create many instances and customise them further. Consider the following code:

for (var i=0; i<10; i++){
   instance_create_alpha(x + i*64, y+64, layer, Object2, i*0.1);
}

This is a loop that instantiates 10 instances, but passes-in different variables each time, so that you see a progression of the alpha changing, like so:

Try playing around with this more yourself and get comfortable with calling your new function.

You Made A GML Extension

That's it for GML extensions! You now know how to add further functions into your .gml file, add them into the Extension Function editor, and call them in your code.

If you wish to use this extension in other projects, you can do a simple "Add Existing" inside those other projects and select the extension .yy file from this project to import all your extension editor setup and the .gml file in one go.

Alternatively, you can create a Local Package from the Tools menu and import that package into your other projects. You could even give the package to other people so they can import your extension into their own projects.

If you had any issues with your own attempt when following this guide, please see this working copy and compare it to what you did: