Jazz Jackrabbit Bonusmap Format

From ModdingWiki
Jump to: navigation, search
Jazz Jackrabbit Bonusmap Format
There is no image of a map in this format — upload one!
Format typeMap/level
Map type2D tile-based
Layer count1
Tile size (pixels)256×256
Viewport (pixels)320×200

Bonusmaps for Jazz Jackrabbit are stored in BONUSMAP.xxx files. Bonusmaps are 256x256 tiles wide/high, and wrap around the edge. If a road leads to the end of the map, the player is sent to the other end of the map. (Though under some conditions the game will freeze and crash.)

File format

The level consists of several blocks, both compressed and uncompressed. Compression is Jazz Jackrabbit RLE compression. The level blocks are as follows:

Block 0: Level header


This looks important, but contains a lot of useless stuff It is basically a list of 14 things used in the level. Each entry consists of a length byte, and x name bytes. All entries are are 9 bytes long, except for the last two, which are 13 bytes long, making the header a total length of 134 bytes The first 12 entries were used when compiling the bonus level by Epic and are useless. Entry 13 is the tileset (The extension, usually .LBM is ignored, but must be included.) to be used by the level and entry 14 is the background music (Including extension.) played in the level.

Block 1: Animation sequences

Uncompressed. (Starts at offset 134.)

This controls the animations in a level. A level is presented with 256 sprites (51 containing data) in an 'array' from the BONUS.000 file. These are then used in 32 64-byte animation sequences for the level, making this section 2048 bytes long.

Many animations are nonetheless empty (containing 1 frame of value 0.) Bonus sprites are warped to appear 3D.


Byte offset Purpose
1-2 Spawn x,y position. Not used.
3 Accessory animation. Not used.
4-5 Accessory x,y position. Not used.
6 Blank
7 Frames in animation loop
8-26 Sprites to use; max of 19
27-45 The movement, in pixels, horizontally of EACH INDIVIDUAL image in the animation loop. This allows images of different widths to move smoothly, or for the same image to move about as if it was several.
45-64 The movement, in pixels, vertically of EACH INDIVIDUAL image in the animation loop. This allows images of different heights to move smoothly, or for the same image to move about as if it was several.

Block 2: Animation names

Uncompressed. (Starts at offset 2182)

The names of the animations above. 32, 16 byte entries for a total length of 512 bytes. These are not used by the game and are identical in format to the strings in the level header. (Length byte and name padded with nulls.)

Block 3: Tile mapping

(Starts at offset 2694) The first compressed block in the level. Bonus levels are even larger than normal levels, 256x256 tiles, for a total uncompressed length of 65'536 bytes (1 byte per tile.) The level is stored column by column, rather than by row.

Block 4: Event properties

16 16-byte entries, one for each possible event in the level. This controls everything about an event.

Byte offset Purpose
1-5 Obscure and apparently unused
6 Animation sequence used
7 Blank?
8 Event type (1, time, 2, gem, 5, pole-bounce 7, exit, 8, hand-bounce)
9 Unknown, either 0 or 1
10 Unknown, is 3 for all useful events
11-14 Blank
15 Sound played when event hit (If any)
16 Blank

By default the standard events are 0, ignored, 1, time, 2, gem, 3, bounce-back, 4, hand, 5, exit 6, pole.

Block 5: Event mapping

Unlike normal levels, events and tile mapping are separate. (Because combined they are larger than $FFFF) This is identical to the tile mapping block, but values here define what even is placed on the level.

Block 6: Level properties

Uncompressed. This controls the properties of the level.

Byte offset Purpose
1-32 16 sound's pitches, one for each sound in the level. Each of these entries is for a sound in the level, and defines how much a sound is squashed (Shortened and raised in pitch.) This lets Jazz use a single sound like several. For example the sound GODLIKE is used for the 'got item' and 'got shield' sounds, the only difference being this value.
33-176 16 sound names, 1 for each sound in the level, consisting of a name length byte and a sound name, as in the header.
177 Word, $FFFF; if this value is otherwise Jazz immediately wins the bonus level and exits
179 Word giving the time Jazz has in the level, in seconds. Max is 9:59 (599 seconds.) Anything above this results in the level displaying characters (E.g. A:59 for 11 minutes.)
181 Word giving the number of gems Jazz must get, only the first two digits are displayed in-level (250 is thus '25')
183 Word, Jazz start y position
185 Word, Jazz start x position
187 12 blank spaces needed to pad the footer to 198 bytes


This file format was reverse engineered by Levellass. If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)