Using GameMaker and Electron together: A Practical Introduction
The HTML5 module for GameMaker Studio 2 allows you to export your game to a format that can be uploaded to the web, and played right in the browser. This format can also be used to create desktop applications. Wait, what?
What’s Electron?
Basically, it’s Google Chrome in a box. Electron allows you to build cross platform desktop apps with JavaScript, HTML, and CSS. It works by creating a kind of special instance of Google Chrome that you can customize. Check it out over here.
I’m sure you can already see where I’m going with this. GMS 2 HTML5 module + Electron = 💰.
But why?
For starters, Electron allows you to do some things that GameMaker’s native desktop export doesn’t, like use system tray icons, access the full file system, create child windows, and lots more.
You can also create transparent windows, which is the technique my team and I used for our entry in the virtual pet game jam:
To get a feel for everything that electron can do, check out the docs.
GameMaker Setup
The first step to combining GameMaker and Electron, is to actually have a game that we can export to HTML5. Just for simplicity’s sake, let’s make a new project and export it to HTML5 without adding anything. This way we have a sample game we can test inside of Electron.
Before we export our empty game, it’s important that we change an HTML5 setting. Make sure that the Display "Running outside server" alert setting is turned off. Electron will load our game directly from the filesystem, so it’s important we don’t display this message.
If this is your first time exporting for HTML5, you’ll get a prompt when exporting to HTML5:
We’re going to want to package as loose files, since we’ll need to use them right away. I’ll be putting them in their own folder somewhere that we can use for the location of our project. The output will look something like this:
Now that have a game to test with, we’re ready to set up Electron.
Electron Setup
In order to set things up with Electron, we’ll need to install some things.
Firstly, you’ll need to download and install Node, a JavaScript runtime that allows you to execute JavaScript outside of the browser. Electron needs Node to run.
Next, you’ll want to pick up a code editor if you don’t already have one. I suggest Visual Studio Code.
After you’ve got a code editor and Node installed, we can install Electron by typing the following into the command line:
npm install -g electronnpm stands for Node package manager, and comes with Node. It allows us to easily install popular Node packages from the internet. install -g instructs npm to install Electron globally, rather than directly into a folder on our computer.
Once that’s finished, you should be able to just type electron into your command line, and a window like this should appear:
With electron properly installed, we’re ready to configure our project and combine Electron and GameMaker!
Crossing the Streams
In order for Electron to know what to display, we need to create a file that contains some instructions. Let’s open the folder that contains our game in our code editor, and enter the following into a new file index.js :
This snippet of JS will instruct Electron to load the HTML file created by GMS 2. I won’t be going over the particulars of how JavaScript works for those unfamiliar, as that’s a little outside of the scope of this article. I will however point out some key points.
The above snippet is what actually creates the window. To load our game into the window, we have to load it as a URL as we would if we loaded it into regular Google Chrome. This is the bit that determines the path to our HTML file:
const htmlPath = path.join(__dirname, './index.html');The path.join function correctly combines strings into proper file paths. The __dirname variable contains the path that the script is called from. The second bit, of course, is meant to point to our HTML file. The result of the function will be the full path to our HTML file. We then load the file with:
mainWindow.loadURL(`file://${htmlPath}`);Running Our App
Now that we have everything in place, navigate to your project directory in the command line. Then execute your app with electron index.js . If you set everything up properly, you should see a window like this:
You have now successfully combined GameMaker and Electron!
What’s Next?
Now that we have everything working nicely, we can take advantage of some of the features that Electron offers. To keep things simple, let’s just cause our Electron application to close from within our game. To do this, we’ll have to write a small JS extension.
Let’s take care of the JS part first. Back in our code editor, let’s create a new JavaScript file and fill it with the following:
That’s all there is to it! The closeApplication function is what we will call from our extension.
Back in GMS 2, let’s create our extension. To do this, right click an empty area in your workspace and select “Create Extension”. Inside the window that appears, let’s add our new JS file on the right.
In our extension file properties, we need to define the closeApplication function. To do this, add a function on the right hand side and fill it out appropriately with the function name. We can also uncheck the “Copies To” fields to only apply to HTML5, since this extension doesn’t make sense for other platforms.
With our extension now ready, let’s add an object that calls our new function when we press a key.
Add that object to your room, and we should be all set! Let’s export for HTML5 again in our project folder. We can test our game again by running the same command that we used before, electron index.js .
This time, when you press the spacebar (or whatever other key you decided to use) the application should close!
Finishing Up
This article outlines only the very basics, of course. You can go on to create JS extensions that interact with many elements of the Electron API to customize your game.
It should be mentioned that this isn’t really a good solution for very large games, as Electron is known to produce very bloated executables. This is because every program made with Electron has to package Chrome and Node along with it in order to function properly.
