In this article: how I adapted an extension written for GameMaker Studio 1.4 (the free version) so that it worked in GameMaker Studio 2 (the new/paid license version).
I wanted to use dicksonlaw583‘s JSOnion extension in GameMaker Studio 2, but the extension was written for GameMaker Studio 1.4. Compiling with the extension in use kept giving me a vague “invalid token” error in 4 different places (luckily, line numbers were included) but no clues as to what token, exactly, was invalid.
It took a lot of trial and error and digging on Google to figure it all out, so I’ve documented what I needed to do here in case it helps someone else.
Importing the Extension
First thing I got confused on was how, exactly, to bring the extension code into GameMaker 2.
The JSOnion instructions say “drag JSOnion.gml into your open project”, but that doesn’t work (or at least it didn’t for me, no matter where I tried to drop).
What I actually had to do is go to the Resources panel and right click on Extensions. Select Create Extension.
Escaping characters
Next, I tried to run my game but the build failed due to a number of “invalid token” errors.
Each error looks like this:
Error : gml_Script__jso_decode_map(84) : invalid token
I was pretty lost here, and the GameMaker docs provided little help. Searching for “invalid token” comes up with nothing and this list of GML compiler errors offers only a vague hint:
You have an invalid character in your game code, which can happen with foreign language characters or Unicode
Hmm. The extension code looked okay to me…at least, it wasn’t full of bizarre characters and nothing looked weird at the line numbers GameMaker was complaining about.
This particular forum post gave me an important clue: single quotes are considered invalid characters in GML 2! Okay, that was something to go with. I went through the JSOnion.gml code and replaced single quotes with double quotes and, in order to do things like a set of double quotes within double quotes, escaped the interior set of double quotes with a backslash.
I also discovered (through more trial and error) that backslashes used for purposes other than escaping things are also considered invalid characters, so I had to escape those, too.
In summary, to adapt an extension meant for 1.4 to work with 2.0, you have to go into the .gml file and:
- Remove usages of single quotes
- Escape \ and ” characters
- escaped slash looks like this: “\\”
- escaped double quotes looks like this: “\””
Note: each time I wanted to test a change I made to JSOnion.gml, I had to go into the JSOnion extension, delete the reference to the file, and re-add the file to get the changes.
Adding macros (constants)
One more thing to do: add the macros.
JSOnion came with a file, constants.txt, that I wasn’t sure how to use. The repo instructions gave a clue: “import constants.txt as macros”, but I think there might’ve been some UI changes since GML 1.4, because I couldn’t figure out how to import this file in the version I’m using.
What I ended up doing was adding the constants manually in the “Macros” section of the extension properties. (See screenshot below).
(These are indeed required, too – if you don’t add the macros and you try to use JSOnion methods, you’ll get errors when trying to read a variable that wasn’t set.)
With the extension code cleaned of “invalid tokens” and the macros in place I can now build.
Was this the right way to do it? I don’t know – I’ve only worked in GameMaker for a few weeks and this was my first attempt at bringing in an extension, so I am far from an “expert” at this point.
Also, I haven’t had a chance to actually use the extension code yet (that’s a subject for another post), but I did get it building so I wanted to share the process in case anyone else is also trying to adapt an old/free extension for the newer/paid version of GameMaker.