NON-PROGRAMMERS READ THIS

Download this silly physics toy:

“Typewriter”

• Mac version
• Windows version
  (Linux users: Source below)

Controls: Keyboard, mouse, F1, F4, ESC

PROGRAMMERS READ THIS

When I started writing Jumpman, something that frustrated me was that there are a couple of seemingly basic things that SDL/OpenGL doesn’t actually provide out of the box, and that I couldn’t seem to find a really good source for sample code for– things like drawing text, or creating a simple GUI, or building a crossplatform binary. So once the game was done I decided to clean up my code a little, strip out the “Jumpman” parts and release the basic skeleton as open source sample code. Below is that code, and a small tutorial on setting up Mac OS X such that it can build Windows and Linux executables. The hope is to make an overall package that would allow someone starting an SDL/OpenGL game to just sit down and start writing, rather than having to spend time downloading and fiddling with libraries.

The Jumpcore package comes in two versions. A minimal version that includes only:

• The ability to draw text (provided by the Freetype and FTGL libraries).
• A code snippet for managing “internal files” (which live in a directory named “Internal” on windows/linux, and inside the application package in OS X)
• Alt-tab support for OS X (SDL does not do this out of the box for fullscreen apps)
• Makefiles (and one .xcodeproj) for Windows, Mac and Linux

And a more fully featured version that also comes packaged with:

• The Chipmunk 2D physics library
• The LodePNG library (and a code snippet for loading PNGs into OpenGL textures)
• The TinyXML library
• Some color conversion routines
• A minimal “ControlBase” GUI library (dependent on Chipmunk)
• The “Typewriter” demo code linked at the top of this post.

The included libraries were picked in an attempt to include all the basic stuff a game needs, while still making the package as easy as possible to port and reuse in weird situations: all the libraries are self-contained and except for SDL itself can be built from the package as source where necessary; nothing depends on anything more complicated than the STL– I avoided heavyweight dependencies like Ogre or libpng; and everything is under a BSD-like license. The biggest limitation of the package at the moment is that it’s a bit mac-centric (I have not tested it with Visual Studio or Dev-C++).

Basically, here’s a box full of Legos and half a robot. Have fun.

DOWNLOAD

• Jumpcore source code (full version w/ typewriter demo)
• Jumpcore source code (minimal version)

HOW TO BUILD

Included is a Jumpcore.xcodeproj for compiling on mac, which can be compiled with XCode; windows makefile and support files are in a folder named win/, and can be compiled with mingw; Linux makefile and support files are in a folder named lin/, and can be compiled with gcc. More detailed instructions for all three platforms follow:

If you’re on a mac:

To build a mac executable, from a mac: Included is a Jumpcore.xcodeproj for use with XCode; just build that in Release mode and it should produce a 10.3.9-compatible universal binary (though note, I’ve not specifically tested it with 10.3.9).

If you’re on a mac and you want to build a Windows executable:

Here’s the best way I’ve found to do this:

1. There is a “Cross Compilers for Mac OS X” page here that actually has OS X installers for mingw. PPC and Intel versions are included; I installed 4.3.0 for Intel. The only problem with these particular installers is they install into strange places, so whichever installer from that page you pick, write down the “Installation directory” listed to the right of it.
2. Once you’ve installed an installer from that page, you need to install SDL headers. In order to do this, go to the SDL download page and look under “Development Libraries” -> “Win32″ -> “Mingw32″. Download that tarball. Once you’ve downloaded it ignore the “INSTALL” file, which is full of lies, and do this: Edit the “Makefile” in the directory so that the “CROSS_PATH” on line 4 is the “Installation directory” you wrote down in step 1. Like in my case this would be:
   CROSS_PATH := /usr/local/i386-mingw32-4.3.0

   Once you’ve done this, run “sudo make cross” and it will install the SDL headers into your mingw directory.

3. Go into the “win/” directory. Run “make” with the argument MINGW=[Installation Directory], where [Installation Directory] is again the directory from step 1– in my case this would be
   make MINGW=/usr/local/i386-mingw32-4.3.0

A directory named “Jumpcore” will be created with a Jumpcore.exe and all the support files necessary.

If you’re on a mac and you want to build a Linux executable:

Just distribute source. No, really. Building Linux binaries for distribution is tricky, and binaries aren’t what people want anyway. However if you want to do what I did and chicken out, what I recommend is installing Virtual Box or Q (probably Virtual Box, though Q is what I used) and loading up an Ubuntu install CD. This is quicker and easier than trying to set up a cross compile. Then go into the “lin/” directory and type “make”.

