Cookies help us deliver our services. By using our services, you agree to our use of cookies. Learn more

Tech

Creating An Extension For Mac, Windows And JavaScript Targets

Posted by Mark Alexander on 4 April 2014

Version: GameMaker: Studio 1.3+


Creating an extension for Mac, Windows or any of the JS targets (Tizen, HTML5, Windows 8) is a relatively simple business. 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 Properties window, where you can fill in the General details of the extension you are making:

Extension_properties.png

If the extension is for your own personal use, then these details are not that important, but if you are planning on distributing your extension to other people, then you should fill in all the fields and also think about adding a Help file (any format, but we recommend pdf or rtf or some other easily viewable format).

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 or a *.gex.

NOTE: You should always choose the *.gmez format rather than *.gex as the gex format is only to help with backwards comparability issues and may be obsoleted sometime in the future.

To create a *.gmez (or *.gex) 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.

 

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. 

Back to Top