Wednesday, July 3, 2013

Using Subversion With the Kobold2D Game Engine and Xcode

I've been messing about with some basic MacOS and iOS game development lately, and at the moment I'm working with the Kobold2D game engine, which is (mostly) a refinement of cocos2d.  I've found however that in Kobold's quest to make initial setup of a project easier, it sidesteps some of the normal setup that Xcode does when you add a project or file.  Some of this, such as Project Summary info like the Application Category and Bundle Identifier is easily fixed after the fact.  Version control setup, on the other hand, is marginally more complicated than normal (at least with Subversion).

With a bit of trial and error I think I've got a working procedure to get a new Kobold project to play nicely with Subversion.  Here are my assumptions for these instructions; the more you deviate from these the less this will be relevant, and I'll leave variations as an exercise for the reader:
  1. You're running Xcode 4.6 (I'm testing with 4.6.3)
  2. You've got Kobold2D 2.1.0
  3. You already have a repository set up and waiting at version 0 (zero)
  4. We're creating a pong clone called  -- oddly enough -- "pong"
Any text here in fixed width is intended to be cut and pasted directly into your Terminal if you desire.  However, I won't be held responsible if anything goes awry... I'm trusting that you're using your head and paying attention before you run any of these commands.

Create a Kobold2D Project

Run the Kobold2d Project Starter app.  Select the appropriate template (I'm going with Physics-Box2D) and set the project name to 'pong'.  You can also set your own Workspace name here if you want.  Make sure you uncheck "Auto-Open Workspace" because we don't want to have that open quite yet.  Click on the "Create Project from Template" button.

Import the Project into Subversion

In Terminal, set ~/Kobold2D/Kobold2D-2.1.0 as your current directory
cd ~/Kobold2D/Kobold2D-2.1.0
Make a new directory structure with the usual 'trunk', 'branches', 'tags' directory structure in it
mkdir -p pong-import/{trunk,branches,tags}
 Move your new 'pong' project into the new trunk directory
mv pong pong-import/trunk/
Change directory into pong-import and import the project and directory structure into your repository
cd pong-import; svn import . https://svn.mydomain.com/pong/ -m "Initial import"
Now delete this directory structure
cd ..; rm -Rf pong-import
That's it for the Terminal.

Add The Repository to Xcode

This is the only step that's exactly as it would usually be.  Go to the Xcode Organizer (menu Window -> Organizer) and select the Repositories tab.   Click on the + in the bottom left corner of the window and select Add Repository.   Follow the prompts to name the repository, give it the URI to the repository, add your authentication credentials, etc..  For the purposes of the example, let's say the URI for your repository is "https://svn.mydomain.com/pong/".

Check Out a Working Copy

While still in the Xcode Organizer Repositories tab, click on the expander arrow to the left of your 'pong' repository.  It should show four folders:  'Root' in purple, and your 'Trunk', 'Branches' and 'Tags' directories in yellow.  Select 'Root' and then click on "Checkout" in the button bar across the bottom of the Organizer.

This will open a standard Save dialogue.  Browse your way to ~/Kobold2D/Kobold2D-2.1.0/, type 'pong' into the Save As field, and click on Checkout.

Clean Up Your Workspace

Return to your Kobold-2.1.0 folder in the Finder.  Open the "Kobold2D.xcworkspace" workspace, or your custom workspace if you created one.

You'll see your pong project listed, but it'll be in red.  That's because the files aren't where the automatically-created workspace expects to find them.   Right click on that and select Delete.

Then, right-click again and select Add Files to "Kobold2D" (or whatever the name of your workspace is).  Browse to ~/Kobold2D/Kobold2D-2.1.0/pong/trunk/pong, select 'pong.xcodeproj' and click on Add.

You're Done!

You should now have a functioning Kobold2D project with all of the usual Xcode internal Subversion support available.  You should be able to pick a random file from your 'pong' project files, right click it and go to Source Control -> Update Selected Files and cause Xcode to check if there are updates available for that file.  

Good luck, and good gaming.