ZeldaClassic Quest File Format by Mike Melanson (mike at multimedia.cx) Version 0.1: November 1, 2005 Copyright (c) 2005 Mike Melanson Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". Contents -------- * Introduction * ZeldaClassic Quest File Format * Header Chunk * Rules Chunk * Door Chunk * Data Map Chunk * Miscellaneous Chunk * Items Chunk * Weapons Chunk * Maps Chunk * Combos Chunk * Color Chunk * Strings Chunk * Tiles Chunk * MIDI Chunk * Cheats Chunk * Guys Chunk * Initialization Chunk * References * Changelog * GNU Free Documentation License Introduction ------------ ZeldaClassic is a project to recreate the classic Legend of Zelda 8-bit NES game for modern computers. The project primarily consists of an engine for playing the game and a data file with all of the game data. The real value-add for this project is the ability to create new quests via the packaged ZQuest editor. The ZeldaClassic project has released a C++ file from the codebase that writes an unencoded quest file (.qsu extension). This file attempts to document the finer details of the format's data structures. Note that the editor saves files as .qst files which are compressed and encrypted. Thus, this format description does not apply to those files. It is assumed that after .qst files are decrypted and decompressed they follow this format. This document is still very much a work in progress and many field names are copied from the source code without any extra explanation. ZeldaClassic Quest File Format ------------------------------ All multi-byte numbers are little-endian. In this description, an LE16 data type refers to a little-endian 16-bit number. An LE32 data type refers to a little-endian 32-bit number. A ZeldaClassic quest file is comprised of signature followed by a series of chunks laid out in a traditional four-character code (fourcc) chunk format. The file signature string is 31 bytes long: "AG ZC Enhanced Quest File" + 0x0A 0x20 0x20 0x20 0x00 0x20 Chunks can presumably occur in any order. Each chunk begins with the following 12-byte preamble: bytes 0-3 chunk type fourcc tag bytes 4-5 LE16: version bytes 6-7 LE16: compatible version bytes 8-11 LE32: chunk size (not including 12-byte preamble) bytes 12.. chunk payload Header Chunk ------------ This is the basic information about the quest file. 12 bytes preamble; type: 'HDR ', size: 488 bytes 1 LE16 Zelda version 1 byte build 30 bytes password 1 LE16 pwdkey 1 LE16 internal 1 byte quest number 9 bytes major version (ASCII) 9 bytes minor version (ASCII) 65 bytes title 65 bytes author 1 byte use_keyfile n bytes data flags n bytes template path 1 byte 0 n bytes reserved (set to 0) Rules Chunk ----------- This defines a number of properties enabled in the quest file. 12 bytes preamble; type: 'RULE', size: 20 bytes 20 bytes quest rules 1 LE16 [rules, page 1] bit 15 3 or 6 Triforce Total bit 14 View Overworld Map bit 13 Fast Heart Refill bit 12 24 Heart Containers bit 11 Big Triforce Pieces bit 10 Start With 999 Rupees bit 9 Cool Scrolling bit 8 No Level 3 CSet Fix bit 7 Fast Dungeon Scrolling bit 6 Fade CSet 5 bit 5 Interpolated Fading bit 4 BS-Zelda Animation bit 3 Multi-Directional Traps bit 2 Enemies Always Return bit 1 Temporary No Return Disabled bit 0 Solid Blocks 1 LE16 [rules, page 2] bit 15 No Flashing Enemy Death bit 14 Fire Boomerang Sparkles bit 13 Magic Boomerang Sparkles bit 12 Golden Arrow Sparkles bit 11 Silver Arrow Sparkles bit 10 Hide Enemy-Carried Items bit 9 Hesitant Push Blocks bit 8 Animate Held Items bit 7 Fix Link's Position in Dungeons bit 6 Show Lens Hints bit 5 Raft/Ladder Fix bit 4 Continue With Full Life bit 3 No Sprite Flicker bit 2 Must Kill All Bosses bit 1 Freeform Dungeons bit 0 Show time on Subscreen 1 LE16 [rules, page 3] bit 15 Sword/Wand/ Flip Fix bit 14 Dodongo CSet Fix bit 13 No Heart Ring bit 12 Heart Ring Fix bit 11 No Guy Room Fires bit 10 Linked Combos bit 9 Allow Fast Messages bit 8 Phantom Placed Traps bit 7 Mean Placed Traps bit 6 Broken Darknut Shield Tiles bit 5 Breakable Darknut Shields bit 4 Temporary Clocks bit 3 No Random Clocks bit 2 Bombs Hurt bit 1 Own Fire Doesn't Hurt bit 0 Can Keep Old Items 1 LE16 [rules, page 4] bit 15 Show Shadows bit 14 No Melee Weapon Grabbing bit 13 New Boomerang/Hookshot bit 12 Ghini 2 Translucency bit 11 Weapon Animation Fix bit 10 Ghini 2 Flickering bit 9 No Bubble Flashing bit 8 No Rope 2 Flashing bit 7 New Enemy Tiles bit 6 Non-Bubble Triforce bit 5 Non-Bubble Fairies bit 4 Non-Bubble Medicine bit 3 Boots Use Magic bit 2 Candle Uses Magic bit 1 Wand Uses Magic bit 0 Enable Magic 1 LE16 [rules, page 5] bit 15 reserved, set to 0 bit 14 reserved, set to 0 bit 13 reserved, set to 0 bit 12 N. Love Rocket Flickers bit 11 Trans. N. Love Rocket bit 10 N. Love Shield Flickers bit 9 Trans. N. Love Shield bit 8 No Bomb Palette Flash bit 7 Fliers Can Appear on Walls bit 6 Shadows Flicker bit 5 Invincible Link Flickers bit 4 No Potion Combining bit 3 Full Link Tile Modifiers bit 2 Bomb Hold Fix bit 1 Quick Sword bit 0 Translucent Shadows 10 bytes reserved, set to 0 Door Chunk ---------- 12 bytes preamble; type: 'DOOR', size: variable 1 LE16 number of door combo data structures foreach door combo in count [up door data] 36 (9 * 4) LE16 door combo data 36 (9 * 4) bytes door cset data [down door data] 36 (9 * 4) LE16 door combo data 36 (9 * 4) bytes door cset data [left door data] 36 (9 * 6) LE16 door combo data 36 (9 * 6) bytes door cset data [right door data] 36 (9 * 6) LE16 door combo data 36 (9 * 6) bytes door cset data [up bomb data] 2 LE16 bomb combo data 2 bytes bomb cset data [down bomb data] 2 LE16 bomb combo data 2 bytes bomb cset data [left bomb data] 3 LE16 bomb combo data 3 bytes bomb cset data [right bomb data] 3 LE16 bomb combo data 3 bytes bomb cset data [walkthrough stuff] 4 LE16 walkthrough combo data 4 bytes walkthrough cset data 2 bytes flags Data Map Chunk -------------- 12 bytes preamble; type: 'DMAP', size: each record is 199 bytes 1 LE16 number of dmap data structures foreach dmap in count 1 byte maps 1 byte level 1 byte xoff 1 byte compass 1 byte color 1 byte MIDI 1 byte cont 1 byte type 8 bytes grid 21 bytes name 21 bytes title n bytes intro 1 LE16 minimap_1_tile 1 byte minimap_1_cset 1 LE16 minimap_2_tile 1 byte minimap_2_cset 1 LE16 largemap_1_tile 1 byte largemap_1_cset n bytes t_music (tracker music?) Miscellaneous Chunk ------------------- 12 bytes preamble; type: 'MISC', size: variable [shops] 1 LE16 number of shop data structures foreach shop in count 3 bytes items 3 LE16 prices [infos] 1 LE16 number of info data structures foreach shop in count 3 bytes str 3 LE16 prices [warp rings] 1 LE16 number of warp ring data structures foreach warp ring in count 8 bytes dmap 8 bytes scr [wind warps] 1 LE16 number of wind warp data structures foreach wind warp in count 1 byte dmap 1 byte scr 8 bytes triforce piece data 1 byte text color 1 byte caption color 1 byte overworld background color 1 byte dungeon background color 1 byte dungeon foreground color 1 byte cave foreground color 1 byte bs_dk color 1 byte bs_goal color 1 byte compass_lt color 1 byte compass_dk color 1 byte subscr_bg color 1 byte triframe color 1 byte link dot color 1 byte bmap_bg 1 byte bmap_fg 1 byte triforce cset 1 byte triforce frame cset 1 byte overword map cset 1 byte dungeon map cset 1 byte blueframe cset 1 LE16 triforce tile 1 LE16 triforce frame tile 1 LE16 overworld map tile 1 LE16 dungeon map tile 1 LE16 blueframe tile 1 LE16 HCpieces tile 1 LE16 HCpieces cset 8 bytes 4 16-bit words for save game icons 1 LE16 end string Items Chunk ----------- 12 bytes preamble; type: 'ITEM', size: each record is 11 bytes 1 LE16 number of item data structures foreach item in count 1 LE16 tile 1 byte misc 1 byte cset 1 byte frames 1 byte speed 1 byte delay 1 LE32 ltm Weapons Chunk ------------- 12 bytes preamble; type: 'WPN ', size: each record is 7 bytes 1 LE16 number of weapon data structures foreach weapon in count 1 LE16 tile 1 byte misc 1 byte cset 1 byte frames 1 byte speed 1 byte type Maps Chunk ---------- A Maps chunk contains n maps. Each map has 136 screens. Each screen data structure contains 1298 bytes. A map has 128 screen on the main map arranged as a 16x8 grid, plus 8 special screens reserved for other purposes. 12 bytes preamble; type: 'MAP ', size: each record is 136 * 1298 bytes 1 LE16 number of map data structures foreach map in count foreach of 136 screens in map 1 byte valid 1 byte guy 1 LE16 str (string ID?) 1 byte room 1 byte item 1 byte time warp type 1 LE16 door combo set 1 byte warp return X coordinate 1 byte warp return Y coordinate 1 byte stair X coordinate 1 byte stair Y coordinate 1 byte item X coordinate 1 byte item Y coordinate 1 byte color 1 byte enemy flags 4 bytes doors 1 byte tile warp dmap 1 byte tile warp scr 1 byte exit dir 10 LE16 enemies 1 byte pattern 1 byte side warp type 1 byte warp arrival X coordinate 1 byte warp arrival Y coordinate 4 bytes path 1 byte side warp scr 1 byte side warp dmap 1 LE16 under combo 1 byte under cset 1 LE16 catchall 1 byte flags 1 byte flags2 1 byte flags3 6 bytes layer map 6 bytes layer screen 6 bytes layer opacity 1 LE16 timed warp tics 128 LE16 secret combo 128 bytes secret cset 128 bytes secret flag 176 LE16 data (16 x 11, tiles?) 176 bytes sflag 176 bytes cset Combos Chunk ------------ 12 bytes preamble; type: 'CMBO', size: each record is 11 bytes 1 LE16 number of combo data structures foreach combo in count 1 LE16 tile 1 byte flip 1 byte walk 1 byte type 1 byte cset 1 byte frames 1 byte speed 1 LE16 next combo 1 byte next cset Color Chunk ----------- 12 bytes preamble; type: 'CSET', size: variable n bytes colordata (size = newpsTOTAL) n bytes palnames (size = MAXLEVELS*PALNAMESIZE) 1 LE16 palcycles foreach count in palcycles 3 bytes first 3 bytes count 3 bytes speed Strings Chunk ------------- This chunk contains all of the textual strings used through a quest. 12 bytes preamble; type: 'STR ', size: each record is 75 bytes 1 LE16 number of string data structures foreach string in count 73 bytes string 1 LE16 ID of next string Tiles Chunk ----------- This chunk defines all of the tile data throughout the game. 12 bytes preamble; type: 'TILE', size: each record is 128 bytes 1 LE16 number of tile data structures foreach tile in count 128 bytes tile MIDI Chunk ---------- 12 bytes preamble; type: 'MIDI', size: variable ... Cheats Chunk ------------ 12 bytes preamble; type: "CHT ', size: variable 1 byte cheats flag if (cheats flag is non-zero) LE32 extended cheats flag n bytes cheat codes data structure Guys Chunk ---------- 12 bytes preamble; type: 'GUY ', size: 0 bytes [no data in this chunk yet] Initialization Chunk -------------------- 12 bytes preamble; type: 'INIT', size: 174 bytes 1 byte raft 1 byte ladder 1 byte book 1 byte key 1 byte flippers 1 byte boot 1 byte ring 1 byte sword 1 byte shield 1 byte wallet 1 byte bracelet 1 byte amulet 1 byte bow 1 byte candle 1 byte boomerang 1 byte arrow 1 byte potion 1 byte whistle 1 byte bombs 1 byte superbombs 1 byte wand 1 byte letter 1 byte lens 1 byte hookshot 1 byte bait 1 byte hammer 1 byte Din's fire 1 byte Nayru's love 1 byte cloak 1 byte hc 1 byte start heart 1 byte cont_heart 1 byte hcp 1 byte max bombs 1 byte keys 1 byte rupies 1 byte triforce 32 bytes map 32 bytes compass 32 bytes boss key 16 bytes misc 4 bytes sword hearts 1 byte last map 1 byte last screen 1 byte max magic 1 byte magic 4 bytes beam hearts 1 byte beam percent 4 bytes beam power 1 byte hookshot links 1 byte msg_more_x 1 byte msg_more_y 1 byte subscreen 1 byte start_dmap 1 byte link walk style References ---------- ZeldaClassic http://www.zeldaclassic.com/ Public Code That Writes An Unencoded Quest File http://fatcatfan.armageddongames.net/zc/qsu.zip http://fatcatfan.armageddongames.net/zc/qsu210.zip PureZC Wiki http://wiki.purezc.com/ The Legend of Zelda Series Official Site http://www.zelda.com/ Changelog --------- v0.1: November 1, 2005 - initial release GNU Free Documentation License ------------------------------ see http://www.gnu.org/licenses/fdl.html