json_stringify

This function converts a single struct or a hierarchy of nested structs and arrays into a valid JSON string.

You supply the initial value to use (a Struct or an Array) and then the function will "stringify" it, i.e. convert it into a JSON string (converting GameMaker arrays into JSON arrays, and GameMaker structs into JSON objects). You can optionally choose to "prettify" it, meaning the final JSON will be formatted for easy readability.

Usage Notes

The function will not serialise the data contained inside assets, data structures and other runtime assets into JSON, and will simply store the internal handle reference for the asset (which is of little use as the index will change between runs of the game).
- Upon parsing the JSON, these will be converted back into runtime references so the assets can be used normally in functions. This includes any asset type that is represented as a handle (see the "Handles" section on the linked page). This conversion can be disabled when parsing.
- Keep in mind that this will not be useful between game sessions as asset information may have changed, depending on the type of asset. Assets are saved using their names so these references maintain their links as long as the asset name does not change.
- If you want to serialise data structures (specifically lists and maps), use the json_encode function.
GameMaker encodes certain values in the JSON as a string so they can be read back correctly later. See Data Conversions for an overview of these conversions.

NOTE See Guide To Using JSON for detailed information on how to work with JSON in GameMaker.

Filter Function OPTIONAL

The function optionally takes a Function, which runs once for each value in the structure, including all nested structs/arrays and all the values inside them.

It takes two arguments (key, value) where key is the struct key name (String) or array index (Real), and value is what's stored in that key/index.

The filter function must always return a value. It can return a new value, which replaces the key's value in the final converted format returned by json_stringify. If no new value should be returned for a particular key, the function must return the original value.

NOTE When overriding a key's value in the filter function (using return), make sure you check its type first, as the filter function runs for the root structure and any nested structures as well, meaning accidentally overriding them will result in a broken final structure. See Example 3 at the bottom.

Syntax:

json_stringify(val, [pretty_print], [filter_func]);

Argument	Type	Description
val	Struct or Array	The reference value for a struct or array to convert into a JSON string
prettify	Boolean	OPTIONAL Whether to prettify the string, i.e. insert indentation and line breaks for readability
filter_func	Function	OPTIONAL Filter function that processes each item. Syntax: function(key, value) -> new_value

Returns:

String

Example 1:

var _contents =
{
version : "1.0.0",
data:
{
coins : 4,
mana : 15,
playername : "Gurpreet",
items :
[
ITEM.SWORD,
ITEM.BOW,
ITEM.GUITAR
]
}
};

var _json_string = json_stringify(_contents);

The above code will convert the _contents struct into a JSON string and stores the string in a variable. The returned string would look like this:

{ "data": { "items": [ 0.0, 1.0, 2.0 ], "coins": 4.0, "mana": 15.0, "playername": "Gurpreet" }, "version": "1.0.0" }

Example 2: Pretty Print

var _contents =
{
version: "1.0.0",
data:
{
coins : 5,
mana : 0,
playername : "Bart",
items :
[
ITEM.SWORD,
ITEM.BOW,
ITEM.PIANO
]
}
}
var _json_string = json_stringify(_contents, true);

The above code converts the _contents struct into a JSON string and stores it in a variable. With the pretty_print parameter set to true, the struct's contents are pretty printed to the string, i.e. indentation and line breaks are inserted to make the resulting string look "pretty" and more readable. The string then looks like this:

{
"data":{
"mana":0.0,
"playername":"Bart",
"items":[
0,
1,
2
],
"coins":5.0
},
"version":"1.0.0"
}

Example 3: Filter Function

The above code takes a struct and stringifies it to JSON, pretty-printing it, and using a filter function to modify some types of values.

If the value is a Real, it rounds it, if it's undefined, it changes it to 0, otherwise it simply returns the same value (meaning it remains unchanged).