Working on a group project is never easy, that’s why source control was invented. Source control (SC) is handled by a version control system (VCS). Today there are many popular VCSs such as GIT, Mercurial, and SVN. These programs all allow SC to be used when handling a large group project. However using these programs is not an easy task, and prone to error when first attempts are made setting them up. In this post I will guide you through setting up SC in GameMaker Studio 2 (GMS2) and setting up a successful project using it.
Simply put, the best way to manage your code is with SC. It has many advantages over simply saving your files, or even daily/monthly backups. Several of which are…
External backup – Hard drives fail, and when they do you will lose anything that’s not saved elsewhere. By using SC you can use one of many online services to safely store a copy of your code, or set up a local server if you plan on working alone and have extra computers around.
Collaboration – Team collaboration is important. As a scientist I have to be able to communicate with and use data from multiple parties to finish projects. The same goes for any large programming effort. Grand Theft Auto 5 had hundreds of programmers working on it at points, and they all didn’t work out of the same computer. Using SC you can easily code on your local computer and load changes to collaborators.
Reversion – If during your project someone codes something that breaks the game, you can find the code that bugged and easily remove it from the source. Additionally this allows you to have “builds” of your game that are easy to pinch off as needed. Eg: I needed an older copy of one of my game jam games, so I was able to jump back in time to the way the game used to be, export a copy, then jump back to the current version of the game.
You should probably know these words as you go forward.
Repository – This can refer to either the local or remote (on server) code that’s being worked on.
Commit – Commits are time-stamped saves of changes to code. Eg: You’re working on your project and commit at 7:00, then your buddy who’s making changes on the same code commits at 7:02, the commit time allows the VCS to determine who made the first changes and what order they should be added to the source.
Push – Pushing is the act of actually sending your code to the remote repository for integration into the source.
Pull – As pushing is to sending, pulling is to receiving. When others make changes you need to get them, so you pull it from the repository.
Conflict – If you work on the same file as someone else, a conflict can arise! These are the bane of working with SC and always annoying. To avoid creating them, remember to commit often, especially if you’re working on a file used often by others.
GMS2 has a built in SC system which is great for people learning how to use it! This section will cover how to add Source Control to GMS2 and setup a new project with it. If you already have a remote repository you want to use then skip the Initial Commit section.
To get started you’re going to want to open a new copy of the GMS2 IDE, no project needed for now. Then you’ll want to open your IDE preferences, in the File tab. Once in the preferences you’ll want to find the SC option, which is under the Plugins tab.
In SC options you’ll see some check boxes and several tabs. Ignore the check boxes for now as we’ll be focusing on the tabs and the check box defaults work just fine.
Starting with the identity drop-down.
The identity is what will be shown in the “Author” field when you browse your code repository commits. So make sure you’re using a name and email that the whole team will know.
To use SC you’ll need an account with a VCS service. For the purposes of GMS2 you’ll want an account with either Github or Bitbucket. Both have their pros and cons, but I generally use Bitbucket for any project I don’t want publicly visible. If you know how and prefer you can set up your own local VCS service instead.
Ignore the SSH keypair option, unless you know what SSH is. For most users the Add User/Pass option will suffice. Click on it.
You’re going to need to enter your VCS service username and password here, so GMS2 can login to the site with it. Additionally you need a repository URL which can be obtained from your VCS service when you create a new repository. Make sure the repository you create uses GIT as that’s what GMS2 is setup to use. For the purposes of this article I created a project called “Flapper” on Bitbucket.
You can see on the overview page under the “I’m starting from scratch” tab where it gives you the information you need to create a new project. Use the URL in the “git clone...” line for your Repository URL, do not include the “git clone” part. Finding this information may vary in each VCS service, but in general it follows the form “https://[account name]@[URL to your repository].git”.
Now it’s time to create a new project using SC. Once you’ve created a new project you’ll want to open your project settings and tick the check box labeled “Enable Source Control”.
When you click “OK” a new menu with several new options will appear next to the “Help” tab.
You will want to select “Import Project into Repository”. Doing so will create another pop up which asks for the URL of the project repository.
This should be the same URL that you used when adding your credentials. Using the right URL will sync up your project with the credentials, so you can have multiple projects and multiple logins.
Clicking “OK” will have GMS2 hang for a second, then if you set your credentials correctly display a “Success!” box. The delay was because GMS2 was validating your credentials with the VCS service, then creating an invisible folder in your project file called “.git”. This folder contains all the information needed for GIT to do it’s job handling your files and sending them to the VCS service, you should never need to touch it. Additionally all the information about the project was sent up to the remote site, making the “initial commit”.
Returning to the VCS service website, click on the “Commits” link to see that the data has been successfully sent.
You can also go to the source tab to see the individual files and folders sent.
If you already have a remote repository that you want to copy, setup is much simpler. After adding your authentication instead of creating a new project, you’ll want to select the “Clone Repository” option from the Source Control tab. This will create a popup asking for some information.
Simply fill it in with the URL of the project, just like you did for the authentication, and the path to the folder you want to use for holding the project files.
Now that we have a project and it’s synced up with a VCS service, we need to know how to send data back and forth. This is very important because if you try to do things in the wrong order, conflicts can arise. All these options are accessed from the Source Control tab. Simply follow this pattern after making changes.
Commit → Pull → Refresh (always if asked) → Merge (if needed) → Push
When you commit you’re time-stamping your changes, so VCS knows in what order to place your changes compared to others. Selecting the Commit option will open a panel like this.
You’ll see a list of files that have been changed in the “Unstaged Changes” section. Typically you’ll want to use the “Stage All” option, unless for some reason you want to hold back a specific change. Also always add a “Commit Message”, this is your change log and keeping good logs makes fixing mistakes much easier. Commit often, and ALWAYS commit after creating/deleting a resource such as an object, or a script, or anything in the Resources bar of the IDE. Creating new resources adds data to the projects .yyp file, which can be a major cause for conflicts.
Pull, Refresh, Merge
When you pull you’re getting any new changes that anyone else has made and adding them into your project. You’ll also see popup list of things that have changed whenever you pull. Choose the “Reload” option that’s present on this list to refresh your files and see the changes. If you don’t refresh, you can create some serious problems, such as erasing your project members changes, in the next step because you’ll send data to the server that’s “old”. Additionally you’ll sometimes see a popup for “Source Control Conflicts”. These are files that the system was not able to automatically determine which changes were the ones you want to keep. Eg: You type A in a file, and your teammate types B on the same line, you’ll have to determine manually if you want to keep A or B. This can be done by using the “Use Mine” or “Use Theirs” options present on the popup. However, manually merging the files will require external software that you link to GMS2 and is beyond the scope of this tutorial. See the sources section for additional information on the topic.
Finally you’ll want to push your changes, making them available on the server to anyone else working on the repository.
Congratulations on setting up GMS2 with source control! Using SC will greatly improve your ability to collaborate with others in the future. SC is a bit of an art and you’ll learn how to utilize it better as you experiment. My experiences came in a rather abrupt manner when my project team decided to use SC for one of my earliest game jams, and none of us really had an idea how to do so. This led to about half the jam time being working on the project, and half being fixing SC errors! Don’t let this happen to you, set up some projects and test how to use SC with them before you start working on time critical projects or things you really don’t want to lose through accidents. Above all, keep programming and have fun!