helt-ion / gmk-splitter Goto Github PK

Purpose

The main use of Gmk Splitter is to enable Game Maker projects to use version
control tools like git and Mercurial.

Game Maker usually stores the code and resources of a game in a single "source"
file (.gmk / .gm81). This makes it impractical to use version control tools
with Game Maker projects, because they see the project source as a single binary
blob.

Gmk Splitter solves the problem by splitting your .gmk file into a directory
tree filled with .xml (resource description), .gml (script), image and sound
files, and which resembles the folder structure that you see in Game Maker.
This directory can be put under version control, and converted back into a
.gmk file for editing and compiling with Game Maker.

Newer versions of Game Maker (HTML Studio) introduced a new source format called
GMX which is similar to the file tree produced by this tool (but not compatible
with it). I don't have any experience with it, but if you have the option, I
suggest using it over Gmk Splitter since it is an integrated and supported part
of Game Maker.


How to use

Gmk Splitter is distributed as a jar file (gmksplit.jar). To run the tool,
you need to have a recent version of Java installed.

The basic command line is
java -jar <path_to_gmksplitter>/gmksplit.jar <input> <output>
Either the input or the output parameter must be a filename ending with ".gmk"
or ".gm81".

If the .gmk file is given as input, it will be disassembled into the directory
given by the output parameter. This directory must not already exist, since the
tool won't overwrite files or directories for safety reasons. The output format
can differ slightly for source files created with different versions of
Game Maker.

If the .gmk or .gm81 file is given as output, it will be created by the tool from
the directory given as input parameter. The format of the generated file depends
on the extension you provide: .gmk files will be created compatible for GM8,
.gm81 files will be in the slightly changed format of GM8.1. Some information
can only be represented in the .gm81 format. If the source tree contains such
information, a warning will be generated.


Limitations/Bugs

This tool has only been tested with GM8 .gmk and .gm81 files so far. Reading older
formats *should* work, but the output will always be in GM8 or GM8.1 format
(depending on the file extension of the destination file).
Not all data contained in GM8 files is converted yet, and some (like timestamps)
will never be supported because they are not useful for the purpose of this tool.

These features are currently not supported but will be in later versions:
- Triggers
- Optional retention of all IDs

These features are not supported and might not make it later either:
- Action Libraries

These features won't be supported:
- Timestamps (last modification of individual resources)

No IDs except those of Objects are stored with the game data. In early
versions the tool tried to keep this information intact, but this strategy has led to
unneccessary problems with otherwise unproblematic merges. Version 0.8 got rid of IDs
entirely, but this caused suble problems with the execution order of different instances.
Now Object IDs are retained again to prevent this problem and minimise useless information
in the tree format. As long as your game doesn't reference resources,
instances or tiles by their numeric ID, the loss of ID information shouldn't affect the
function of your game.

Since keeping IDs intact might be important for other uses of this tool, the code was
not completely removed. A command line interface to expose this option will be added
in the future.