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

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)

By default, 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 behaviour
can be changed with the --preserve-ids command line option:

java -jar gmksplit.jar --preserve-ids all <input> <output>

  objects (default): Only Object IDs are stored in the directory tree.
  all: The IDs of all resources, room instances and tiles are stored as well.
       Resource IDs are stored as "id" attributes in the XML files; script IDs
       are stored in a comment of the form /* !scriptId=123 */ in the first
       line of the .gml file.
  none: No IDs are stored at all. Note the caveat about instance execution
        order above.

Use the same setting when splitting and rejoining a project - IDs that were not
stored when splitting are assigned anew when the .gmk file is built. Duplicate
IDs (which can result from merging branches) are resolved automatically.

Some projects intentionally reuse tile or instance IDs in different rooms. To
keep those duplicate IDs unchanged when using "--preserve-ids all", list the
types to allow as a comma-separated value:

java -jar gmksplit.jar --preserve-ids all --allow-duplicate-ids tiles,instances <input> <output>

The currently supported values are "tiles" and "instances". Either may be used
alone. Missing or invalid IDs are still assigned above the existing maximum,
and duplicate resource IDs are still resolved automatically.


Character sets (non-ASCII text in .gmk files)

Game Maker 8.0 stores all text in a .gmk file (resource names, scripts, captions
and so on) in the Windows ANSI code page of the system it runs on, without
recording which code page that was. A .gmk file created on a Korean Windows
system contains MS949 (EUC-KR) text, one created on a Western European system
contains windows-1252 text, and so on. Only plain ASCII text looks the same in
all of them. GM 8.1 (.gm81) files always use UTF-8 and are not affected by any
of this.

By default, Gmk Splitter assumes the code page of the system it is running on,
which is correct if the file was created on a similar system. If the .gmk file
was created on a system with a different code page, specify it with the
--charset option:

java -jar gmksplit.jar --charset MS949 game.gmk game_tree

The charset that was used when splitting is stored in the file _metadata.xml in
the root of the directory tree, and used again when the tree is joined into a
.gmk file, so --charset is usually only needed for splitting. It may be given
when joining as well, to override the stored charset or when the tree was created
by an older version of the tool without _metadata.xml. The tree itself always
uses UTF-8.

Gmk Splitter prints a warning if the text of a .gmk file cannot be decoded with
the charset in use (a sign that the charset is wrong), if text cannot be
represented in the charset used for writing a .gmk file (those characters are
replaced), and if a .gmk file with non-ASCII text is written as UTF-8 without
being asked for it, since GM 8.0 will most likely not display such text
correctly.