GRFCodec Documentation

These programs are distributed according to the terms of the GNU General Public License, Version 2. For more information read the file "COPYING".

The following three programs are part of GRFCODEC:

GRFCodec: Convert a GRF into an editable PCX file and vice versa
GRFDiff: Compare two GRF files for differences, and write only the differences to a GRD file
GRFMerge: Take a GRD file and merge it back into the GRF file

GRFCODEC

GRFCodec takes a TTD .grf file and converts it to PCX, or vice versa. To use it,

Copy it into your TTD directory
to decode a GRF file:

grfcodec -d <grf-file>

This will put a pcx file in a subdirectory called "SPRITES". It will also make a .NFO file that is needed to reconstruct the GRF file.
to encode a GRF file:

grfcodec -e <grf-file>

It will look in the sprites directory for both the PCX and the NFO file and make a GRF file out of this.

Options

When decoding:

-w <width>: To set the width of the PCX file
-h <height>: To set the maximum height of a PCX file. With this option, each GRF will be split into several PCX files.
Note that both width and height should be large enough to accomodate the largest sprite in your GRF file, or you will get strange results.
-b <boxsize>: GRFCodec organizes the sprites in boxes in the PCX file. Use this option to choose the minimum size of these boxes.
-p <palfile>: Choose a differenct colour palette for the PCX file, for example when decoding TT Original or TT+World Builder graphics. See -p ? for a list of possible values.
-m <mapping>: Map the colour palette from one type to another, for example to convert DOS GRF files to the Windows version or vice versa. See -m ? for a list of possible values.

Examples:

grfcodec -d trg1.grf grfcodec -d -w 800 -h 600 trg1.grf grfcodec -d -p 6 mars.grf

When encoding:

-u: To disable redundancy compression. This speeds up the encoding process, but it also greatly increases the size of the resulting .GRF file, and may reduce performance in TTD because it can only cache fewer sprites.
-m <mapping>: Map the colour palette from one type to another (see decoding above)

Examples:

grfcodec -e trg1.grf grfcodec -u -e trg1.grf grfcodec -m 1 trg1.grf

What you can edit

You can change all the sprites in the PCX file. Note that the colour 0 (black) is the transparent colour. Any changes to the white background around the sprites will be ignored.

It is possible to change the size of a sprite, but it is non-trivial. You have to edit the .NFO file -- even though it says "do not edit". For every sprite there's a line in the following format:

<pcx filename> <x> <y> <type> <y-size> <x-size> <x-ofs> <y-ofs>

In case you change anything, there are two things you must must MUST make sure, which is that:

The sprites remain in the correct order
Do not delete lines or rearrange them, in particular do not delete or modify the strange block with a "*" as filename. These are special data that aren't sprites but go in the GRF file nonetheless.

The sizes are given in regular decimal notation. You need to change these. Of course, you also have to make room for them in the PCX file. Therefore, the best way to enlarge a sprite is to:

Decode the GRF file
Edit the NFO file, change the size
Encode the GRF file, even though you haven't edited anything in the PCX file
Decode it again
Edit the PCX file
Encode it again

Steps 3 and 4 are there to ensure proper spacing in the PCX file.

GRFDIFF

Usage: grfdiff [options] Old-GRF-File New-GRF-File

GRFDiff compares a backup of your .grf file with the new .grf file, and writes a .grd which contains the changed sprites.

Since GRFCodec makes a backup of your GRF file the first time it is changed, you would normally run GRFDiff like this:

grfdiff trg1.bak trg1.grf

This will generate the file trg1.grd, which contains only the sprites which are new in trg1.grf.

Options

-l <numbers>: Instead of searching for the sprites which are new, you can specify the numbers here, using a format like
-l 1-10,50,100-120
Note that the numbers must be in increasing order. If -l is specified, you can omit the Old-GRF-File name.
-n: Instead of making the GRD file, only show which sprites are new.
-o <filename>: Instead of making a GRD file of the same name, write to this file.
-x: Make a self-extracting .exe file. Simply running that file will automatically integrate the changes into the right .GRF file. This self-extracting file is actually a copy of GRFMerge.
-y: Answer 'Y' to all questions.

You can also combine the differences between several sets of GRF files into one GRD file (or one self-extracting .EXE) by adding more files on the command line, separated by a plus. Example:

grfdiff file1.bak file1.grf + file2.bak file2.grf + file3.bak file3.grf

This compares the three sets of GRF files and writes the differences of all sets into file1.grd. When giving several sets of files like this, only option -l can be specified multiple times, all other options must be given for the first set:

grfdiff -x -o many.exe file1.bak file1.grf + -l 10-15 file2.grf + -l 23 file3.grf

This can be useful when making diffs that should work for the DOS or the Window version, because GRFMerge will just skip the files it can't find. For example,

grfdiff -x -o bothver.exe trg1.bak trg1.grf + trg1r.bak trg1r.grf

will add the differences in both the DOS and Windows versions of the main TTD sprite file to bothver.exe. When run, bothver.exe will patch both files if they are present, or otherwise just patch the one that exists.

GRFMERGE

Usage: grfmerge GRD-File [GRF-File]

GRFMerge takes a GRD file and integrates the new sprites into the GRF file. If no GRF file is specified, it uses the one which the GRD file was made from.

Options

-l: Do not integrate the sprites, only show which ones are contained in the GRD file
-y: Answer 'Y' to all questions.

If called as a self-extracting file (made by grfdiff -x), the GRD file cannot be specified, it is always built into the .exe file. The GRF and all options can still be specified though. You can also specify a self-extracting file instead of the GRD-File, though that is perhaps a bit redundant.
Copyright © 1999-2005 by Josef Drexler.

Last changed on Apr 17 2005 13:03 EDT by Josef Drexler