GZIP_Utils v1.0

GZIP_utils is a set of utility scripts providing access to ZIP, GZIP and TAR file formats without requiring any external library (everything is written in GML).

With GZIP_utils you can compress, decompress and read the metadata of ZIP and GZIP files, as well as expand TAR archives.

Moreover, you can also create zip and gzip files without even having an actual file on the filesystem by using the contents of a buffer instead.

Getting started

First of all, import the whole content of the asset from your marketplace library into your project. The asset includes only scripts located in a gzip_utils folder.

The following are a few examples on how to perform some common operations using the provided scripts. For details refer to the functions section of this documentation.

Create a zip archive and save it to file
var _zip = zip_create();
zip_add_file(_zip, "data/items.csv");
zip_add_file(_zip, "saves/slot_1.sav");
zip_add_file(_zip, "saves/slot_2.sav");
_zip = zip_close(_zip);

if(_zip >= 0) { buffer_save(_zip, "backup.zip"); }
buffer_delete(_zip);
Get the total size of the files before decompressing the zip
var _zip_info = zip_info("archive.zip");
var _usize = _zip_info[? "uncompressed_size"];
ds_map_destroy(_zip_info);

show_debug_message("Uncompressed size: " + string(_usize) + " bytes");
Create a gzip file compressing some csv data
var _gzip = gzip_create("data/items.csv");

if(_gzip >= 0) { buffer_save(_gzip, "items.csv.gz"); }
buffer_delete(_gzip);
Unzip a gzip file and, if it contains a tar archive, expand the archive
var _extracted_file = gzip_unzip("items.tar.gz", "data/");

if(filename_ext(_extracted_file) == ".tar") {
  tar_untar(_extracted_file, "data/");
  file_delete(_extracted_file);
}
Create a gzipped json file from a ds_map
var _json = json_encode(your_ds_map);

var _buffer = buffer_create(string_byte_length(_json), buffer_fixed, 1);
buffer_write(_buffer, buffer_text, _json);

var _gzip = gzip_create(_buffer, "data.json");
buffer_save(_gzip, "data.json.gz");

buffer_delete(_gzip);
buffer_delete(_buffer);

Compatibility

GZIP_Utils does not use any external library and should be compatible with most export modules, with the exception of HTML5 and javascript based modules.

The asset has been tested to be working on Mac and Windows exports both with and without YYC. If you find any problem in other export modules, please let me know by dropping an email to simoneguerra<at>ekalia.com

Caveats

Being a GML only asset, GZIP_Utils is limited in some aspects by the availability of specific GML features:

  • GML has no function to access a file modification and creation date, as well as other file attributes, therefore files added to zip and gzip archives will lose that information and use the compression datetime instead.
  • Unzipping gzip files relies on the internal zip_unzip function, meaning that unlike gzip_create, the gzip_unzip function can not return the extracted file in a buffer.
  • It is not possible at this time to create TAR archives (but it's a planned feature)

Function reference

Gzip

GZIP files can be created using gzip_create and unzipped using gzip_unzip. Please note that the gzip format, unlike zip archives, allows only a single file to be compressed.

gzip_create( filename | buffer, int_filename )

Compresses the specified data and returns a buffer with the gzipped data. You can then save the gzip data to the file system by using buffer_save or buffer_save_async.

int_filename sets the name of the compressed file in the gzip headers. Please note that this is an optional parameter in a gzip file, and sometimes it is ignored, using the gzip filename minus the extension instead.

Arguments
  • filename | buffer string | buffer name of the file or buffer holding data to compress
  • int_filename string name of the file
Returns
buffer buffer containing the gzip data

gzip_info( filename | buffer )

Reads a gzip file metadata and returns it in a ds_map. In case of errors reading the file, -1 is returned.

Arguments
  • filename | buffer string | buffer name of the gzip file or buffer holding gzip data
Returns
ds_map a ds_map with the gzip information

gzip_unzip( filename, target )

Decompresses the gzip file to the specified target destination, and returns the path to the file.

Arguments
  • filename string name of the gzip file to decompress
  • target string the target directory to extract the file to
Returns
string path to the extracted file

Tar

TAR is a file format for collecting multiple files in a single archive. TAR files are commonly used with GZIP in order to generate compressed archives.

GZIP_UTILS allows tar files to be expanded. Creation of tar archives is still not possible, but will be added in the future.

tar_untar( filename | buffer )

Extracts a tar archive at the specified location. Returns the number of extracted files, or a negative number in case of errors.

Arguments
  • filename | buffer string | buffer name of the tar file or buffer holding tar data
Returns
integer number of extracted files

Zip

ZIP files can be created by opening an empty zip container with zip_open and subsequently add one or more files using zip_add_file or zip_add_buffer.

When done adding data to the zip, calling zip_close will finalize and the container and return a buffer with the zip file data, that can be saved to the file system by using buffer_save or buffer_save_async.

Please note that you can not include multiple files at once by passing a folder name to zip_add_file, you'll need to pass every file explicitly.

zip_add_buffer( zip, buffer, filename )

Adds the content of a buffer to the zip container using the specified filename (folders or subfolders are allowed). The function will not alter the original buffer. Deleting the original buffer will not cause any problems after this function call, and you should in fact do so if you no longer need the uncompressed data.

Arguments
  • zip integer id of the zip container
  • buffer buffer buffer data to add to the zip container
  • filename string internal filaname of the file in the zip folder structure
Returns
integer size of the compressed data in bytes

zip_add_file( zip, ext_filename, [int_filename] )

Adds a file to the specified zip container, returning its compressed size (in bytes). By default, files added to the zip will keep their relative path with respect to the sanbox; a file stored in "Data/sample.csv" will be expanded into the "Data" folder as well at unzip time. You can change this by specifying a different folder and / or filename as int_filename.

Please note that you can not include multiple files at once by passing a folder name to this function, you'll need to pass every file explicitly.

Arguments
  • zip integer id of the zip container
  • ext_filename string file to add to the zip container
  • [int_filename] string internal filaname of the file in the zip folder structure
Returns
integer size of the compressed file in bytes

zip_close( zip )

Finalizes a zip file created using zip_open, and returns the zip data as a buffer that can be used to save the zip to the file system.

Arguments
  • zip integer id of the zip container
Returns
buffer buffer containing the zip data
Example
//closes a zip and saves it to file
var _buffer = zip_close(_zip);
buffer_save(_buffer, "file.zip");

zip_info( filename | buffer )

Reads the zip data held in the provided buffer or file and returns a ds_map holding the zip metadata. In case of errors reading the file, -1 is returned.

Arguments
  • filename | buffer string | buffer name of the zip file or buffer holding zipped data
Returns
ds_map a ds_map with the zip information

zip_open( )

Creates a container for a new zip file, and returns its id. You can then pass this id to the other zip functions in order to add files and generate the zip file with zip_close.

Returns
integer id of the zip container

Credits & Support

For any kind of question or issue relates to this asset, please contact me:

Developed with by Homunculus.

Uses CRC32 script by @jujuadams, u/JujuAdam, GMLscript.com/license