Carton 1.0.2

Buffer packer/unpacker for GameMaker Studio 2

@jujuadams

 

 

Carton is a small library to help with storing and retrieving many buffers at the same time. This library was originally made to pack .obj models into a single file for distribution, taking advantage of GameMaker's buffer compression to additionally reduce the filesize of the models. Carton could be used for any number of things, not least storing and compressing localisation strings.

//Create a couple buffers of data
buffer_0 = buffer_create(1024, buffer_fixed, 1);
repeat(1024) buffer_write(buffer_0, buffer_u8, 0xF0);

buffer_1 = buffer_create(16, buffer_fixed, 1);
repeat(16) buffer_write(buffer_1, buffer_u8, 0xF1);



//Create a carton to store buffers
carton = carton_create();

//Add our two buffers to the carton
carton_add(carton, "Buffer 0", buffer_0);
carton_add(carton, "Buffer 1", buffer_1);

//Save the carton to disk with compression turned on
carton_save(carton, "output.bin", true);

//Cartons use memory! Don't forget to destroy them
carton_destroy(carton);



//Ok, now let's load in the carton we just saved
carton_in = carton_load("output.bin", true);

//Unpack the buffers from the carton (there's also a metadata getter as well)
buffer_0_in = carton_get_buffer(carton_in, 0);
buffer_1_in = carton_get_buffer(carton_in, 1);

//carton_load() also allocates memory so make sure to take care of that as well
carton_destroy(carton_in);

 

Functions

__carton_config()

Returns: N/A (undefined)

Name	Datatype	Purpose
None

This script holds macros that control the behaviour of Carton. __carton_config() never needs to be directly called in code, but the script and the macros it contains must be present in a project for Input to work.

You should edit this script to customise Carton for your own purposes.

Macro	Typical Value	Purpose
CARTON_BUFFER_START_SIZE	1024	Starting size of the buffer used for a carton

 

 

carton_create()

Returns: An empty carton - a container for multiple buffers (array datatype)

Name	Datatype	Purpose
None

Cartons act like other native GameMaker data structures and must be destroyed after creation to free memory.

 

 

carton_destroy()

Returns: N/A (undefined)

Name	Datatype	Purpose
carton	carton	Carton to destroy, freeing memory allocated for it

 

 

carton_count()

Returns: Integer, the number of buffers packed into the carton

Name	Datatype	Purpose
carton	carton	Carton to target

 

 

carton_add()

Returns: N/A (undefined)

Name	Datatype	Purpose
carton	carton	Carton to target
metadata	string	Metadata string to be included alongside the buffer
buffer	buffer	Buffer to add to the carton
[offset]	integer	Offset of buffer data to add, in bytes. If not specified, 0 is used (the start of the buffer)
[size]	integer	Size of the data to add, in bytes. If not specified, the size of the buffer is used

 

 

carton_get_metadata()

Returns: String, the metadata for the given carton buffer index

Name	Datatype	Purpose
carton	carton	Carton to target
index	integer	Carton buffer index to target

 

 

carton_get_buffer()

Returns: Buffer, a copy of the targetted carton buffer index

Name	Datatype	Purpose
carton	carton	Carton to target
index	integer	Carton buffer index to target

 

 

carton_save()

Returns: N/A (undefined)

Name	Datatype	Purpose
carton	carton	Carton to target
filename	string	Filename to save the carton to
compress	boolean	Whether to compress the carton before saving

 

 

carton_load()

Returns: Carton that holds data loaded from the file specified

Name	Datatype	Purpose
carton	carton	Carton to target
filename	string	Filename to save the carton to
decompress	boolean	Whether the file requires decompression