This is a function "cheat sheet" for TJSON extension by YellowAfterlife. The extension can be obtained from Marketplace or itch.io. A most up-to-date version of the manual is always available online.

Click on sections to expand/collapse them.
Quick display controls: Categories · Sections · Everything ·

Advantages

This section is dedicated to advantages of TJSON over the built-in functions.

Automatic memory management

Built-in functions create data structures to store the resulting structures, causing memory leaks if not freed explicitly.

TJSON uses array-based memory structures (which are freed automatically) and automatically pools data structures on a few occasions where they are preferable.

Type information

Since built-in functions return data structure' indexes, it becomes impossible to reliably tell apart the encountered values if the type may vary. That is,

var q = json_decode('{ "a": [], "b": {}, "c": 1, "d": true }');
show_debug_message(q[?"a"]);
show_debug_message(q[?"b"]);
show_debug_message(q[?"c"]);
show_debug_message(q[?"d"]);

produces outputs like "0, 1, 1, 1", leaving little way of finding out what the value is.

TJSON, on other hand, uses easily distinguishable array-based structures, and offers functions (tj_is_array, tj_is_object, tj_is_bool, etc.) to reliably tell apart the values.

Boolean value support

GameMaker has very partial boolean value support (more on this), and the built-in functions cannot produce boolean values (true/false) in resulting JSON strings at all - if an API requires you to provide a JSON boolean value, the most you can do is use a "special string" and string_replace_all it in the encoded string prior to submission.

TJSON, on other hand, implements a separate boolean type, allowing boolean values to be told apart after decoding, and to produce proper output upon encoding.

General functions
tj_decode(json_string)

Decodes the given JSON string into TJSON value(s).

  • JSON arrays are decoded into TJSON arrays.
  • JSON objects are decoded into TJSON objects.
  • JSON boolean values are decoded into tj_true / tj_false accordingly.
  • Strings and numbers are decoded into GML strings/numbers.
  • JSON null is decoded into GameMaker' undefined (alias tj_null).

Nested structures will produce nested JSON accordingly.

If JSON is invalid, tj_error is returned and tj_error_text is updated.

Resulting structures are managed automatically, so you don't need to destroy anything (as with data structure based approaches).

tj_encode(value, ?indent)

Encodes the given value into JSON and returns it as a string.

  • Arrays are encoded into JSON arrays.
  • TJSON objects are encoded into JSON objects.
  • TJSON boolean values are encoded into JSON boolean values.
  • Strings and numbers are encoded as-is.
  • GameMaker' undefined is encoded into JSON null (alias tj_null).
  • Any other values are encoded as JSON null.

Nested structures will produce nested JSON accordingly.

indent is indentation string (such as 2 spaces or 4 spaces or tab character). If not provided, the output is left without optional spacing/linebreaks.

If cyclical structures are passed, result is undefined (please don't).

tj_opt_value_keys(?allow)

This option is only available for native targets and alters the internal parser to allow JSON keys to be strings, numbers, booleans, and null (undefined) instead of just strings.

Note that this is not specification compliant so you should only use it for convenience with your own code.

If an argument is passed, changes the option to match that.

If no argument is passed, returns the current option state.

JSON value functions

The following functions aid working with TJSON values in general

tj_copy(value)

Recursively makes a deep copy of the given TJSON value.

Leaves non-array/object values unchanged.

tj_compare(value1, value2)

Recursively compares two TJSON values, returns whether contents match.

tj_typeof(value)

Returns the type of the given value as string.

Possible outputs are as following:

tj_typeid(value)

Much like tj_typeof, but returns a numeric constant (tj_type_) instead of a string.

Can be slightly more convenient than string comparisons/lookups.

JSON object functions
Overview

On JavaScript-based platforms, TJSON uses native JS objects for high performance.

GML's native platforms currently lack support for garbage-collected/automatically managed object structures, so TJSON uses a workaround involving a 2d array storing the actual values and a reference to a field name - field index lookup table shared between objects of the same structure.

tj_object(...key_value_pairs)

Forms a new TJSON object from provided key-value pairs.

Note that JSON keys can only be strings.

For example, tj_object("a", 1, "b", 2) produces an equivalent of { "a": 1, "b": 2 }.

tj_is_object(value)

Returns whether the given value is a TJSON object.

tj_get(obj, field)

Retrieves a value from the given JSON object, much like ds_map_find_value.

If the given field is not present in the object, undefined is returned.

tj_set(obj, field, value)

Changes a field on the given JSON object.

Throws an error if obj is not a valid object.

tj_delete(obj, field)

Removes a key-value pair from the given JSON object.

Note that this is not very fast on native platforms because values have to be moved around in the container-array to fill the formed "gap".

Throws an error if obj is not a valid object.

tj_size(obj)

Returns the number of fields in the given JSON object.

Returns 0 if the value is not a JSON object at all.

tj_keys(obj)

Returns an array containing all fields of the given JSON object as an array.

Returns an empty array if the value is not a JSON object.

Array functions
Overview

GML and JSON arrays are fairly interchangeable.

On JavaScript platforms, TJSON uses native JavaScript arrays (which are compatible with GML arrays).

On native platforms, TJSON uses GML arrays, so standard functions (array_length_1d, etc.) can be used for them.

Empty arrays may have a single-item second row for compatibility with <= 1.4.1763.

tj_is_array(value)

Returns whether the given value is a TJSON array (rather than a TJSON object or anything else).

tj_array(...values)

Assembles an array containing the given values.

So tj_array(1, 2, 3) produces an equivalent of [1, 2, 3].

In GameMaker: Studio 2, array literal [...] can be used.

Boolean functions
Overview

Historically, GameMaker did not have a boolean type - all "logical" operations and functions would yield values 1 (true) and 0 (false) accordingly.

Starting with Studio, support for actual boolean values was introduced, but they remain to be used inconsistently (for compatibility reasons?).

To workaround the situation and make it possible to tell apart the boolean and numeric values, TJSON defines two special constants (tj_true and tj_false) along with a few functions.

On JavaScript platforms, tj_true and tj_false map to the according JavaScript constants.

On native platforms, references to special arrays are used instead. This means that you should be doing if (v == tj_true) (or if (v != tj_false)) when working with these, rather than just if (v) directly.

tj_is_bool(value)

Returns whether the given value is a TJSON boolean value (tj_true or tj_false).

tj_bool(bool)

Returns either a tj_true or a tj_false value depending on the provided GameMaker boolean/numeric value.

Is very much just if (argument0) return tj_true; else return tj_false;

tj_true

A special value representing a JSON' true-value.

Note that this is not the same as GML' true-value and you will need to compare explicitly (value == tj_true).

tj_false

A special value representing a JSON' true-value.

Note that this is not the same as GML' true-value and you will need to compare explicitly (value == tj_false).

Error handling
Overview

TJSON follows the JSON specification fairly strictly, and will not fail if invalid input is given. When invalid input data is encountered, tj_decode will store the (human-readable) error text in tj_error_text and will return tj_error.

tj_error

Is returned from tj_decode when invalid input is encountered.

This value is reused between function calls and servers as a constant to compare against.

tj_error_text

Is updated by tj_decode when invalid input is encountered.

Is a global variable, so you should copy the contents