Jazz Jackrabbit Map Format

From ModdingWiki
Jump to navigation Jump to search
Jazz Jackrabbit Map Format
There is no image of a map in this format — upload one!
Format typeMap/level
Map type2D tile-based
Layer countUnknown

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.)


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.)


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


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!)