Creating a GameMaker Studio Extension Using GML

  • Article

GameMaker is a very nice tool for developing 2D games that port to many different platforms. GameMaker supports scripting in its own proprietary language called GML. Once you've created a set of useful scripts, you can bundle them together into an "Extension". An "Extension" is basically a prepackaged set of scripts you can distribute.

Creating an extension is fairly well documented for GM7 and GM8, but I was unable to locate a walkthrough for creating an extension using GM:Studio. There are some good walkthroughts for GM7/GM8 (see below) but none of them directly mapped to studio. And creating a simple extension has now cost me about two days of stubborn aggravation.  So here you go, Nodens, god of the hunt, aka the SEO god!  May others find this before they burn too much time.

EXTENSION IDEA - Let's start simple and have a simple GML extension that draws a square around our sprite. I would actually use this in some debugging scenarios myself, so its not 100% trivial.

STEP1 -MAKE IT WORK OUTSIDE OF THE EXTENSION - If it doesn't work outside the extension, it probably won't work inside the extension.

STEP2 - CREATE THE SCRIPT - [right-mouse] on Scripts and create a new script for your project. Name it "draw_square_around_sprite_gml". Why am I putting the GML in the script name? I'm want the name of the script to be different from the name of actual extension I'm going to create.

STEP3 - CREATE THE SCRIPT CONTENT - Paste the code below into the script and save the script.

 var x1,y1,x2,y2, spr_width, spr_height;
spr_width = sprite_get_width( spr_Clown );
spr_height = sprite_get_height( spr_Clown );

x1 = x - ( spr_width/2 );
x2 = x + ( spr_width/2 );
y1 = y - ( spr_height/2 );
y2 = y + ( spr_height/2 );

draw_set_color ( c_green );
draw_rectangle( x1, y1, x2, y2, true );

STEP4 - WIRE IT UP - Now we need to attach it to an existing object that has a sprite. In my case I'm using a smaller version of the MyFirstGame tutorial from YoYo that has a clown object. Double click on obj_Clown. Add a DrawGUI event handler. Inside the Actions for DrawGUI put an Execute Script object and point it to "draw_square_around_sprite_gml".

STEP5 - CHECK YOUR WORK - Run the program to Windows. You should see a green rectangle around the sprite as below. At this point we know our logic is working and its time to create the extension method.

STEP6 - CREATE THE EXTENSION - [right-mouse] the Extensions area, and click Create Extension. I've named my extension "dfDBGExtension" and filled in the various fields as you can see below.

STEP7 - ADD FILE TO EXTENSION - [right-mouse] the dfDBGExtension you just created. Click Add File. Hunt down "draw_square_around_sprite_gml.gml" that was created for you in STEP2 and STEP3. Mine was in C:\dev\gamemaker\GMExtensions2.gmx\scripts .

STEP8 - ADD FUNCTION - We need to setup each function we are going to use. [right-mouse] on the file under the extensions, and click Add Function. Set both your internal and external names to "draw_square_around_sprite".

STEP9 - WIREUP DRAWGUI TO CALL OUR EXTENSION METHOD - Right now the clown's DrawGUI event is calling our script under the Scripts folder. We want clown's DrawGUI event to call new extension method instead. Open up obj_Clown, and find the DrawGUI event. Delete the Execute Script action. Add in a Execute a piece of code script and type in "draw_square_around_sprite();". Notice it turns orange (at least in the black theme) showing its a valid method.

STEP10 - RUN THE PROGRAM - At this point we should be able to give the program a run. Give it a go. Wait, crud, we get a code error. What do you mean you can't find the function! I just defined it!

 Error on load
Unable to find function draw_square_around_sprite

No real doc on this error. Bing, google, whatever. To research, I downloaded the drawhalo extension from csanyk for GM7 (linked below) and then dug into his script. There is this funny little line at the start of his .gml that uses a #define to declare a function name. I dig through GM help and look online but can't find any doc on #define. What the heck, let's give it a go anyway.

STEP11 - ADD #DEFINE TO OUR SCRIPT - [right-mouse] on our draw_square_around_sprite function. Click Open in Explorer. If you don't see your "draw_square_around_sprite_gml.gml" hunt it down. Mine was stored in "C:\dev\gamemaker\GMExtensions2.gmx\extensions\dfDBGExtension". Add a line to the top of the file that reads "#define draw_square_around_sprite". The file should match the code below.

 #define draw_square_around_sprite

var x1,y1,x2,y2, spr_width, spr_height;
spr_width = sprite_get_width( spr_Clown );
spr_height = sprite_get_height( spr_Clown );

x1 = x - ( spr_width/2 );
x2 = x + ( spr_width/2 );
y1 = y - ( spr_height/2 );
y2 = y + ( spr_height/2 );

draw_set_color ( c_green );
draw_rectangle( x1, y1, x2, y2, true );

STEP10 - RUN THE PROGRAM AGAIN - Now you should see happy clowns with green boxes. If you don't then just download the sample I've written.

GameMaker extensions are very powerful but the doc is a bit lacking on how to wire them up. Hopefully this post will help you over the "#define" nasty that gave me quite a bit of grief.