If you’re on Windows:

I was able to successfully compile Jumpcore on Windows by doing the following:

1. Download and install MinGW. (Make sure to install the C++ package.)
2. Download and install MSYS (it’s part of MinGW, but a separate download)
3. As described on the MinGW install HOWTO, add C:\MinGW\bin to your path: right-click “My Computer”, click “Advanced”, click “Environment Variables”, double-click the line that says “PATH”, and in the second line add the characters ;C:\MinGW\bin
4. Go to the SDL download page and look under “Development Libraries” -> “Win32″ -> “Mingw32″. Download that tarball and open up its contents in MSYS. Type “make native” and it will install itself.
5. A kind of odd step: right-click the file “README.txt”, open it in Wordpad, and immediately save it. (This will strip out my evil UNIX newlines.)
6. Go into the directory win/ and run: make WINDOWS=1

This will create an install directory named “Jumpcore”. If you want to compile for debugging, in that last step type: make WINDOWS=1 DEBUG=1

If you’re on Linux:

Install Freetype and SDL. Go into the directory lin/ and run make. This will create an install directory named “Jumpcore”. If you want to compile for debugging, instead type: make DEBUG=1

GETTING STARTED

Once you get the thing built, you’re going to want to start focusing on swapping out the Typewriter code for your own code. Jumpcore consists of a main.cpp that does basic bringup/teardown and event loop work hopefully good enough for most games, and makes callbacks as appropriate into a display.cpp (display logic) and a program.cpp (game logic) you provide. You’ll want to implement the following methods:

In display.cpp

display_init() - This is called once each time the display surface is initialized. It’s a good place to do things like initialize fonts and textures. (Note it could be called more than once if the window size ever changes.)

display() - This is called when it is time to draw a new frame.

audio_callback() - This is set up as the SDL audio callback.

drawButton (”full version” only) - This is a cpSpaceEach callback which the default display() calls on each interface item. If you want to change the appearance of the ControlBase controls this is a good place to do that.

In program.cpp

program_init() - This is called once when the program begins.

program_update() - The default display() calls this once per framedraw.

program_eventkey() - This is called when SDL gets a key event.

program_eventjoy() - This is called when SDL gets a joystick event.

program_eventmouse() - This is called when SDL gets a mouse event.

program_interface() - This is called after the event system finishes dispatching events to ControlBase controls, to give the interface a chance to redraw itself.

BackOut() - Called when ESC is hit (quits).

AboutToQuit() - Called right before the program quits.

Documentation for the individual libraries and functions included with Jumpcore can be found on these separate pages:

• Basic Jumpcore functions
• ControlBase GUI library
• Chipmunk documentation
• LodePNG home page
• TinyXML documentation

LIMITATIONS AND POSSIBLE FUTURE IMPROVEMENTS

I’m not really sure if this is ultimately going to be useful to anyone, and I don’t intend to maintain it unless there are people actually using it. However if there turns out to be any interest in this there are a few things I’d like to improve in a future release:

• The package contains everything you need to build a Windows version from a Mac. It would be awesome if I could eventually reach the point where a Windows user could build a Mac version (is that even possible?).
• Linux version is poorly tested in general. I have reports of issues on 64 bit systems, and the original Jumpman code seemed to have issues with switching to and from full screen mode.
• The final executable size is pretty large– 2 or 3 MB compressed for the very minimal typewriter demo. I’m curious if this can be improved on. At least on the mac a large chunk of this is taken up by SDL, which gets bundled along with the executable. However, to someone who’s using OpenGL to draw, a lot of this is wasted space– because much of the complexity in SDL is taken up by the 2D drawing support. I’d like to try to swap out the SDL libraries for versions that lack 2D drawing.
• iPhone compatibility? Now that I’m doing iPhone development I’m becoming pretty firmly convinced it does not make sense to create a single codebase that compiles on both PC and iPhone– the platforms are too different– but maybe it would make sense to rewrite some parts of the typewriter demo to make portability to something like iPhone easier (for example, rewriting the drawing code to be OpenGL ES-compatible).
• I am not sure that every library included with this is the most recent version.
• The one “every game needs this” feature that isn’t in this package is configurable joystick/gamepad support. I’m not sure whether it makes sense to try to add it or not.

Finally, there have actually been a number of interesting-looking SDL “game engines” released lately, so you should be aware of those in case one fits your needs better than Jumpcore does. Two I’m aware of are 2D Boy’s Boy engine and Mattias Gustavsson’s Pixie engine.

- Andrew McClure
mcc@grumpybumpers.com
http://runhello.com