Jazz Jackrabbit Map Format
| Format type | Map/level |
|---|---|
| Map type | 2D tile-based |
| Layer count | Unknown |
| Games |
Levels for Jazz Jackrabbit are stored in LEVELx.yyy files. All files with the same extension make up one world, though this need not be the case.
Each level is divided into seventeen blocks, each controlling something different. Some are Jazz RLE compressed, some are not. Some are total junk that was used by Epic, but is not necessary for the level itself to run. These are as follows:
Block0: Level header (Uncompressed)
This section is 39 bytes long and uncompressed. Only the first three bytes are read, these are always 0x44 0x44 0x1A. The rest of the block was used as the level title by Epic's level editor, but usually reads 'Digital Dimensions Gamepackage'
Block1: Mapping
32768 bytes when uncompressed, this is a Jazz RLE compressed block of 2-byte entries detailing what tiles and events are used in the level. Levels are 128x64 tiles in size and are read left and down. The first byte is the tile, the second the event. In practice the tile values here are from 0-240 (The maximum size of tilesets.) Event values larger than 127 are 'background enabled' that is, any transparent part of a tile they are placed on will be black. (Just the tile they are initially placed on, not any tiles they may move to.)
Block2: Tile transparency
256 bytes long when uncompressed, this is a Jazz RLE compressed block that controls a special part of game memory. There are 256 1-byte entries, one for each possible tile in a tileset. Any tile that is used as a sun tile, or must have Jazz appear behind it needs a value of 1 here. (The two event types that cause this are 'Foreground with transparency' and 'Repel Jazz foreground')
This increases level loading time noticeably when many entries are filled.
Block3: Tile mask
2048 bytes when uncompressed, this is a Jazz RLE compressed block of 8-byte entries that contain the compressed tile masks for a tileset. (This means the same tileset can be masked many different ways in different levels.) Any part of a tile not masked, Jazz will fall through, so most tiles are masked heavily.
Each tile is divided into 4x4 pixel blocks (Each tile thus consists of 8x8 of these.) Each block can have a value of 0 (Empty) or 1 (Solid) Each bit in a tile's entry controls one block, 8 bytes x 8 bits is 64 blocks per tile.
Block4: Special behaviour
8192 bytes when uncompressed, this is a Jazz RLE compressed block of variable size entries that govern how events with the 'Special behavior' type move. An event using 'Special behavior' moves in one of a set of predifined patterns, which is stored here. Each pattern is known as a behavior and can be a varying multiple of 512 bytes in size. (Thus this block can have between 1-16 behaviors in it.)
The 'number' of a behavior pattern is its address in this block divided by 512, thus behavior 0 is at 0, behavior 2 is at 1024. (Note again, behaviors can take up more than 512 bytes of space, this just means that certain behavior segments cannot be used.)
Behavior
Each behavior consists of a word giving the length of the behavior, followed by the behavior itself. Behaviors can be any length, after which the behavior is repeated, but a behavior will use a number of 512 byte blocks.
Behavior data consists of two-byte 'steps' each about 1/128th of a second long, consisting of a pair of 1-byte x and y coordinates for the event to move to at each step. (0,0 is at the top right of the tile that the event is placed on.) Values are in multiples of four pixels.
An event doesn't need to 'loop' and can move as erratically as you want, even leaving the screen entirely. Values are between 0-255, with values greater than 127 being negative. (Signed)
Block5: Event properties
4064 bytes when uncompressed, this is a Jazz RLE compressed block of 32-byte entries that govern the properties of events in a level. Events in Jazz are quite complex, almost everything about them being definable in-level.
There are 127 32-byte entries, from event 0 to event 127. (In the level of course events go from 0-255 as explained above.)
Events
Event format is as follows. (Copied from J1E source)
| Byte offset | Field size (bytes) | Field purpose | Description |
|---|---|---|---|
| 0 | 1 | Difficulty | Difficulty level event first appears in (0-3 = Easy-Turbo.) Event will appear in the level for any difficulty equal to or greater than this. (If it is an event number larger than 127, the black-transparency still appears on any difficulty.) |
| 1 | 1 | Blank | |
| 2 | 1 | Reflect | Obscure, either 0 or 63 often has no effect, but must be 63 in Technoir for the water to reflect Jazz off itself |
| 3 | 1 | Blank | |
| 4 | 1 | Behavior | How sprite moves, there is a big list of the possible hard-coded values you can use, such as 'walk left and right' or 'fall to ground' |
| 5 | 1 | Left | anim Sprite uses this animation when left of Jazz or facing left |
| 6 | 1 | Right | anim Sprite uses this animation when right of Jazz or facing right |
| 7 | 1 | Blank | |
| 8 | 1 | Magnitude | 'Strength of effect'; if a event has some effect on Jazz, this is how strong it is. Values less than 128 are positive (Down, right...) those greater are negative (Up, left...) This is used, for example by springs to push Jazz up (With values like 246.) If an event has no effect, this is usually set to 255 (-1) |
| 9 | 1 | Health | How many shots from Jazz an event can take before being destroyed. (This is increased by 1 in the harder difficulties.) If this is 0 then the event either cannot be shot, or cannot be killed. Note that things like carrots have this set to 0. Anything not 0 makes the event 'flash' when shot |
| 10 | 1 | Type | Event type, enemy, item, time, etc... The two types that affect the game are 'hurt Jazz' (If this has a health above 0 it counts as an enemy point when shot.) and 'item' (Counts as an item point when destroyed.) |
| 11 | 1 | Points | How many points Jazz gets when the event is destroyed (Shot or grabbed.) is this value * 10 |
| 12 | 1 | Attack | What attack the event uses. The first 5 attacks (See later.) are also used by Jazz as his shots, but can still hurt him. Values between 0-31 |
| 13 | 1 | Attack fr | Attack frequency, how often (In 32ths of a second) an event attacks (Shoots) |
| 14 | 1 | Blank | |
| 15 | 1 | Speed | How fast an event moves |
| 16 | 1 | Blank | |
| 17 | 1 | Anim speed | How fast an event animates |
| 18-19 | 2 | Blank | |
| 20 | 1 | Number | Event number, totally useless as far as I can see and can be handled automatically |
| 21 | 1 | Sound | The sound played when this event is 'used' Usually by being shot or grabbed (carrots, orbs) or by Jazz touching it (springs, tubes.) This makes use of the sound list, found in block 9 later on |
| 22 | 1 | Multi 1 | Multi-purpose; usually the value of many different effects, including the x-axis to warp to, destruct replacement tile, and immortality/speed boost duration |
| 23 | 1 | Multi 2 | Used less often than 1 for e.g. Y-axis to warp to and 'bridge sink depth' |
| 24 | 1 | Bridge len | Length of bridge typ events. = length in tiles / 2 |
| 25 | 1 | Medivo len | Length of the Medivo-ball-type event's chain, similar to above. |
| 26 | 1 | Medivo dir | Direction Medivo balls start moving in, in degrees from 12-o-clock |
| 27 | 1 | Blank | |
| 28 | 1 | Death anim | What animation is displayed when an event is destroyed (Shot or grabbed.) |
| 29 | 1 | Death anim2 | Same as above, identical in fact, due to animations needing left and right values, but destruction not really HAVING a left/right |
| 30 | 1 | Attk anim l | Animation used by an event attacking left |
| 31 | 1 | Attk anim r | Animation used by an event attacking right |
Block6: Event names
2032 bytes when uncompressed, this is a Jazz RLE compressed block of 16-byte entries used by Epic's editor to name events. This is not read by the game itself and is often blank. Each entry consists of a byte giving the name length, and 15 bytes of name, padded with nulls.
Block7: Animations
8192 bytes when uncompressed, this is a Jazz RLE compressed block of 64-byte entries that arrange sprite frames into animations to be used by events in the level. A sprite frame can be used as many times as desired.
Animation entries
Animation format as follows: (Copied from J1E help file.)
| Byte offset | Field size (bytes) | Field purpose | Description |
|---|---|---|---|
| 0 | 2 | Spawn x,y | Where, relative to the top left of the tile an event is placed on, a new event (E.g. bullet.) is produced if and when the current event 'shoots' it out. Usually blank except for attack animations like Jazz shooting |
| 2 | 1 | Acc anim | Accessory animation to use. Accessory animations DO animate and count as a place to injure an enemy. |
| 3 | 2 | Acc spanw | Where, relative to the top left of the tile an event is placed on, the accessory animation (E.g. Boss Devan's ship's gun turret.) is located if there is one. Usually blank, but used a lot in boss animations. |
| 5 | 1 | Start y | Where, relative to the top of the tile an event is placed on, the animation starts. (There is no x value for this.) This is because many images are odd sizes. |
| 6 | 1 | Anim num | Number of images in the animation loop, 0-19 |
| 7 | 19 | Anims | Images used in animation loop, the same image can be used more than once, and often is, for example the orbette animation uses the same image six times in a row. If the value 255 (-1) is used, this means 'blank' (0 is an animation, remember.) This is used for things like hidden springs. |
| 26 | 19 | X move | 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 | 19 | Y move | 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 (e.g orbettes use this trick.) |
Block8: Animation names
2048 bytes when uncompressed, this is a Jazz RLE compressed block of 16-byte entries used by Epic's editor to name events. This is not read by the game itself and is often blank. Each entry consists of a byte giving the name length, and 15 bytes of name, padded with nulls. Unlike events, this has 128 entries, not 127.
Block9: Level properties 1 (Uncompressed)
This section is the first uncompressed block after the header and contains numerous lists of things affecting the level. It signals the start of the 'tail' of the level. This controls a lot of things. The format is as follows (Copied from J1E source file.)
| Byte offset | Field size (bytes) | Field purpose | Description |
|---|---|---|---|
| 0 | 144 | Names | 16 entries -> 9-bytes each. Usually blank, names of the level blocks (used when compiling levels.) Same format as previous name lists and make interesting reading. |
| 144 | 9 | Misc | Usually blank, once used to load compressed level blocks |
| 153 | 64 | Snd pitch | 32 sounds -> 2-byte sound entries. 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. Note that the same sound can have MORE than one pitch value, and often does, that most sounds have a 'default' value for this even though they shouldn't really have to (laziness!) and that not all entries need to be filled. |
| 217 | 288 | Snd name | 32 sounds -> 9-byte sound entries. Sound names. Unlike other names, these actually have a function; if the name doesn't match one in the SOUNDS.000 (or SOUNDS.00X where X is the episode Jazz is playing) no sound will play. As such you have only a limited number of options here. This list also gives each sound a number (0-31) that is related to byte 22 of events. Once again the same name CAN be used more than once. The name entries of course follow the usual format established above, but with the total length being 9 bytes instead of 16. |
| 505 | 13 | Music name | Name of the music file played as background music in this level. Can be blank. Follows the usual name format, 1 length byte, 12 name bytes padded with nulls. |
| 519 | 13 | Start nam | Name of level start movie, this file is not actually used anymore. |
| 532 | 13 | End name | Name of level end movie, usually played at the end of a section. Can also be blank if you don't want something played. Usually this is ENDLEVEL.0SC played at the end of level 2 of a world. |
| 558 | 24 | Blank | |
| 583 | 2 | Jazz x | Jazz's start position x |
| 585 | 2 | Jazz y | Jazz's start position y |
| 587 | 1 | Next lev | Next level number (.000 etc) |
| 588 | 1 | Next world | Next world number (LEVEL0, etc) |
| 589 | 2 | Jazz jump | Jazz's jump height, this is negative (up) and is the height in tiles divided by two. Default is $FFF5 (5 tiles) |
| 591 | 2 | ??? | Unknown, varies between levels, an always negative value that is probably some sort of level, like that water that follows it. |
| 594 | 2 | Water | Water height, in pixels from level top. If it is too low (the value is too high, usually above $07D0) then the level may look odd at the start (the sky will be multicoloured; see block 14.) If the water level is below the level bottom, water related events will not work. |
| 595 | 1 | Jazz an sp | How fast Jazz animates (Default is 119) |
| 596 | 2 | ??? | Unknown, always $01 $1E |
Block10: Jazz animation list
Usually 352 bytes, but can be longer, a Jazz RLE compressed list of animations Jazz uses in the level. Usually pretty standard except in special levels like Birdland. The first 19 are used often, the next 25 are mostly tutlettes but have some use.
Each entry consists of two two-byte values, on for facing left, the other for facing right. (Notably no value is above $00FF...) The important ones are as follows:
01.) J Walk 02.) J Jump 03.) J Airspin 04.) J Shoot 05.) J Duck 06.) J Fall 07.) J Hurt 08.) J Lean on wall 09.) J Hover 10.) J Stand 11.) J Bored 12.) J Balance on edge 13.) J Look u/d' 14.) J Swim 15.) J Run 16.) J Die on hoverboard 17.) J Sucked 18.) J Stop 19.) J Spring up .... .... .. .
'First value is look up, second is look down
Block11: 'Debris animation list' (Uncompressed)
The smallest block, 4 bytes of uncompressed data controling the animations used by... stuff. There are 4 entries, each one byte long. These are animations for 'derbis' type phenomena. For example, the first is the invincibility sparkles that surround Jazz. The second is the 'Devan head' that appears in boss fights (In normal levels it is $09, bosses $7E) The last two are some sort of explosions (Unknown)
Be aware that these are handled special, a RANDOM image from the selected animation is picked and animated. If you change it to animation that doesn't have a large enough number of images then ones from the next (And the next!) animation will be used as well. This can look... messy.
The values are almost always the same in every level.
Block12: Attacks
640 bytes when uncompressed, this is a Jazz RLE compressed block of 20-byte entries that control a level's 'attacks' These are what happens when Jazz or an event shoots.
'Attacks' spawn another event from an existing one. Usually this means shooting and what is formed are bullets. This block deals with how these events behave for EVERYTHING, Jazz, enemies, the bird...
Jazz uses the first four attacks (Blaster, etc; the TNT attack is different and can be used no matter what.) The bird uses the last one (31) The 'unknown weapon' is attack 4 and most enemies use one or two optional ones.
Note that attacks can also be things like bubbles or fragments, they are most ingeniously used. Indeed, even enemies can be spawned here. (Deserto)
Note also that TWO shots are produced (RF missile) in each attack, usually with one being null, so everything is a bit doubled up.
Attack entries
| Byte offset | Field size (bytes) | Field purpose | Description |
|---|---|---|---|
| 0 | 2 | Sprite 1 | Sprites to use for attack 1 when facing l/r (For spawn event this is the EVENT number to spawn.) |
| 2 | 2 | Sprite 2 | Same as above, for the second attack (E.g. RF missiles) |
| 4 | 2 | Speed x 1 | Speed l/r for first attack (Blaster speed = 1) |
| 6 | 2 | Speed x 2 | Same as above,for second attack |
| 8 | 2 | Speed y 1 | Speed up/down for attack 1 (RF missile y speed = 2) |
| 10 | 2 | Speed y 2 | Same as above, for second attack |
| 12 | 2 | Gravity 1 | How strongly an attack feels gravity; this makes it fall faster and faster the longer it's active. (Launcher) unlike y speed which is constant. Note that just like previous values, the left and right attacks have different values. Note that this value is only useful if the attack is of type 2-4 (see below for attack types.) Note also that if this is 4 or higher the attack becomes a spawned event (e.g the lizard generator in Deserto.) |
| 14 | 2 | Gravity 2 | Same, for second attack |
| 16 | 1 | Death anim | What animation the attack shows when it is destroyed (Hits stuff or is shot) |
| 17 | 1 | Death snd | What sound the attack makes when it is destroyed |
| 18 | 1 | Type | Attack type, 0: Normal 1: Shoot l/r at same time (A max of FOUR shots at once can appear if this is used with RF missile type attacks.) 2,3: Fall under gravity and smash, 4: Launcher (Fall and bounce) |
| 19 | 1 | Start snd | Sound made when the attack appears (the shooting sound) |
Block13: Attack names
672 bytes when uncompressed, this is a Jazz RLE compressed block of 32-byte entries that name each attack. Again this is not used by Jazz, but was by Epic, and follows the usual format for name lists. (1-byte length, 31 bytes name, padded with nulls.)
Block14: Level properties 2 (Uncompressed)
This is another complex and uncompressed block, 25 bytes long, controlling a number of complex and hard to explain phenomena.
| Byte offset | Field size (bytes) | Field purpose | Description |
|---|---|---|---|
| 0 | 1 | Background mode | How the sky looks; value between 0-15. This affects three things, firstly the sky (is it seen [Transparent] or is it grey?), water colour (what colour is it? Does it get darker as Jazz sinks? Can it even be seen?) and 'movement sensitive palette' (the tiles that colour animate as Jazz moves up and down in a level; if these are stalled you have 112 extra colors usable for tiles.) |
| 1 | 1 | Sun? | Do we use a sun tile? $01 = yes |
| 2 | 1 | Sun tile | Sun tile, this and next 3 tiles is used. |
| 3 | 11 | Jazz snd | Sounds used by level and Jazz |
| 13 | 11 | Anims | Jazz accessory animation list, 21 1-byte entries. |
Background modes
| # | Sky visible? | Black backgrounds? | Water colour? | Parallaxing? |
|---|---|---|---|---|
| 0 | No | No | Invisible | Looks odd |
| 1 | No | Yes | Invisible | No |
| 2 | Yes (Normal) | Yes | Invisible | Yes |
| 3 | Yes (Odd start) | Yes | Dark green | Green-yellowish |
| 4 | Yes (Odd start) | Yes | Green | Green tinge |
| 5 | Yes (Odd start) | Yes | Dark purple | Purple tinge |
| 6 | Yes (Odd start) | Yes | Purple | Pink tinge |
| 7 | Yes (Odd start) | Yes | Yellow | Yellow tinge |
| 8 | No | No | Invisible | Yes |
| 9 | No | Yes | Invisible | Yes |
| 10 | Yes (Odd start) | Yes | Invisible | Yes |
| 11 | Yes (Odd start) | Yes | Lagunicus blue | Green-yellowish |
| 12 | Yes (Odd start) | Yes | Lag Green | Green tinge |
| 13 | Yes (Odd start) | Yes | Lag purple | Purple tinge |
| 14 | Yes (Odd start) | Yes | Lag pink | Pink tinge |
| 15 | Yes (Odd start) | Yes | Lag yellow | Yellow tinge |
Level sounds
01.) Nothing 02.) Jazz jump 03.) Jazz hurt 04.) Jazz bored 05.) Bored??? 06.) Nothing??? 07.) Levend count 08.) Level done 09.) Nothing??? 10.) J lose bird 11.) Uploop?
Level animations
01.) Nothing 02.) Nothing 03.) Nothing 04.) 4 shield gem 05.) Hoverboard l 06.) Hoverboard r 07.) Bird l 08.) Bird r 09.) ??? 10.) Nippious' 11.) 1 shield gem
' If this value is 1, Jazz shivers and slides (Icy) if 2 or above he shivers but doesn't slide, 0 is a normal level.
Block15: Editor data
32 bytes when uncompressed, this is a Jazz RLE compressed block of 16 2-byte entries used to load the level blocks in Epic's editor. Now not used by the game, this is usually blank.
Block16: Level properties 3 (Uncompressed)
The final block in the level, 17 bytes in length though sometimes with added nonsense tacked on the end. Mostly used for the game's checksums. format as follows:
| Byte offset | Field size (bytes) | Field purpose | Description |
|---|---|---|---|
| 0 | 3 | Blank | |
| 3 | 1 | World check | World checksum. Start with the value 208 + (World number); if [(world number) \ 2] is even then we add 2, if it is odd, we subtract 2. The value for 0,1,2... is thus 210,211,208,209,214... |
| 4 | 1 | Level check | Level checksum. If INT[(level extension) \ 4] is even, then this is [(level extension) + 4] if it is odd then this is [(level extension) - 4]. This creates a pattern of ++++----++++... |
| 5 | 2 | Easy en | Number of enemies needed to be shot on easy/med for 100%, Epic calculated this by counting every 'hurt' type event on easy that could be shot, sometimes causing an error since not all hurt events were destructable. |
| 7 | 2 | Hard en | Same as above but for the hard difficulty; should be equal or larger to the previous value, and calculated in a similar way |
| 9 | 2 | Turbo en | Same as above |
| 11 | 2 | Items | Items to get to get 100% at level end; since items aren't supposed to increase in number with difficulty as enemies do, this is for all difficulties |
| 13 | 1 | Block len | Length of block extension, should of course be $03 |
| 14 | 3 | Block | Block file to use is BLOCKS.XXX where the numbers here are in plain text (e.g '032'.) The most common string is '999' meaning 'the same as the level ending' but you will notice say, boss levels, are forced to use the block number specifically. |
External Links
- JCS'94 is a level editor
- [1] J1E is the best Jazz level editor, able to alter almost all aspects of a level
- [2] JJ1MOD is a beta program for editing most of the Jazz graphics including sprites and tiles when making new levels
Credits
This file format was deciphered from the source of OpenJazz, elaborated by Levellord and fully deciphered by NewSpaz and 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!)