Test of Time Sprite File Format
Many thanks to Apolyton's Zarion (DracoOmega) and Angelo Scotto. I would never have been able to decipher the sprite file format without them.
Mercator
STATIC.SPR
The unit images are aligned to the bottom-left corner of the bounding box of the
terrain tile. Since the unit health bar is centered at the top, making the
images taller will move up the health bar.
FILE HEADER
bytes: value
----------------------------------------
HEADER
4 bytes: 0, due to absence of Animations section
4 bytes: 12, offset of Image Offsets section
4 bytes: Offset of Images section
IMAGE OFFSETS
N x 4 bytes: Image offsets relative to start of Images section. The first
image has offset 0. They refer to the 5 facing directions
(N, NE, E, SE, S) of all units. The last offset points to the
end of the file (EOF).
* The order is first all facing directions of the first unit,
then the second unit etc.
* The NW, W and SW facing images are autogenerated by mirroring
the images for NE, E and SE, respectively.
* In a standard ToT game there are 406 offset:
5 directions x 81 units + EOF = 406
* The Test of Time Patch Project (ToTPP) can increase the number
of unit types to 127. The number of sprites used from this file
depends on the @COSMIC2 key NumberOfStaticUnitSprites.
See http://forums.civfanatics.com/showthread.php?t=517282 for
more info about ToTPP.
* What happens if there are fewer offsets than there are units?
IMAGES
bytes: value
----------------------------------------
IMAGE HEADER
16 bytes: 0; no apparent effect
4 bytes: Image width
4 bytes: Image height
4 bytes: Left coordinate of non-empty image bounding box
4 bytes: Top coordinate of non-empty image bounding box
4 bytes: Coordinate of first pixel right of non-empty image bounding box
4 bytes: Coordinate of first pixel below non-empty image bounding box
1 byte : 0xFD, this controls which color is treated as transparent.
This only applies to the pixels actually present in the image
encoding, not the implicit transparent pixels outside the
image's bounding box.
The first 5 bits must be 1. The last 3 bits are in the order
BGR (blue, green, red) and reflect the RGB values of the
transparent color.
For example, if the last 3 bits are 111, the transparent color
is white. If the last 3 bits are 001 the transparent color is
red. The default is 101 which makes the transparent color
magenta. 0xFD is 11111101 in binary.
4 bytes: remaining image size (body + footer)
IMAGE BODY ([Number of rows] - [Number of leading empty rows] rows)
4 bytes: Number of empty bytes (2 bytes per pixel). This is the number
of leading transparent pixels, ignoring the bounding box.
4 bytes: Row data size: N bytes, or N/2 pixels.
N bytes: Row image data. This image data is in 15+1 bit format (in Big
endian byte order that would be: 1-5-5-5). The first (i.e.
highest-order) bit indicates whether the pixel's shade is
changed to the civ color (1) or not (0). The other 15 bits are
5 bits each in the order R-G-B. Transparent pixels are
represented by magenta (Little endian 0x1F7C, or Big endian
0111110000011111) as described in the header.
* Blank lines in the middle of an image are encoded with zeroes
for both row header values.
* Some resources also use the civ color bit. It's not used.
* Existing resources always have a full-size bounding box, so
blank lines are encoded too. This is not necessary to work.
IMAGE FOOTER
10 bytes: 0; no apparent effect
UNITXX.SPR
Unit animations are also aligned to the bottom-left corner of the terrain tile's
bounding box.
Unit numbering follows the order in the Rules.txt, with the first being 00. The
last unit is the barbarian leader. 99 or 999 is the railroad train (see below).
FILE HEADER
bytes: value
----------------------------------------
HEADER
4 bytes: 12, offset of Animations section
4 bytes: Offset of Image Offsets section
4 bytes: Offset of Images section
ANIMATIONS
Animation Header:
32 x 4 bytes: Start offsets of the first frame of each animation:
8 facing directions x 4 actions = 32 animations
The actions are, in order: Attack, Die, Idle, Move. The
directions start at North, continuing clockwise to end at
Northwest. The offsets indicate first all directions of
Attack, then the animations for Die, then Idle and Move.
* The train animation also has its own animation file. This is
usually Unit99.spr. ToTPP changes this to Unit999.spr if the
@COSMIC2 key NumberOfAnimatedUnitSprites is greater than 80.
Since the train's Attack and Die animations are never used
their offsets always point to an empty animation.
* The offsets need not necessarily be in ascending order or even
different. You could let the file contain only one animation,
with all actions and directions using the same one.
Animation Information:
N x 4 bytes: For each animation frame...
(a signed, long integer "bitmasked" into separate values)
1. Index into the list of image offsets, using 10 bits, so
there can be at most 1024 images.
2. .... ..xx (Part of the image index from byte 1)
...x xx.. These 3 bits control transparency:
000 = fully visible
001 ~ 1/8 transparent
010 ~ 2/8 transparent
011 ~ 3/8 transparent
100 ~ 4/8 transparent
101 ~ 5/8 transparent
110 ~ 6/8 transparent
111 ~ 7/8 transparent
(units only)
..1. .... Start of animation
.1.. .... Loop animation (back to start)
1... .... Mirror frame (horizontally)
3. 0x06 unused? 0x00 on unit animation end frames and some
empty resource animations.
4. .... ...1 End of animation (not displayed)
.... ..1. Animate continuously (resources only)
.000 00.. 0; unused
0... .... 0; sign bit; 1 hangs Civ2
* An animation can be effectively turned off by using a dummy
animation with a single frame that is both start and end.
RESOURCES:
The first frame in an animation MUST have the Start flag. The
last frame MUST have either the Loop or End flag. All frames
in a looped animation, and only those frames, MUST have the
Continuous animation flag. Neither the first, nor the last
frame in a non-looping animation are displayed.
Error Handling:
If the first frame doesn't have the Start flag, Civ2 will
first search up to the next End or Loop flag and then search
back to find a Start flag. It will then play that animation.
Animations that end with the End flag, but do have frames with
the Continuous flag will continuously loop only those frames,
and will play the entire animation only occasionally.
In the continuous animation, the non-continuous frames do take
up time, but don't appear, and the animation isn't refreshed
during those gaps (unless the tile has focus) so the last
continuous frame remains visible.
UNITS:
The last frame MUST have either the loop or end flag. Die
animations SHOULD NOT loop, or they'll go on forever.
The first frame doesn't need any flag... There MUST be at
least one frame with the start flag, though, if it's a loop.
In that case it will play the animation once from the first
frame and then loop back to whichever frame has the start flag
(usually also the first frame).
IMAGE OFFSETS
X x 4 bytes: Image offsets (from start of image section), the last one of
these offsets points to the end of the file.
IMAGES
As in Static.spr
RESOURCE.SPR
Resource animations are aligned to the top-left corner of the terrain tile's
bounding box. So making the images taller will cause the bottom to disappear
from view.
The format is the same as for the unit animations, with some minor differences:
ANIMATIONS
Animation Header:
N x 4 bytes: Terrain resource animations in the same order as specified in
the Rules.txt. In a standard ToT game this means there are:
4 maps x 11 terrain types x 2 resources = 88 animations
* ToTPP can extend the number of types to 16 and uses as many
animations as set in the @COSMIC2's NumberOfAnimatedResources.
Animation Information:
Some of the animation frame information is treated differently in the units and
resources. See the UnitXX.spr description above for more details.
Last updated: 26 May 2020