Print

Please login or register.
1 Hour 1 Day 1 Week 1 Month Forever
Login with username, password and session length

[Orpheon]

Programming and submitting code for GG2 (or: How to use Git)

To start contributing to Gang Garrison 2, you need to know three things:
- How to use Game Maker, which GG2 is written in,
- how GG2 works internally, and
- how to use GmkSplitter and Git for collaboration.

If you have general questions about with Game Maker, you can look in the General GML FAQ and Help thread in the Mods forums. Questions about GG2s internal workings can be asked in this forum. This text is about explaining the third aspect, the tools we use for collaboration.

Programming in groups can be difficult to organize. If everyone simply changes the game and uploads his own version somewhere, you will have a lot of trouble combining them into a single version that has all the improvements.

If you've worked in programming teams before, you might've heard of so-named version control systems. We use one named Git.

Git keeps track of the history of a project, that is, it remembers the entire content of the project in each version, as well as information about who made which changes, and which original version each new one is based on. With that information, Git can often automatically merge versions from two "branches" of development that have evolved in parallel.

The basic idea is that you develop new features in branches that are based on some official version, and that are tracked with Git. Once a feature is tested and ready, you can ask to have it included in e.g. the next official release of GG2. Because Git can figure out the changes, other developers can easily see what you did, and apply your changes to the official vanilla version - or their personal mod.

However, Git was written with projects in languages like C or Java in mind, where your actual source consists mostly of text files. They can track binary files too, but they can't meaningfully find differences between them or merge them. And to these tools, a Game Maker .gmk is just a big binary file.

Gmk Splitter
To solve this problem, enter GmkSplitter. It can split a .gmk into a file tree of .xml-, .gml-, image- and sound files. This file tree is a good format for using the tools discussed above, and can later be reassembled into a fully functional .gmk by Gmk Splitter.

Using Gmk Splitter:

(click to show/hide)

Download Gmk Splitter from http://github.com/Medo42/Gmk-Splitter/downloads. You'll also need a recent version of Java installed to use it. The zip file contains a gmksplit.jar and a gmksplit.exe. Those are actually the same program, but gmksplit.exe can be run directly on Windows without explicitly calling Java. It's a console tool, so double-clicking it won't do anything. See the readme for detailled usage instructions.

Now, you can try splitting and reassembling the game. I recommend creating a new directory for that, where you put the gmksplit.jar and the .gmk file of GG2 (or any other .gmk). Let's assume that the .gmk is called xyz.gmk and you want to split it into an output directory called xyz_split. Open a console, enter the directory you just created and type

Code: [Select]

java -jar gmksplit.jar xyz.gmk xyz_split
On Windows, the .exe version makes it slightly easier:

Code: [Select]

gmksplit.exe xyz.gmk xyz_split
Don't worry, the tool won't overwrite or delete anything, so you can't do much wrong when you try it out. Look around a bit in the resulting directory to get familiar with the format. It's very similar in structure to the resource tree in Game Maker.

Now let's create a new .gmk from that. In the console, enter:

Code: [Select]

java -jar gmksplit.jar xyz_split xyz_reassembled.gmk
This will create a new file called xyz_reassembled.gmk that should be functionally identical to xyz.gmk - except for the issues detailled in the readme. Look at the output of the tool, you might get warnings or errors sometimes.

The file tree format is not really meant for developing in, you should still use Game Maker for that.

Git and Github
Now that this is out of the way, let's get to the most interesting tool. However, I won't give a full introduction to Git because other people have already done that and probably better than I could, too.

http://gitref.org/ offers a good and comprehensive introduction. I know it's a scary amount of information to absorb at first, but you're learning to use a very powerful tool here that you will be able to use in your future projects too. Many small and big projects - most prominently the Linux kernel - are managed using Git. If you want to work as a professional programmer, chances are good that you'll have to learn using it - or another version control system - sooner or later anyway.

You can find the latest version of Git on its homepage www.git-scm.com
I recommend going with msysgit instead of cygwin for Windows if you're unfamiliar with this whole shebang. When you set it up, please follow the help documentation on Github: http://help.github.com/
One relatively important question that comes up during installation is whether you want git to automatically convert your line endings between Windows and Linux conventions (crlf/lf only). I strongly recommend you to disable this feature (checkin and checkout as-is).

In order to allow you to make branches of GG2, Medo put up a public repository at Github: http://github.com/Medo42/Gang-Garrison-2 EDIT: New URL, GG2 has moved: https://github.com/Gang-Garrison-2/Gang-Garrison-2
It contains all the development since 2.2, including non-released stuff. The versions have been tagged, so you should be able to find the one you are looking for.


If you want to collaborate on GG2, you should register an account on Github and follow the steps in the help to get set up. Since you can’t write to the official GG2 repository, you first need to make your own copy of it that you can work on, by hitting the fork button on the GG2 repository page. Then you can clone that new repository to your hard disk as described here:
http://help.github.com/forking/. You now have two copies of the repository that you can do with whatever you want - one on Github, and one on your PC.

To develop a new feature, you probably want to use the most recent version in the “master” branch as basis, because this is the most recent “official” development version. If you want to work on multiple big features, it is a good idea to make a separate branch for each one, each based on an official version, so that they can be individually reviewed and merged.

The basic workflow looks like this: First, create the gg2.gmk file by running gg2GitToGmk.bat in the Source directory. Careful, this will delete the file if it already exists. Then, open the .gmk in Game Maker to work on your changes. Once you are done with one task, hit save and split the .gmk into the Source/gg2 directory again by running gg2GmkToGit.bat. Again, be careful since this will delete the directory first. Next, commit your changes. Please describe all (high-level) changes in your commit comments so people can easily see what you did without looking through the entire code.

Once your feature is done, push the branch to Github and send a pull request, and it’ll hopefully get accepted.