Jazz Jackrabbit Bonusmap Format
|
This article is partially complete. This means that all known information is here, but there is still more information that needs to be discovered and/or reverse engineered. If you know some of the missing information, you can help the ModdingWiki by adding this info yourself. |
| Format type | Map/level |
|---|---|
| Map type | 2D tile-based |
| Layer count | 1 |
| Tile size (pixels) | 256×256 |
| Viewport (pixels) | 320×200 |
| Games |
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
Uncompressed.
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.
Animations
| 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 |
Credits
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!)