-----------------------------------------------
Jazz Jackrabbit sprite importer\exporter
-----------------------------------------------
---------------
Usage:
---------------
EXPORTER:
-The directory must contain 'pal.000' a sprite file to read from and a tile
file of the same extension. No files will be overwritten; the JAZZ
directory is the best place
-Enter the name of the sprite file you wish to extract sprites from
-Sprites will be exported as 8-bit bitmaps, one per sprite frame; the
sprite structure will be exported as a text file
IMPORTER
-The directory must contain a list(text) file of the correct format and
8-bt bitmap files to be imported as sprites (1 per sprite frame). Files
will be overwritten
-Enter the name of the sprite list you wish to import and the name of one
of your sprite bitmaps; the program will use any bitmaps similar in name to
this. A Jazz compatible spritefile will be created; this shouldn't
overwrite any files present
---------------------------------
Notes:
---------------------------------
You may be confused about the bitmap names exported; the sprites work in an
interesting way; the SPRITES.XXX file and MAINCHAR.000 file are both
combined; there are blank spaces in the SPRITES files that allow the
MAINCHAR sprites to be 'inserted' (And likewise the MAINCHAR contains blank
spaces for the SPRITES sprites.) Therefore, most of the 'entries' in a
sprite file are blank and empty (They should start at about sprite 20-40,
with any others being past 230) THIS IS IMPORTANT! When importing sprites,
be vERY CAREFUL, Starting from sprite 1 will overwrite Jazz's own
animations. (It is best to simply save new sprites with the names of old
bitmaps since the whole setup can be complex.) I cannot stress this enough.
The list file is important; it contains the h and v offsets of all sprites
to be imported. These are used
to control how far right or down a sprite appears compared to the
*previous* sprite. This is because sprites are different heights or widths
and can appear 'jerky' if left to animate by themselves. The tallest or
widest sprite will have a value of 0, with shorter or slimmer sprites
having positive values. To best see how these work, change a value or two
in a list and import. No values can be larger than 255. The list also tells
the program how many sprites to import, this cannot be more than 255 also.
The list is delicate, do not change the spacing and such in it or you will
get big problems. You will be asked for the list file name, this can be
anything.
You will be asked for the sprite bitmap names; the program will take the
first five characters of the name and look for anything containing these;
for simplicity, just use the names of bitmaps the sprite extracter
produces, and type in the name of one of the bitmap files you have in the
directory.
All sprite bitmaps must be divisible by four, if they are not, they will be
adjusted on importing, with extra lines added to the right.
When importing, any files NOT present will be considered marker sprite
files (Just like when things are being exported, who wants all those empty
files cluttering up the place?) However,any sprites in the SPRITES file
will 'overwrite' those in the MAINCHAR file, so if you add 'extra' sprites
where the default Jazz ones are, Jazz's shape will change, ONLY for those
levels using that sprite file!
Sprites are extracted using the palette from a block file of the same
extension as the sprite file. The color 0 cannot be used in a sprite as it
is the transparent color; it is however possible to edit masks so that the
color 0 appears, but this is a lot of hassle for one color, isn't it?
Sprites cannot be bigger than 252*252 or big troubble will occur.
---------------------------------
Sprite format:
---------------------------------
Header size [Two bytes, size of both the h and v offset segments. Also the
number of sprites in the file.]
[The minimum is 231($E7) and the maximum 255($FF) This includes
blank sprites, of which there]
[will be many as 'placekeepers'
]
H offset [(Header size) bytes; one entry for each sprite in the level; this
includes the sprites in ]
[MAINCHAR.000 which will be loaded into the blank sprite spaces in
the SPRITES file. This thus ]
[affects Jazz and his ammo and such. Each byte controls how far
'extra' right a sprite appears ]
[compared to the LAST sprite that has animated. This is used
because sprites can be different ]
[sizes and this makes the movement look smoother. This list can
often be ignored. ]
V offset [(Header size) bytes; one entry for each sprite, same points as
above apply. However this is the]
[vertical location of the sprite. This is because many sprites are
different heights or have ]
['empty' lines. The tallest sprite will ahve a value of 0, and
smaller sprites will have ]
[positive values, moving them down so they don't 'float' in the
air. This list cannot be ignored]
[as quite large values are often needed.
]
-BLANK SPRITES:
$FF $FF [This indicates that the sprite is blank and to move on to the next
sprite. These are common. ]
-UNMASKED SPRITES:
Sprite width [Two bytes, actually width \ 4]
Sprite height [Two bytes]
Image size [Two bytes, sprite is made out of FOUR of these images,
interlaced]
Spacer [Two bytes, almost always zero]
Mask size [Two bytes, $FF $FF to indicate sprite is UNMASKED]
Image 1 [Row 1,5,9... Consists of the sprite divided into 4 images, each
interlaced to provide the]
Image 2 [Row 2,6,10.. full sprite. Transparent color is color 254, color
255 cannot be used. ]
Image 3 [Row 3,7,11.. This is sort of a combined mask and pixel data (See
below) and is actually ]
Image 4 [Row 4,8,12.. more efficient size-wise. I don't know why it is not
used more. ]
-MASKED SPRITES:
Sprite width [Two bytes, actually width \ 4]
Sprite height [Two bytes]
Mask size [Height * width usually, but can be larger (Sprites can
have 'extra' lines)]
Maks data size [2 bytes, size of mask data segment]
Pixel data size [Two bytes, number of masked pixels in sprite mask, the
total pixel data is 4x this ]
Mask data [2 bytes per line of mask; notes the sum of how many
masked pixels are in the mask so ]
[far. The last entry will thus be the same as the Pixel
data size (Total number of ]
[masked pixels.) and the first entry will be pretty low.
JAZZ doesn't read this, but ]
[it is (was0 used by Epic to figure out the h\v offsets.
]
Mask [Image of sprite squashed horizontal 4x. Consists of bytes between $00
and $0F as follows: ]
[Row 1 = 1, row 2 = 2, row 3 = 4 and row 4 = 8;
]
[To display the color of a byte on rows 1 and 3, but not 2 and 4, the
mask byte is 5 (4 + 1) ]
[Thus $00 shows no color and $0F always shows the color (1 + 2 + 4 +
8) ]
Mask color 1 [Row 1,5,9... of pixel data, same size as number of masked
pixels since $00s aren't counted ]
Mask color 2 [Row 2,6,10.. any pixel given $00 as a color is not maksed, in
this way the single mask ]
Mask color 3 [Row 3,7,11.. becomes 4 different masks all mashed together
row after row into one ]
Mask color 4 [Row 4,8,12.. single sprite. Transparent color is color 254.
(255 not allowed.) ]
