Application

-table of contents-

About spr2bmp:

I have developed spr2bmp to help people that are trying to make mods for DC.
In past people could only change maps, descriptions, and stats for unit, but now they can also edit graphic, fonts.
Best motivation was very active polish forum DC Forum PL

Credits:
programming language: FreeBasic (FB)
code editor: FB Edit
png library: PNG library
compression library: zlib

-table of contents-

Directories in DC:

animate -> animation descriptions
cursor -> cursors graphic
gamtestat -> stats of buildings, units
intrface -> sprites for menu, fonts
scenario -> missions, MP maps, and tile sets
sound -> sounds
sprites -> sprites for units, special effects

-table of contents-

What helps with decoding?

From game:
2 versions of file with cursors:
curs2.spr -> not compressed
curs.spr -> compressed
searching differences of these two files show you how this compression works
palette.ppm - palette for most files, .ppm file type - can be converted to .bmp using netpbm

Other utilities:
'file reader' -> program for reading raw graphic data, headers and other are not important
spr2bmp -> working converter from .spr to .bmp
some good diff program -> shows differnces between 2 files (diff_my included)
good hex editor, best with searching by strings and hex value, example: ICY Hexplorer.
HDSearchAndStats od Freebyte -> świetne do wyszukiwania plików

-table of contents-

spr2bmp features:

file type - description - result spr -> sprites -> coverts sprites to bmp/png format
bts -> map graphic -> -||-
png -> image/sprite -> creates spt that is compatibile with DC
fin -> animation description -> txt file with description of the animation
map -> map file -> map view, without units and other
Warning! Currently sp2bmp can create .spr files only from .png

-table of contents-

Configuration:

Several functions need know were DC is, localization of game should be placed in 'setup.txt' file, example:
DCpath=D:\games\Dark Colony
You need to remember that palettes must be in the same folder that spr file.

Game files

-table of contents-

--- .spr file ---

aa, 00 are hexadecimals and they mean one byte, numbers/index of bytes are written assuming that firs byte has index 1, in tables often is used indexing started with 0 as first element, so in this case you need to substract 1 from this values.

header:
2 bytes - 01 00 -> normal file - version 1
- 81 00 -> file with compression - version 2
2 bytes - aa bb -> numer of images = bb*256+aa

4 bytes: aa bb cc dd => lenght of compressed data
dd*256^3+cc*256^2+bb*256+aa + numer_of_images*4 = lenght_of_file - position_of_first_byte_with_image_data

768 bytes with an RGB palette (3 * 256)
most of these palettes is to dark, so the best is light them up (if not black)
ex. take one byte -> aa, if aa>0 then aa=aa*4+3

from byte 777 starts data with size of all images:
4 bytes dimensions + 4 bytes displacement
aa bb cc dd + ee ff gg hh
widht = bb * 256 + aa
height = dd * 256 + cc
move_x = 144 - ee //displacement to left
move_y = 104 - gg //displacement to up
it's possible, that these 2 unused bytes also have some pupruse
move_x hav to be calculed in other way, whed image is flliped:
-(width - 32 - move_x)

Now starts differences between compressed and not compressed files.

version 1:
image data starts right after 'size data', so number of bytes to take from .spr is width*height
All images are stored in this way. In game only few files are sored in this way - some text images, and not used graphic.

version 2:
Before each image are 4 bytes, storing lenght of data describing these image.
number of compressed bytes: aa bb cc dd - like main lenght of data:
dd*256^3+cc*256^2+bb*256+aa = number_of_image_data

way to decode:
We take one byte (a):
if a<128 then take next a+1 bytes and put_then into image buffer
else (a>=128) put_to_image_buffer(256-a)black_pixels

Example:
E2 02 42 41 41 -> we decode like this:
E2(226) > 128, put 30 (256-226=30) black pixels into image
02(2) < 128, 3 next bytes (1+2=3) are raw data, so we store them into image

Result:
palette.bmp -> 24bits (RGB) bmp file, size 256x1 with all colors from palette
pal_used.bmp -> similar file, but contains only colors that are used, color that wasn't use are replaced with first color
build.txt -> information about how to decode the original spr file

Description build.txt:
first line -> commentary
second line -> is this spr or bts file
third line -> is compressed ot not (0 - not)
fourth line -> black break line enabled, desribed lower

(z,n - normal colors, c - black)

black break line:

0123456789X

zzzzzccccc

ccccnnnnnn

wihtout break line:

01234567890123456789X

zzzzzcccccccccnnnnnn

These two types are used in DC, remember that DC allows different files to use specific coding type.

-table of contents-

--- .fin file ---

Animation description of units and effects.
These files are large and they havemany unnecessary datas, it's hard to decode some bytes.

Directions of unit movement:

    8
  6 | 10
   \|/
 4--x--12
   /|\
  2 | 14
    0

1 i 2 byte (0 i 1 counting from 0) unrecognized
3 i 4 byte (2 i 3 from 0) amount of 3 type blocks
5 i 6 byte (4 i 5 from 0) amount ot 2 type blocks
7 byte - amount of 1 type blocks
length/amount of 4 type blocks is not written in .fin files (I think so)

