The Data of Zelda

I recently discovered Zelda Classic, a fascinating project to clone the classic Legend of Zelda game. This is what the original game looks like running in an emulator:

The Legend of Zelda

Why does anyone care? Look, it’s just a really cool game, okay?

These programmers created their own game engine and then cloned the original Zelda graphics for use in the game. But the real value-add is being able to create new quests, distribute them for others to play, and download other quests to play in the engine.

But I just can’t leave well enough alone. And I can’t contain my curiousity for how this thing operates. It’s free, but not open source (that makes it free as in beer but not speech for those of you who understand those terms better). A Linux engine is slated, but nothing is solid. But no engine source code will be released. However, just as in multimedia hacking, I maintain that the code is not nearly as important as the data. If the data file format for the quest files was known, independent, interoperable game engines could be created.

Let’s look at a sample data file: A file begins with a 24- (0x18-) byte signature consisting of the characters “Zelda Classic Quest File” (no NULL termination). From then on, the data is apparently encrypted. According to the documentation and forums over at the Zelda Classic website, the password is stored somewhere in the data file, in an obfuscated manner. The game engine needs to be able to decrypt and load the file. Whereas, if you load a file in the ZC editor, it will ask you for a password before allowing you to do anything with it.

If you are editing a quest file, you have the option of exporting an unencoded quest file (with an extension of .qsu). This file type begins with a signature of “AG ZC Enhanced Quest File”. It goes on to have a clear fourcc-chunked format. After sorting out the chunk types, I found out from the Zelda Classic forums that this file format is actually quite carefully documented. At the very least, C header file definitions are available:

Thanks to the quest editor it will be trivial to create custom quest files in order to explore the finer points of the data format. These are the primary data types in the Zelda Classic quest file which, oddly, are not completely documented in the aforementioned references (some had ‘not sure’ comments):

Header          'HDR '
Rules           'RULE'
Strings         'STR '
Doors           'DOOR'
DMaps           'DMAP'
Misc. Data      'MISC'
Items           'ITEM'
Weapons         'WPN '
Maps            'MAP '
Combos          'CMBO'
Color Data      'CSET'
Tiles           'TILE'
MIDIs           'MIDI'
Cheat Codes     'CHT '
Init. Data      'INIT'
Enemy Data      'GUY '

and the main chunk format (all multi-byte numbers are little-endian):

bytes 0-3    chunk type fourcc tag
bytes 4-7    2 16-bit numbers indicating versions
bytes 8-11   chunk size (not including 12-byte preamble)
bytes 12..   chunk payload

6 thoughts on “The Data of Zelda

  1. John Berry

    Hey, I’m trying to extract some tile images from an unencoded quest file (.qsu) based on your format document. Do you happen to have any details about the format used to encode tiles in the 128 data structures in the tile chunk?

    Also — if you happen to still have the file that contains the source for the exporter I’d love to get a copy of it. I’m not having any luck finding it at the links you posted — all dead. Thanks much!

  2. John Berry

    Hey Mike,

    Thanks for the details! I posted a Python reader over at my blog… I came up with this based on your docs. It take a .qsu file and spits out images for the tiles, and optionally an image of the overall map.

    Also, along the way I answered one of the questions in your document. In the Maps Chunk, each map contains a 16×11 array of 2-byte values. In the document you have this listed as

    176 LE16 data (16 x 11, tiles?)

    It turns out that these values are actually the IDs of Combos contained in the Combos Chunk – these specify the tile, color set, “walkability”, and a bunch of other stuff about a particular square of the map.

    Have fun and thanks for getting me started on this!


  3. Link

    They’re using MD5 for the quest password protection now…

    Also, there’s a new version – 2.5 – out later this month.

Comments are closed.