• Hey! Guest! The 36th GMC Jam will take place between February 27th, 12:00 UTC - March 2nd, 12:00 UTC. Why not join in! Click here to find out more!

Asset - Scripts GM Serialize - Convert Gamemaker Instances to JSON


Hello everyone!

This asset provides a set of scripts that convert Gamemaker instances to and from JSON files. This allows you to easily save and load instances, transfer them to other languages, store them in databases, send them over the internet, etc.


Not all instances are created equal. While some store simple data (numbers and strings), others have complex data structures and even other instances. This extension provides mechanisms for serializing/deserializing simple and complex instances easily.

  • Works out of the box for simple instances.
  • Builtin scripts to work with complex instances.
  • Provides an extremely high amount of customization.
  • Extendable with scripts.
  • Fully commented code.
  • Fully documented.
  • Decoupled serialization from saving, allowing you to write secure save functions or even save to other file formats.
  • Currently supported: Here on the forums or on my Discord.
  • Cross platform.
Note for GMS2 users: These scripts should work out of the box on GMS2. All of the scripts have a GMS1 and GMS2 header(?), so converting them should be relatively simple.

In order to use the library, import the extension, and from the extension import the Serialize folder in the Scripts section. If you'd like to an example or some tests, import everything.

In order to understand how the scripts work, instances take this path to be serialized:

instance -> ds_map -> JSON
JSON -> ds_map -> instance

In other words the scripts first converts the instance to a ds_map, and then converts that map to json using json_encode.

If for whatever reason you'd like to change how the instance is saved (to save it securely or using another format), the scripts instance_to_map and instance_from_map are exposed to allow this.

Under the Hood
Part of the reason this library exists is that I can transfer instances between languages. Therefore, there is almost no magic going on under the hood. In other words, the resulting json is almost a 1 to 1 mapping of the instance and it's variables. The only thing that's added is a key "__0Type", which holds the type of the instance.

As an example, lets say we have an object "obj_character", and we have this code in it's create event:

hp = 10;[/SIZE][/SIZE]
[SIZE=7][SIZE=4]mp = 10;
spd = 3;

If we created and then serialized an instance of obj_character, the resulting json would look like this:

{ "__0Type": "obj_character", "hp": 10, "mp": 10, "spd": 3, /* The built-in variables go here... */ }
To test the speed of the serialization and deserialization process, I ran the desired script 1000 times, then recorded the total time and the average time. Here are the results:
  • Small Instance (10 vars)
    • Serialize
      • Total Time: 1547ms
      • Average Time: 1.55ms
    • Deserialize
      • Total Time: 440ms
      • Average Time: 0.44ms
  • Medium Instance (List with 10 values)
    • Serialize
      • Total Time: 1498ms
      • Average Time: 1.50ms
    • Deserialize
      • Total Time: 468ms
      • Average Time: 0.47ms
  • Complex Instance (3 vars, 1 list with 2 values, 1 nested instance, 1 grid, 2 maps)
    • Serialize
      • Total Time: 1749ms
      • Average Time: 1.75ms
    • Deserialize
      • Total Time: 728ms
      • Average Time: 0.73ms
This definitely brings some things to light. What takes the most time is probably having to iterate through relatively large maps (in addition to values listed, all objects have many of their base properties serialized as well, such as their x and y positions). This explains why the medium object that has to call a script on every serialize/deserialize was still FASTER than the small object. In addition, the complex object probably takes so much longer to deserialize because the script has to create the instance, destroy all data structures created in that instances create event, then recreate them from the json.

If you use this extension, keep in mind the speed costs to doing so. If you perform many operations at once (> 10) it might take longer than a frame to complete, so if you're doing it during an action sequence the user is likely to notice.
Last edited: