{"id":744,"date":"2023-03-26T12:50:46","date_gmt":"2023-03-26T19:50:46","guid":{"rendered":"https:\/\/porkrind.org\/missives\/?p=744"},"modified":"2023-03-26T18:22:07","modified_gmt":"2023-03-27T01:22:07","slug":"decoding-the-sprite-format-of-a-25-year-old-game","status":"publish","type":"post","link":"https:\/\/porkrind.org\/missives\/decoding-the-sprite-format-of-a-25-year-old-game\/","title":{"rendered":"Decoding the sprite format of a 25 year old game"},"content":{"rendered":"

My brother nerd sniped<\/a> me the other day. He wanted to see if he could extract the images out of an old game by Ambrosia Software<\/a> called “Slithereens”<\/a>. It was released on 1998-12-15 for Mac OS 9. That sounds easy enough\u2026<\/p>\n

\"\"<\/a><\/p>\n

Digging though resource forks<\/h2>\n

Old Mac OS had the ability to have a 2nd plane of data on a file called a “resource fork”<\/a>. Rather than being just arbitrary binary blobs, they had some structure to them. Back in the day there was tool called “ResEdit”<\/a> from Apple that let you poke around Resource Forks. Today there are open source clones out there. I grabbed “ResForge”<\/a> to look around with a nice GUI. I could have also used \/usr\/bin\/derez<\/code> which still ships with the developer tools even on the latest macOS 13.<\/p>\n

Here’s the list of resources in the Slithereen Sprites resource files:<\/p>\n

\"\"<\/p>\n

There’s just a handful of types. Poking around it looks like the SpRt<\/code> resources contain metadata about the animations and the SpRd<\/code> resources are just raw data, probably bitmaps.<\/p>\n

Here’s a SpRt<\/code> resource for the “Player 1 Head” sprite:<\/p>\n

\"\"<\/p>\n

That’s got a bunch of stuff, but really the only super interesting piece of data is the width: 24 pixels.<\/p>\n

As an aside, how did they get their custom animation data to show up parsed like that? That’s actually a cool feature of ResEdit\u2014you can defined TMPL<\/code> resources in your file and ResEdit will use them to decode and print your data nicely, allowing you to edit stuff right right from ResEdit and without any custom tools. Many programs would ship with their TMPL<\/code>s and so you could open the application with ResEdit and poke around their data. It’s sort of the equivalent of finding a .json<\/code> file in someones app nowadays. Here’s the TMPL<\/code> for the SpRt<\/code> resource:<\/p>\n

\"\"<\/p>\n

I didn’t want to start with the “Player 1 Head” sprite though. I wanted something more recognizable that would help when looking for patterns. A 24×24 square with a semi-circular snake head in the middle seemed to hard. I checked out the screenshot and noticed the “Level” text in the bottom right corner, which seemed promising:<\/p>\n

\"\"<\/p>\n

Distinctive shape, wider than it is tall. It looked like it was in a sprite called “Level”, so I checked out the SpRt<\/code> resource:<\/p>\n

\"\"<\/p>\n

It’s just a single animation frame, which seems like a good idea to start with\u2014less complications up front.<\/p>\n

Width 85. I can remember that number… But no Height for some reason. I zoomed up the screenshot and manually counted the pixels in the Level sprite. It looks like it is 22 pixels high.<\/p>\n

Now lets look at the data (in the SpRd<\/code> resource):<\/p>\n

\"\"<\/a><\/p>\n

I glance at this a little, but my eyes glaze over. It’s probably just bitmap data, after all.<\/p>\n

What I don’t know, though, is the layout of the bitmap data. It probably<\/em> goes top left to bottom right (as was the style of the time), but that’s not a given. What if it’s rotated or something weird? And how many Bits per Pixel (“BPP”) is it? 8 bit seems reasonable for that timeframe, but it could also be 4\u2014it doesn’t look like the sprites each have a ton of color.<\/p>\n

So I’m thinking I want a little data structure that I can read arbitrary bits from so that I can try rendering the bitmap with different BPPs. I decided to write it in Ruby and came up with this little class:<\/p>\n

class Bits\n  def initialize(bytes=[])\n    @bytes = bytes\n  end\n\n  def get(offset, length)\n    v=0\n    while length > 0\n      start = offset \/ 8\n      bit   = offset % 8\n\n      bs = bit\n      be = [8, bs+length].min\n      bits = be - bit\n      v = v<<bits | @bytes[start] >> (8 - be) & 0xff >> (8 - bits)\n\n      offset+=bits\n      length-=bits\n    end\n    v\n  end\nend\n<\/code><\/pre>\n
I also need the sprite data. I’ve saved the RsRd file out from ResForge and I can poke an prod it from the command line now. I read the man page for xxd<\/code> and discovered the -i<\/code> option which sounds perfect:<\/p>\n
\n  -i | -include:  Output in C include file style. A complete static array definition is written (named after the input file), unless xxd reads from stdin.\n<\/p><\/blockquote>\n
Neat. Now I can just do:<\/p>\n
$ xxd -i Level.sprd > level.rb\n<\/code><\/pre>\n
And then convert the C-ism to Ruby-ism in Emacs.<\/p>\n
I also write a little dump routine to dump the bitmap in rows and columns:<\/p>\n
def dump(data, width, height, bpp, start=0, stride=width)\n  (0..height).each {|y|\n    (0..width).each {|x|\n      pix=data.get(start + y * stride * bpp + x * bpp, bpp)\n      printf(\"%*b \", bpp, pix)\n    }\n    puts \"\"\n  }\nend\n<\/code><\/pre>\n
I don’t know if I’ll need stride or start, but it’s easy enough to add them now\u2014maybe they’ll turn out to be important later.<\/p>\n
dump(head, 12, 12, 4)\n<\/code><\/pre>\n
produces
\n<\/p>\n
   0    0    0    0    0    0    0    0    0    0    1 1000    0\n   0    0    1 1000    0    0    0    0    0   10  101    0    0\n   0    0    0    0    0    1    1   11    0    0    1 1000    0\n   0    1   10 1011    0    1    0    0    0    0    0    0    0\n   0    1    0    0    0    0    0    0    0    1    0    0    0\n   0    0    0    0    0    1    0    0    0    0    0    0    0\n   0    1    0    0    0    0    1  100    0   11    0    0    0\n   0    0    0 1010    0   10    0    0    0    0    0 1001 1111\n1111 1111 1111 1111 1111 1111 1111 1111 1111 1111 1111 1111 1111\n1111 1111 1111 1111 1111 1111    0    0    0    0    0    0    0\n   0    1    0    0    0    0    1  100    0   11    0    0    0\n   0    0    0 1000    0   10    0    0    0    0    0 1100 1111\n1111 1111 1111 1111 1010 1100 1111  110 1000    1 1010  111 1010\n<\/code><\/pre>\n
<\/small><\/p>\n
It doesn’t really look like anything. If you kind of squint the different patterns look like different greyscale blobs. Kinda. I play around with some numbers and run it a bunch of times but I can’t make the it look like anything except gibberish.<\/p>\n
I end up tweaking the code to output either X<\/code> or Space instead of the numbers (full program here<\/a>):<\/p>\n
dump(level, 85, 22, 8) {|pix| pix==0 ? \" \" : \"X\"}\n<\/code><\/pre>\n
produces<\/p>\n
<\/p>\n
     X X  XX     X XX   X  XX  XX  XXXXXXXXXX   X  XX  XXXXXX   X  XX  XX  XXXXXXXXXXX\nXXXX  XX  XXXXXXXXXX  XX  XX  XXXXXXXXXXXXXX   X  XX  XXXXXXXXXXX  X  XX  XX  XXXXXXXX\nXXXXXXX   X  XX  XXXXXXXXXXX  X  XX  XX  XXXXXXXXXXXXXX   X  XX  XXXXXXXXXXX  X  XX  X\nXX  XXXXXXXXXXXX X  XX  XXXXXXXXXXX  X  XX  XX  XXXXXXXXXX  XX  XXXXXX   X  XX  XXXXXX\nXXXXX   X  XX  XXXXXXX  X  XX  XXXXXXX  X  XX  XXXXXXXXXX   X  XX  XX  XXXXXXXXXX  XX\n  XXXXXXXXXX   X  XX  XXXXXXXXXXXXXXXXXXXXXX  XX  XXXXXXXXXXX  X  XX  XXXXXXXXXX  XX\n XX  XXXXXXXXXX  XX  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX X  XX  XXXXXXXXX\nXX  XX  XX  XXXXXXXXXX  XX  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX  XX  XX\nXXXXXXXXX  XX  XX  XXXXXXXXXX  XX  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n   X  XX  XXXXXXXXXX  XX  XX  XXXXXXXXXX  XX  XXXXXXXXXXXXXXXXXX  XX  XXXXXXXXXXXXXXXX\nXXXXXXXXXXXXXXXXXXX   X  XX  XXXXXXXXXX  XX  XX  XXXXXXXXXX  XX  XXXXXXXXXXXXXXXXXX  X\nXX  XXXXXXXXXXXXXXX  X  XX  XXXXXXXXXXXXXXXXXX   X  XX  XXXXXXXXXX  XX  XX  XXXXXXXXXX\nX  XX  XXXXXXXXXXXXXXXXXXXXXX   X  XX  XXXXXXXXXXXXXXX  X  XX  XXXXXXXXXXXXXXXXXX   X\n  XX  XXXXXXXXXX  XX  XX  XXXXXXXXXX  XX  XXXXXXXXXXXXXXXXXXXXXX   X  XX  XXXXXXXXXXXX\nXXX  XX  XXXXXXXXXXXXXXXXXX   X  XX  XXXXXXXXXX  XX  XX  XXXXXXXXXX  XX  XXXXXXXXXXXXX\nXXXXXXXXXX  XX  XXXXXXXXXXXX X  XX  XXXXXXXXXXXXXXXXXX  XX  XXXXXXXXXX  XX  XX  XXXXXX\nXXXXX   X  XX  XXXXXXXXXXXXXXXXXXXXXX   X  XX  XXXXXXXXXXX  X  XX  XXXXXXXXXXXXXXXXXX\n  XX  XXXXXXXXXX   X  XX  XX  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX   X  XX  XXXXXXXXXX\n  X  XX  XXXXXXXXXXXXXXXXXX  XX  XXXXXXXXXXXXXX  XX  XX  XXXXXXXXXXXXXXXXXXXX X  XX  X\nXXXXXXXXXXXXXXX  X  XX  XXXXXXXXXX  XX  XXXXXXXXXXXXXXXX X  XX  XXXXXXXXXXXXXX  XX  XX\nX  XXXXXXXXXXXXXXXXXXX  X  XX  XXXXXXXXXXXXXX   X  XX  XXXXXXXX X  XX  XXXXXXXXXXXXXXX\nX  X  XX  XXXXXXXXXXXXXX  XX  XX  XXXXXXXXXXXXXXXXXXX  X  XX  XXXXXXXXXXXX X  XX  XXXX\nXXX   X  XX  XXXXXXXXXXXXXX  XX  XXXXXXXXXXXX X  XX  XX  XXXXXXXXXXXXXXXXXX   X  XX  X\n<\/code><\/pre>\n
<\/small><\/p>\n
That doesn’t look like anything. I tweak more numbers but each time I have to edit the file then run it to get results. It feels slow. I need my turn-around time faster<\/em>! I kinda want a little UI and maybe have it respond to keystrokes. I start to think a web app could be nice…<\/p>\n
So I rewrite those same little code chunks in javascript. Now that I have a browser I can drop <input><\/code> tags down, grab a canvas and draw actual rectangles of different colors instead of printing X<\/code>s. I get it working and it’s still kinda slow, deleting those numbers and incrementing them\u2014sounds dumb but requires thought and I want to focus on looking for patterns not remembering how to type numbers quickly.<\/p>\n
The easy answer is to make “PgUp” and “PgDown” increment and decrement the number (and “Home” and “End” to increment and decrement by 10). This finally feels good. So I sit down and play:<\/p>\n