Creating An Extension For Mac, Windows And JS Targets (GMS v1.3+)

Creating an extension for Mac, Windows or any of the JS targets (Tizen, HTML5, Windows 8) is a relatively simple business, made easier by the "wizard" that GameMaker: Studio provides to help you.

To start with, you simply right-click on the Extensions folder from the resource tree and select "Create Extension". This will bring up the Extension Wizard window, where you can fill in the basic details of the extension you are making and supply a name and version number:

Extension_properties.png

For Windows, Mac and the JS targets, you will see a "Create" button at the bottom (where the image above shows "Next"), and clicking that adds the extension to the resource tree, where you can now add files and functions to it.

Note: For Android extensions please see the article Creating A Native Extension For Android and for iOS extensions please read Creating A Native Extension For iOS.

Adding A File

With that done we then need to go ahead and add the file that is to be used. For that we need to close the Extension Properties window, then right-click on the new extension in the resource tree, and select "Add File". This will bring up the file explorer where you can select the file to be used:

*.js - This is a JavaScript extension and is only compatible with the JS targets (HTML5, Tizen, Windows8).

*.dll - This a dynamic-link library extension and is only compatible with the Windows target.

*.dylib - This is the Mac equivalent of a dll and is only compatible with Mac target (not iOS).

Adding the file to your extension will bring up the File Properties window.

Extension_File_Properties.png

In this window you can re-name the file that is to be used as the extension (this file is then saved with the gmx project and any changes should be made in the project file, and not to the original) and you can define the Init Function and the Final Function. These functions are the ones that the included file or the source file (which will depend on the target platform) needs to have called to set them up for use with GameMaker: Studio and to free them again when the game closes. They are called automatically, with no arguments, and you should note that these are not always necessary so you should check the documentation for the file you wish to use as an extension first to see if these functions are necessary or can be left blank (if in doubt, leave them blank). 

The final section is labelled Copies To. Here you can see a list of target platforms which you can tick (or un-tick) as appropriate for your extension. In this way, you can have (for example) two hi-score extensions, one *.dll and one *.js that have the same functionality but work for different target platforms. You would, for example, tick ONLY the Windows check-box for the *.dll but for a *.js extension you could tick Tizen (JS) and HTML5. In this way GameMaker will know to use only the appropriate file for the target platform. You can also set up different configurations and tick/un-tick options as necessary depending on the current configuration chosen.

Clicking "OK" will close this window and save your changes, and the chosen file will now be bundled with your game for use. But how do you use it? Well, you now need to define the specific functions and constants that your extension requires.

Creating Functions

Now you have added the necessary files to the extension, it is time for you to add the functions and constants that you wish the extension to use. This is done by right-clicking on the file and selecting either Add Function or Add Constant. If you choose to add a function, then the following window will open:

Empty_Function.png

The different options presented here are:

  • Name - This is the GML name of the function (only letters from A-Z, numbers and the under-bar "_" symbol are permitted, and the name must not start with a number).
  • External Name - Here you must put the name of the original function as it is recognised by the extension, even if the Name is the same.
  • Help - This is the text that will appear at the bottom of the script editor and should be a correct form of the function syntax with the format function(argument0, argument1, etc...).
  • Return Type - What the function returns. This can be either a string (text) or a double (real number).
  • Type (dll only) - The calling convention used to call the function.
  • Arguments - Here you can list all the arguments that your function can take as well as the type (string or double). This is limited to a maximum of sixteen arguments, and note that for functions with 4 or more arguments, all of them must be of type double.

Creating Constants

For defining a constant, it is simply a case of giving it a name (only letters from A-Z, numbers and the under-bar "_" symbol are permitted, and the name must not start with a number) and a value and then clicking on the "Okay" button.

Constant_Properties.png

Using The Extension

Now you are ready to use the extension. If all has been set up correctly, it should simply be a case of you using the defined functions and constants as you would any other GML function or pre-defined constant. If you have filled in the "Help" field in the Function Properties field when defining the function, you will be able to see the function in the code complete, as well as benefit from the code editor syntax checking.

Exporting An Extension

Once you have defined all your constants and functions, the extension is ready to be used and distributed as a *.gmez. These files can contain assets as well as your extension functions and files, and are a replacement for the (now obsolete) *.gex format.

To create a *.gmez all you have to do is right-click on the extension name and select Export, which will open a save dialogue where you can say where to save the final file to. Once this is done you can then use the same gmez/gex in other projects by importing it into the resource tree (right-click the extensions folder then select "Import Extension"), or distribute it for others to use.

NOTE: Your extensions are signed using a unique profile certificate. This means that you can distribute them freely to other people, but they will not be able to compile a final executable unless the extension has been uploaded to the GameMaker: Marketplace and the user has downloaded it from there. You can find out more about the Marketplace here: MarketPlace FAQs.

Sharing Functions And Constants

If you are developing for Windows and Mac platforms, it is worth noting that you can create a single extension with only one set of functions which will work on both platforms. This is achieved by adding only one of the link libraries to your game as an extension and placing the other in the Included Files (don't forget to mark the export target for the file when you do).

For example, say you have a Windows extension with the dll "Haggis.dll". You would simply replicate this dll as a Mac OSX DyLib, naming it "libHaggis.dylib" and making sure that the internal function names match those of the original Windows dll. Note that all we have done to the name is prefixed it with "lib".

This DyLib would then be added into the Included Files and set to export when the game is run on the Mac target, and Gamemaker: Studio will automatically use it when the extension functions are called. 

Have more questions? Submit a request

0 Comments

Article is closed for comments.
Powered by Zendesk