Creating a GameMaker Studio Extension Using GML

  • Artykuł

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.

Comments

  • Anonymous
    January 12, 2014
    Glad my article helped.  You're right that GM Extension Builder was introduced with GM7, but I've used it to build GML-based .gex projects that are compatible with GM8, GM8.1, and GM:S -- but it's good to learn that the capability is now built into Studio.   As far as I know, in GM7/8, #define isn't used normally in projects.  In the process I describe, #define wasn't part of what I coded in the GML script -- it was added by the Export Script action.  It's apparently necessary when creating extensions, and is used to define a function.  Possibly it has its legacy in the Delphi C that GameMaker originally was implemented with.

  • Anonymous
    January 12, 2014
    @csanyk - thanks for the article, it was ripping apart your 'simple sample' that pointed me in the right direction.  still surprised at the lack of doc on something that is built into the ide...

  • Anonymous
    March 22, 2014
    Thanks a lot for your knowledge on this topic. About the extensions in Game Maker Studio, there's one thing that keeps bothering me. GM:Studio supports only 1 ad provider ( MS Pubcenter Advertising ), problem is this one has really low revenues as compared to Admob. Since Admob supports Windows Phone 8 in the latest Admob SDK, I was wondering if there's another way to include Admob to Windows Phone 8 App ( or other ad provider ). Someone from Yoyo said that it's possible by using Extensions, but, they don't provide any documents about this. I'm not good at programming, and I did a lot of researches but found no results Would you please take a look at this problem ?  Thank you

  • Anonymous
    January 10, 2016
    The #define got it working for me! Thank you!

  • Anonymous
    May 02, 2017
    Hi, nice extension example! I have a question about changing the layout while the extension is running, inside the Android source folder for the project I have added the necessary folders containing the .xml files for my theme but it isn't changing anything, it compiles and doesn't crash, so I just wanted to ask if I'm setting up the folder tree correctly, AndroidSource- java - has the java file libs - empty folder res - drawable folder with background.xml file and .png images, layout folder with .xml file, 5 mipmap folders for each dpi with 1 .png image each, values folder with color, dimens, strings and styles .xml files and finally the values-w820dp folder with the dimens.xml file sdk - empty folder is this correct?