MessagePack for GameMaker

Available on YoYo Games marketplace.

A pure-GML implementation of the MessagePack protocol. Is able to encode or decode ds_map and ds_list into/from msgpack structures stored in buffers.

MessagePack is a light-weight binary serialization format with wide language support, often described as "like JSON, but more binary". See https://msgpack.org for more details.

This set of scripts uses pure GML to do the conversion, making it safer for cross-platform use as it does not depend on external DLLs.  However, the consequence of this, and due to some of the limitations of GML's datastructures, it is slower than the native json_encode/decode.

Basic usage

Encoding

The function msgpack_encode() takes a buffer and a ds_map.  It encodes the map as binary data inside the buffer.  The buffer can then be transmitted or saved to file.

var buffer = buffer_create(100, buffer_grow, 1);
msgpack_encode(buffer, map);
buffer_resize(buffer, buffer_tell(buffer)); // resize to exactly the right size
buffer_save(buffer, "save.bin");

Decoding

The function msgpack_decode() takes a buffer and returns a ds_map or ds_list depending on what is contained within the messagepack.

var map= msgpack_decode(buffer);

Advanced usage

Encoding a ds_list

msgpack_encode() only accepts a ds_map to encode, however messagepack allows encoding ds_lists as parent objects.  To do this, part of of gm_msgpack's internal function can be re-used, with the only requirement that an 8-byte scratch buffer be provided:

var scratch = buffer_create(8, buffer_fixed, 1);
msgpack_encode_ds(buff, list_to_encode, MSGPACK_DS.map, scratch);
buffer_delete(scratch);

decoding ds_lists is automatic, and msgpack_decode() can be used directly.

Encoding single values

Single values can be encoded in the same way. The datatype of the value is automatically detected.

var scratch = buffer_create(8, buffer_fixed, 1);
msgpack_encode_value(buff, "hello_world", scratch);
buffer_delete(scratch);

Known issues

• Use of the encode function will cause the  following message to appear in the output console: "Attempting to WriteValue for unsupported type -2147483648" this can be safely ignored, it is part of a workaround to GameMaker's lack of true datatypes for datastructures.
• msgpack_encode() is slow. This is due to GameMaker's lack of true datatypes for datastructures, and the consequent workaround requiring string manipulations
• arrays, pointers, vec3 and vec4 are not supported
• other types of datastructure aside from ds_list and ds_map are not natively supported, please serialize as a string first