(This article is going to be geeky and technical and ranty.  Don’t say I didn’t warn you.)

As I’ve mentioned I’m prepping for the Glorious Trainwrecks’? THE 371-IN-1 KLIK & PLAY PIRATE KART II: KLIK HARDER event.  I’m on win7 and Klik & Play doesn’t really run all that easily, so I’ve been poking about for something else.  I did a bit with Construct, but it’s windows only, and I don’t really want to learn a new tool that isn’t going to give me some other benefit.

I thought about Unity, and that’s still a bit in the running, but I was already learning Python for other reasons, and pygame  is a fairly developed tool for making games.  I’m not looking for something fancy, just something I can quickly hack together, and make a few crapware games in a couple of hours each.  Once I’m more comfortable with the tools, and the games, I can develop the ones that seem good into something better.   To me the event is like a speed writing exercise, the goal isn’t something publishable,but something that’s creative that can be developed.

So, what I want to do is familiarize myself with the tools, and, if possible, find or write an engine that’ll let me do basic tile games (mazes and platformers, mostly).  I’ve found two or three of these, and they are either several years old, or quasi-documented.  PGU seems to be the most recently updated — and I’ve found in my years working with open source that you want two things: recent updates, and an active community.  That means the project is alive, and kicking, and working with the current suite of tools.

None of these tools that I’ve found have an active community, but PGU was updated in the past few months.  Unfortunately, PGU’s documentation leaves a lot to be desired.  I don’t really want to have to puzzle out someone’s code to figure out how it works — it’d be faster for me to just write my own code at that point.  If I’m using an engine, I want to not have to think about the low level implications of my decisions, and just move forward.

I don’t want to say that PGU’s documentation is bad. It follows a convention I’ve seen in the Java and Python worlds.  You put your documentation in the code, so it can be generated when you do a release.  You document functions and objects as you write them, and then everything is documented right?

Well, no. Not really.

There are two kinds of documentation that often — but not always — get left out of this. The first is systemic documentation, which tells you how all the pieces fit together and work together. A good project will have a page or two showing you how to fit all the pieces together to make something work.  Often this is a tutorial or a set of documented examples showing the project working.  PGU does this, but it feels largely esoteric.  Yes there’s code, and I can more-or-less see what it’s doing, but there’s some magic going on in there, and I’m not sure what it is.

That uncertainty, I realized was the missing second bit of documentation: file formats.  Unless you’ve got an object which reads and unpacks a file format and that process is documented in your Py or JavaDocs, you’ve got no documentation about your file formats.  PGU uses a Targa file (.tga, a graphic format) to store it’s tiles and maps.  The former, I get, the latter less so.

I delved into the code last night, to see if I could have an a-ha moment and move forward.  What I discovered was that he was being tricky. A graphics file is ultimately an array of color values, along with some information to tell you the shape of the rectangle that it is. In other words, it’s a 32 x32 graphic, the upper leftmost pixel is black, the next one is green, et cetera.

Color information is 32 bits in a Targa file (just like on your modern computer) it’s 8 bits for Red, Green, and Blue color values, and 8 bits for “alpha transparency”.  That’s how Vista and Win 7 (for example) manage to give you that  see-through the window look.   Getting the colors out of pygame is pretty easy, it’s Surface class will give you those four values for any pixel in an image.

The author of PGU is then using these four values for different things. I’m not 100% sure what they all are. One is the tile index, which I get and expected — tile games have a pretty stable design, they work a certain way, and I’ve worked with 5 or 6 different libraries, and they all share certain similarities. Another is something called “codes” and another is “background”.  He’s also using the alpha for something, but I’m not sure what.

Not knowing how all that works makes the code really hard to read.  Add to it’s object-oriented nature (I’m not against that, but it spreads the actual verbs around in ways that make it hard to trace through the code, as I bounce between API and program code)

I don’t want to invest too much time into this, I’ve got about 3 weeks to become proficient enough to make some games with something.  That’s like agreeing to write stories using a different keyboard than you were used to, and trying to Mavis Beacon your way through it.  Sometimes it’s better to find a different keyboard.

Today, I’m a bit tempted by HTML5, and I already know a great deal about that.