Using Source Control with RPG Maker VX Ace

I mentioned in my intro to RPG Maker scripting post (and in the panel that’s based on it) that you can use source control systems like Mercurial or Git with RPG Maker VX Ace, allowing you to take periodic snapshots of your work.

(First, you’ll want to read a tutorial about how your chosen source control system works, such as hginit.com for Mercurial. This post will make a lot more sense once you do.)

What I neglected to mention is there’s two big, easy-to-forget gotchas with this setup.

Binary vs. Text Files

Most source or version control systems are built with two assumptions:

VX Ace stores its data binary rather than text files, so these assumptions are both right out the window. (MV uses text files, so it’s more source control-friendly.)

You can use source control for collaboration, but you’ll need to coordinate your saves and updates carefully, ensuring you’re never working on the same files at the same time. There’s no way to merge changes within the same file, so one of you will lose your changes.

Steam Cloud and Source Control Conflicts

The point of using source control is that, if you screw something up, you can easily rewind your project to a working backup.

However, there’s one easy-to-miss configuration setting that will prevent you from actually being able to do this.

So what's the problem?

Let’s walk through setting up a new RPG Maker VX Ace project in Mercurial using TortoiseHg. (Using Git is similar, although the terminology is different.)

This is sort of the long way around–I could simply point you to the button that will fix this issue–but I think it’s helpful to understand what’s going on behind the scenes here.

Find your project directory in Windows Explorer, right-click, and go to "Create Repository Here":

Create the repository, and then in the TortoiseHg workbench, mark all files in the project (except Game.exe, which is the built game) as added to the repository.

Mercurial (and most other source control systems) assume you don’t want any files tracked unless you explicitly say to "add" them. (Likewise, they won’t remove them from the repository unless you explicitly say to "remove" them.)

Once that’s done, commit your project to the repository:

If you’re backing your work up to an online service like Bitbucket or Github, you’d push your commit at this point.

Then, you’d go back to working. So, for example, I might add an island to the default ocean map:

Let’s say that I’ve hit a stopping point, and want to make another snapshot of my work. I’d save my project in RPG Maker VX Ace, and then go back to TortoiseHg Workbench and refresh my files.

You’ll see that three files have changed ("M" for modified): Map001.rvdata2, System.rvdata2, and Game.ini. Game.ini is a text file, so I’ll see my changes, but the .rvdata2 files are binary–whatever I commit is all-or-nothing.

Once I commit, I’ll see two commits in the panel above. My newest commit, with the message "Changed the map," is the tip (that is, the latest commit) in the default branch (because I could technically commit multiple versions side-by-side). When I click on each commit, I can see which files changed.

I can also right-click on a commit and Update to it, reverting my project folder to the state it was in when I committed that snapshot. (I might want to do this if, for example, I broke something in the Script Editor and couldn’t fix it.)

When I Update, I’m going to close and re-open RPG Maker to reload my project–it doesn’t know that TortoiseHg updated my files on disk.

TortoiseHg’s Graph will now show that my Working Directory (that is, the current version of the project on disk) is built off of the files in my first commit. It will also warn me that this isn’t the most current version I have in source control. (If I was trying to recover from an error I made in that commit, this might be what I want to do.)

And here's the gotcha

So, let’s recap: using TortoiseHg, I’ve essentially rewound history, reverting the project files on my hard drive to a new, fresh RPG Maker VX Ace project.

The island that I created should be gone, replaced with the default ocean map that RPG Maker creates in that new project.

And so, I open RPG Maker again, and…

Wat.

At this point, if you were trying to recover from an error, you’d be screwed, because you couldn’t get to that backup. And you’d probably think I sold you a bill of goods on this whole complicated source control ordeal.

So what happened?

Steam Cloud happened. RPG Maker VX Ace saves its files to Steam Cloud so that you always have a backup–which would otherwise be useful.

When I opened RPG Maker, it checked Steam Cloud and made sure I had the latest copy I’d saved. Of course, this isn’t what I want; I deliberately want to go back to an old backup of the project.

From my experimentation, it looks like this might even overwrite the .hg folder in my project, which is how Mercurial’s magic works–all my snapshots and related information is stored there. If the .hg folder goes away, I’ve lost all of my backups.

Turning off Steam Cloud on a project

By default, RPG Maker enables Steam Cloud on every project. You can find these options under File > Manage Projects:

This will show me a list of all RPG Maker VX Ace projects I’ve ever worked on:

It’s hard to see, but the projects on Steam Cloud have a little cloud icon and show the size of the project under the Cloud column. Projects not tracked by Steam Cloud have a little hard drive icon and show the size of the project under the Local column.

If you select your project and click "Delete From Cloud," RPG Maker will delete whatever is saved on your Steam Cloud and default to using your local copy. Remember, you’ll need to do this every time you start a new project–you should probably use it before you create your repository.

If you decide you want to stop using Mercurial or Git, you can simply delete the .hg or .git folder from your project and click "Save on Cloud" to go back to syncing over the internet.

Conclusion

If you decide to try working with source control, hopefully this saves you some pain.

Source control was something that took me a long time to understand and even longer to really appreciate, but once I did, it became indispensable. (It’s way more convenient than emailing files back and forth, or making multiple copies of your project folder.) If you want to get deeper into game development or programming of any sort, it’s worth trying out sooner rather than later.

This was originally posted on my personal blog, dylanwolf.com.