Block types:
1: 4 bytes name + 4 bytes space
-> names of used graphic files, often not all files are used + space
2: 16 bytes + 4 bytes some marker
-> animation name + numbers of anim frames -> 2bytes start, 2bytes end of range - it's needed for identyfing anim's when reading 4type block
3: 4 bytes + 8x 20 bytes
-> largest blocks, unrecognized datas :>
4: 22 bytes
-> most interesting, described below

To read animation we need to decode 4 type block so I will describe it:
block type 4 - 22 bytes

               image id-1 -> from file graphic_name.spr
                 |                       is main layer
                 |                       |    is flliped
  graphic_name   V                       V    V
6261727200000000 06 00 E0FF21 0000001000 0100 0100 - first layer, flliped
6261727200000000 07 00 E4FF1F 0000001000 0100 0100 - first layer, flliped
6261727200000000 13 00 61FF1E 0000001000 0100 0000 - first layer
6261727200000000 08 00 61FF1B 0000001000 0100 0000 - first layer
6261727200000000 18 00 61FF1E 0000001000 0100 0000 - first layer
6261727200000000 3B 00 61FF04 0000001000 0500 0000 - second layer
6261727200000000 3E 00 61FF02 0000001000 0500 0000 - second layer
6261727200000000 27 00 61FF1E 0000001000 0100 0000 - firs layer

graphic_name - from what file we nned to get graphic, mostly the same as .fin file, sometimes - special effects it's different

Result:
File that contains description of all animations in .fin file.
Warning! In .fin files are many not used animation descriptions, example BLOOD in reap.spr, they need to be overlooked.

How looks result file:
example:

pozycja: 96

animacja nr: 0, nazwa: REAPSTAND0  

klatki: 0-0



pozycja: 47400

pozycja w bloku 3: 1316

klatka nr: 0, źródło spr: reap.spr

nr obrazka: 1

pozycja -> means byte index, in file
animacja -> animation number, assuming 0 is first,
klatki -> frame number, from 4 block, assuming 0 is first
nr obrazka -> sprite number from .spr file - same as spr2bmp will produce

In case you will get similar data:
nakładka: .spr, nr obrazka: 113 it means that animation info wasn't read correctly, so you need to track the problem manually.

-table of contents-

--- .bts file ---

Map graphic

4 bytes unrecognized
2 bytes (maybe more) -> number of images in file
from byte 9 starts palette - same like in .spr files

from byte 777 starts image data
4 bytes unrecognized (maybe some id) + 1024 bytes of data
all images have size 32x32 = 1024 bytes

Result:
Similar as in .spr files.
Also file 'tile_set.txt' is created, it contains id for all tiles from original bts file.
example:

302 ; 1

305 ; 2

first number is tile id, second is tile number - easier to look.

-table of contents-

--- .map file ---

Maps from DC.

4 bytes width
4 bytes height

block about map squares:
2 bytes -> background
2 bytes -> front sprite
these datas contains block id, from .bts file

After all map squares data, are second packet - info about parameters:
2 bytes -> info
first byte - square is mirror or not, info about height, and is in this square seeing blocked
second bytes - movement bloking and does field have ability to camouflage

1 byte
- mirror: (96, 100) v (223, 228) v (63, 68) v [193]
- mirror only for background: [161] v (159, 163) v (223, 228) v (95, 100) v [32] v [193]
if lower than 128 then seeing is blocked

2 byte
movement block: [2, 14, 18, 30, 6, 54, 42, 50, 90, 58, 78, 82, 46, 66, 62, 70]
camouflage: [49, 77, 89]

Result:
Select the map, then type of unit that will be displayed (currently working TRSC, REAP, BARR) and type of animation that need to be overlook, then select tile set (desert, jungle, special.)
Controls:
arrows -> movement
q -> help lines
w -> rendering type -> normal / special / field attr
d/f/m -> change unit animation death/fire/move
1-9 -> direction of unit movement
Esc -> quit

-table of contents-

--- .scn file ---

Information about teams, then

poz_x
height - poz_y
unit_type -> id from gamestat.txt
team -> 0 red, 1 blue
? -1
? 0

-table of contents-

--- other ---

Palettes.
First color is transparent.

Water animation
color from 201 to 207 (including), ale cycled to make animation.
Example of working water animation in source - map view.

Other

-table of contents-

--- Creating .spr file ---

Choose one spr file, use 'centruj grafike' option (type tak - yes), select png format.
Edit created png files.
Start spr2bmp again, select one from these png files, and thats all. Remember that 'build.txt' and 'palette.bmp' files must exists.
There could be problems with colors, because palettes build in files have for example 3 same colors with different index, so spr2bmp not always use same index as in original file.

-table of contents-

--- Command line ---

In other words parameters that works with spr2bmp. first srting need to be input file name
-p file.bmp -> will use palette from 'file.bmp', only 24bits bmp with size 256x1, works only for spr>>png/bmp
-r -> file will be readed as raw data
example.
spr2bmp reap.spr -p paleta2.bmp
will convert reap.spr to png/bmp, using palette from paleta2.bmp

-table of contents-

--- Working in Linux ---

spr2bmp is written in FreeBasic, a modern free cross-platform basic language.
Most code will work on Linux, but you propably should change slashes, and change belowe definition:
#Define sys_op "win"
'win' -> for 'lin', then compiler will use cross friendly code

by dreamerman :-)