
How to define new graphics
==========================

The new graphics are controlled by newgrf.cfg (newgrfw.cfg for Windows),
which is simply a list of .grf files to include.  Each .grf file can
then define graphics for one or more vehicles.

In this document, you can find out how to define new sprites and
control how they are displayed.

Table of Contents

1)  Introduction to Pseudo-Sprites
2)  Definition of pseudo-sprites
3)  Pseudo-sprite actions
4)  General information and hints and tips



1) Introduction to Pseudo-Sprites
---------------------------------

Pseudo-Sprites are special entries in the .nfo file that corresponds to
a .grf file when decoded by GRFCodec.  They are the entries that do not
have an actual picture in a PCX file, and they start with an asterisk,
instead of the PCX file name.

This is what a regular sprite looks like:
    7 SPRITES\newship.pcx 162 200 09 46 72 -6 -7

This is what a pseudo-sprite looks like:
  125 * 17	 02 02 01 02 04 00 00 01 00 02 00 06 00 07 00 08 00

In each line, the first number is the sprite number.  It must increase
in consecutive integer numbers, starting from 0 for the first entry.

For regular sprites, the next part of the line is the PCX file name,
and the dimensions and offsets of the sprite.

For pseudo-sprites, the entry after the asterisk is the total length
of the pseudo-sprite data, in bytes.  After it follows the actual data,
also in individual bytes.  Note that the length must be given in decimal
notation, but the data is given in hexadecimal notation.

Pseudo-sprites exist in TTD's .grf files too, but their format is
unknown.  In a .grf file used by TTDPatch, however, the format is
described in the next section.  For example, you will find that the
example pseudo-sprite above means to TTDPatch:
	- this is the definition of a cargo ID for ships
	- it defines cargo ID number 1
	- there are two different sets of sprites for ships that are in motion
	- there are four different sets for ships being loaded or unloaded
	- after which follow the numbers of the sprite sets


2)  Definition of pseudo-sprites
--------------------------------

Each pseudo-sprite that is read by TTDPatch has the following format:

<sprite-num> *   <length> <data>

	sprite-num	The consecutive number of the sprite (see above)
	length		Total size of the pseudo-sprite, including the
			action byte and all data bytes
	data		The first byte of this is the so-called "action"
			that decides how this particular sprite is to be
			interpreted, and what it does


The following actions can be specified:

      Action	What it does
	0	Change vehicle info (like TTD Alter)
	1	Define new sprite block
	2	Define new cargo ID: mapping of cargo type and load status to sprite
	3	Define vehicle to cargo ID mapping
	4	Define new vehicle names
	5	New graphics such as pre-signals and overhead wires
	6	Apply newgrf.cfg parameter to following sprite data
	7	Skip following sprites if condition is true
	8	Define the GRF ID, description and copyright info
	9	Skip following sprites even during initialization
	A	Replace arbitrary TTD sprites


The format of the data of each action is different depending on the action,
and is described below.

These descriptions of the parameters are organized in this manner:

	Size  Name  Description

The size can have the following values:
	B	This parameter is a single byte
	W	This parameter is a two-byte word, specified in little-endian
		byte order, that is, low-byte first, followed by the high-byte
	D	This parameter is a four-byte dword, again in little-endian
		byte order, with the least significant byte first and the
		most significant byte last.
	S	This parameter is variable-length, zero terminated text string
	V	This parameter has a variable length, which depends on one
		of the previous parameters; it will be described there.


Each sprite in the .grf file is such a pseudo-sprite, except for the
graphics sprites preceeded by actions 1 or 5.

The first (pseudo-)sprite has a special format.  It defines how many entries
the .grf file contains in total.  TTDPatch needs to know that, because it
needs to reserve memory for each sprite in the file.

This is the format of the first sprite:

	*   4  <num-entries>

	D num-entries	The total number of sprites and pseudo-sprite
			in this .grf file.  May be slightly larger than
			the actual number, but must not be smaller.

If you give a number that's too large, you're wasting memory that may
be needed for actual sprites, and if the number is too low, the last
few sprites will have to be skipped, which may confuse TTDPatch.


3)  Pseudo-sprite actions
-------------------------


Action 0:	Define new vehicle properties.
~~~~~~~~~

May appear anywhere in the .grf file.

Data is <00> <veh-type> <num-props> <num-info> <offset>
then repeated numprops times: <property> <new-info>

	B veh-type	0, 1, 2 or 3 for trains, road vehicles, ships or planes
	B num-props	how many properties to change
	B num-info	how many vehicles to change
	B offset	offset into each property (i.e. how many vehicles
			to skip before the first one to change)
	B property	what property to change, depends on the veh. type
	V new-info	new bytes of info (variable size)

	Properties common to all vehicle types
	number	size	property
	00	W	date of introduction
	02	B	how fast reliability decays without maint initially
	03	B	vehicle life in years
	04	B	model life in years
	06	B	climates available (bit mask)
	07	B	load amount (amount of cargo transferred per unit
			of time if using gradualloading)

All of the above only apply to new games, or when using Cht: ReloadEngines.

The date is specified as number of days since 1920.  It will have a random
number from 0 to 511 days added to it at the start of every new game, or after
using "Cht: ResetVehicles".  Note that TTD stops updating vehicle type data
after the game ends in 2050, so all dates of introduction should be no later
than in 2044, to ensure that all vehicle types can be introduced and reach
their maximum reliability.

The reliability decay speed is used when a new vehicle is bought, and
specifies how quickly the reliability decays after servicing.  The initial
TTD default for all vehicles is 20.  If a vehicle goes without servicing
for a long time, or if it gets very, very old, this number increases,
meaning faster decay and more breakdowns.  Larger numbers mean faster decay,
smaller number slower decay.  If set to 0, reliability never decreases
in normal operation.

Vehicle life is the life of a vehicle before it needs to be replaced.

Model life determines how long this model is available for sale (without
using persisentengines).  Usually this shoule be at least twice or three
times as  long as the vehicle life.  When starting a new game, a random
amount between 31 months and 17 years is added to this as well.

	Properties for trains
	05	B	track type (0=railroad, 1=monorail, 2=maglev)
	08	B	AI special flag: set to 1 if engine is 'optimized' for
			passenger service (AI won't use it for other cargo),
			0 otherwise
	09	W	Speed in mph*1.6 (0 for wagons)
	0B	W	Power (0 for wagons)
	0D	B	Running cost factor (0 for wagons)
	0E	D	Running cost base; for engines either 4C30 (steam),
			4C36 (diesel) or 4C3C (electric); 0 for wagons
	12	B	Sprite ID (FD for new graphics)
	13	B	Dual-headed flag; 1 if dual-headed engine, 0 otherwise
	14	B	Cargo capacity
	15	B	Cargo type
	16	B	Weight in tons
	17	B	Cost factor
	18	B	Engine rank for the AI
			(AI selects the highest-rank engine of those it can buy)
	19	B	Steam/smoke/sparks type and sound effect for new graphics;
			00..07=steam, 08..27=diesel, 28..31=electric,
			32..37=monorail, 38..41=maglev; default if unset is steam
	1A	B	Not a property, but an action: sort the current train
			vehicle before train vehicle with the specified number
			Use this when converting waggons to engines or vice versa
	21	B	Make vehicle shorter by this amount (e.g. for tenders)
			00=not shorter, 01=shorter by 12.5%, up to 07=shorter by 87.5%
			Does not work for the first vehicle in a consist (i.e. the engine)


	Properties for road vehicles
	08	B	Speed in mph*3.2
	09	B	Running cost factor
	0A	D	Running cost base
	0E	B	Sprite ID (FF for new graphics)
	0F	B	Capacity
	10	B	Cargo type
	11	B	Cost factor
	12	B	Sound effect: 17/19/1A for regular, 3C/3E for toyland
	13	B	Power in 10 hp (only used with rvpower)
	14	B	Weight in 1/4 tons (only used with rvpower)
	15	B	Speed in mph*0.8 (up to 511 km/h, only used with rvpower;
			uses prop.08 if unset; always set prop. 08 too)
	16	D	Bit mask of cargo types available for refitting
			(not refittable if 0 or unset)


	Properties for ships
	08	B	Sprite
	09	B	Refittable (0 no, 1 yes)
	0A	B	Cost factor
	0B	B	Speed in mph*3.2
	0C	B	Default cargo type
	0D	W	Capacity
	0F	B	Running cost factor
	10	B	Sound effect type (4=cargo ship, 5=passenger ship)
	11	D	Bit mask of cargo types available for refitting


	Properties for aircraft
	08	B	Sprite
	09	B	Is helicopter? 2=no, 0=yes
	0A	B	Is large? 0=no, 1=yes (=can't safely land on small airports)
	0B	B	Cost factor
	0C	B	Speed in mph*8
	0D	B	Acceleration
	0E	B	Running cost factor
	0F	W	Passenger capacity
	11	B	Mail capacity
	12	B	Sound effect (not for helicopter); 6=prop 1, 7=jet 1,
			3b=supersonic, 3d=jet 2, 45=prop 2, 46=jet 3


Note:
	- Trains use FD for new sprite graphics, all other vehicle types
	  use FF.
	- Vehicle costs and running costs are all determined by a factor
	  only, which is then multiplied with a base value that is the
	  same for all vehicles of that type (except trains, where you
	  have a choice of three base values)
	- Don't use property numbers that aren't defined here

You can define several new properties for many vehicles using a single
action 0 entry.  For example, the following entry:

* 180	00 02 0A 0B 00
   00	6A 0B	9A 55	90 08	BC 5C	69 43	7B 44	30 4A	23 07	11 39	56 47	EC 3B
   06	07	07	0F	0F	0F	06	03	0F	07	0F	07
   08	FF	FF	04	FF	06	FF	FF	FF	FF	FF	FF
   09	00	00	01	00	00	01	00	01	01	01	01
   0A	9E	BE	60	FF	94	B4	AF	6E	A0	D2	AA
   0F	96	82	5A	FF	BE	BE	B4	A5	A0	78	AA
   0B	45	52	49	6C	E0	55	4D	45	4A	52	4A
   0C	03	03	00	00	00	0B	04	05	06	05	07
   0D	2C 01	C2 01	64 00	F4 01	64 00	18 01	68 01	BE 00	68 01	C2 01	68 01
   11	08 00 00 00
	08 00 00 00
	05 00 00 00
	01 00 00 00
	01 00 00 00
	00 30 20 04
	10 00 00 00
	F6 7F BF FF
	42 41 00 00
	20 30 20 04
	80 0A 01 00

sets all properties for all of the ships at once.  If you can, combine as
many action 0 entries as possible, to save some memory that would otherwise
be wasted.


Action 1:	Define new vehicle sprite blocks.
~~~~~~~~~

May appear anywhere in the .grf file.

Data is <01> <veh-type> <num-sprites> <num-dirs>

	B veh-type	same as action 0
	B num-sprites	number of sets of num-dirs sprites
	B num-dirs	how many different vehicle directions in each sprite set
			Set num-dirs=8, unless your sprites are symmetric.
			In that case, use num-dirs=4.

The following num-sprites times num-dirs sprites will be actual sprites,
not pseudo-sprites.  The first num-dirs sprites will be sprite set 0, the
next num-dirs sprites will be sprite set 1, and so on up to sprite set
number num-sprites - 1.


Action 2:	Define cargo IDs or randomized/variational cargo ID lists
~~~~~~~~~

May appear only *after* the sprite block (action 1) it corresponds
to.  It always refers to the most recent sprite block.

Data is <02> <veh-type> <cargo-id> <num-loadtypes> <num-loadingtypes> <loadtypes...>

	B veh-type	see action 0
	B cargo-id	ID of this particular definition, must be unique
			for each sprite set
	B num-loadtypes	bits 0-6: how many different states of load this set
			can display, while the vehicle is in motion
			bit 7: if set, this is not a cargo ID but a randomized
			or variational cargo ID list (see below)
	B num-loadingtypes
			same as num-loadtypes but shown while vehicle is
			either loading or unloading
	W loadtypes...	sprite ids for each of the states of load; first for the
			"in motion" load states and then the "loading/unloading"
			load states

A cargo ID defines a super-set of sprite sets that go together to display
a certain cargo type, at various states of motion or loading.  For example,
for a certain vehicle, you might have one cargo ID for coal, one for iron
ore and one for grain.  Several cargo IDs can share sprites, for example
the empty sprite might be the same for several cargo types.

Both the num-loadtypes and num-loadingtypes must not be zero, or a division
by zero may occur.

If there is only one load type, it is shown for all loads
If there are two load types, the first is shown below 50%, the other above 50%
If there are three load types, they are shown above/below 33% and 66%
If there are four load types, they are shown above/below 25%, 50% and 75%
etc...

Note that you cannot skip the definition of a cargo ID using action 7 or 9.
If you try to do that, it will not work they way you would expect.  The best
way is to skip an action 3 conditionally, instead of using action 7 to select
between several definitions of a single cargo ID number.


Randomized and variational cargo ID lists:

If num-loadtyoes has bit 7 set, the action is interpreted differently,
depending on the value of num-loadtypes.

In that case, it specifies a list of cargo IDs instead, providing an
intermediate step in the sprite determination.  Such a definition can itself
specify randomized or variational cargo IDs, and the chain is followed until
a regular cargo ID (def-type 00) is reached.  Note that the cargo IDs a
randomized or variational definition refers to must have been defined before
that definition, i.e. you can't refer to cargo IDs before they have been
defined.


For num-loadtypes 80:	list of randomized cargo IDs

Data is <02> <veh-type> <cargo-id> <80/83> <random-type> <nrand> <randbit> <cargo-IDs...>

	B veh-type	same as above
	B cargo-id	same as above, can't share the same number with
			another cargo ID
	B 80/83		literal 80 or 83 (hex) to indicate a randomized
			cargo ID list
			80 means the triggers refer to the vehicle itself
			83 means the triggers refer to the engine of the
			   consist of this vehicle
	B random-type	a bitmask of triggers that cause the sprite to change
			01	whenever the vehicle gets a new cargo load
			02	whenever the vehicle enters a depot and is
				serviced
			80	only change if *all* triggers are met,
				by default changes if *any* triggers are met
			(currently no other bits are defined)
	B randbit	number of lowest bit to consider for the random number
			should be zero unless this random definition references
			another randomized cargo ID list
	B nrand		how many different randomized cargo IDs to show
			must be a power of two (e.g. 2, 4, 8, 16....)
	W cargo-IDs	list of nrand different cargo-IDs that are chosen randomly
			you can of course list a cargo-ID multiple times to
			increase its probability

	When displaying vehicles in the purchase list, the game will always
	show the first cargo-ID listed, not a random one.

	If you have several random cargo ID lists in a chain, normally all of
	them would check the same bits in an eight-bit randomized value.  To
	prevent that, choose randbit such that all random checks are linearly
	independent, or at least as independent as possible.  For example,
	if one check has 8 possibilities, it needs three bits (values 0-7).
	If you have another check, this means you shouldn't use the first
	three bits, so set randbit to 3.  Then, if you have another check,
	increase randbit again, but make sure not to check for any bits
	above bit 7, because those bits will always be zero.

	The cargo ID is always randomized when a vehicle is first bought,
	but from then on it only changes when any or all of the trigger
	conditions are met.  These conditions are checked according to
	the current graphics, so if there are several random lists in a
	chain, only the triggers of the chain that defines the current
	graphics matter.  To be on the safe side, always have identical
	triggers in all final random lists of a chain.

For num-loadtypes 81/82: list of variational but deterministic cargo IDs

Data is <02> <veh-type> <cargo-id> <81/82> <variable> <shift-num> <AND-mask>
		<nvar> <cid-definitions...> <default-cid>

	Each cid-definition (except for the default-cid) is in the
	form <low-range> <high-range> <cargo-ID>

	B veh-type	same as above
	B cargo-id	same as above, can't share the same number with
			another cargo ID
	B 81/82		literal 81 or 82 (hex) to indicate a variational
			cargo ID list
			81 means the following variable refers to the
			   vehicle itself
			82 means the following variable refers to the engine
			   of the consist of this vehicle
	B variable	what variable determines the cargo ID to choose
			00 current date (counted as days from 1920)
			01 current year (count from 1920, max. 2175 even with eternalgame)
			02 current month
			03 current climate, 0=temp, 1=arctic, 2=trop, 3=toyland
			09 date fraction, a word value, incremented by 0x375 every engine tick
			0A animation counter, a word value, incremented every tick
			80+x vehicle property (where x is the offset in veh struct)
			for example,
			B4 current vehicle speed (speed is at 34) [1]
			C0 vehicle age in days (age is at 40)
			C4 year built (counted from 1920)
	B shift-num	number of bits to right-shift the variable by
	B AND-mask	bit-mask to AND the value of the variable with after
			shifting it; use FF to leave all bits as they are
	B nvar		how many different ranges of values there are

	W cargo-ID	cargo-ID to use for this range of values
	B low-range	lower bound of the range of values (inclusive)
	B high-range	upper bound of the range of values (inclusive)

	W default-cid	default cargo ID to use if none of the ranges
			below matches; must be specified even if the ranges
			cover all possible values

	When displaying vehicle in the purchase list, the game will show
	those variations based on external variables (dates etc.) correctly,
	but variations based on vehicle properties (speed, age etc.) will
	always show the first (not the default) cargo-ID.

	Since only byte-ranges are supported, you must use the shift-num to
	move the value into a useful range.  For example, the vehicle age
	is normally a two-byte value.  If you want to specify the age range
	15-20 years, the age would be 5479-7305 in days.  To get this to
	fit in a byte value, you have to shift it to the right by 5 bits,
	yielding 171-228, which introduces a slight rounding error of course.

	Then you specify the range 171 (AB) to 228 (E4), for example using this
	pseudo-sprite data (parenthesis for emphasis only):

	* 17	00 03 81 C0 05 FF 02 (00 00 00 AA) (01 00 AB E4) (02 00)

	This will use cargo ID 0 if the age is 0 to 5471 days, ID 1 if the
	age is from 5472 to 7328 days, and ID 2 otherwise.


	[1] Note that the unit of the speed depends on the vehicle type
	    For trains: in mph/1.6
	    For road vehicles and ships: in mph/3.2
	    For planes: in mph*8
	    Also this is only valid for the first engine, not wagons or
	    additional engines.

Action 3:	Associate cargo IDs with vehicles
~~~~~~~~~

May appear only *after* all corresponding cargo IDs have been
defined by an action 2 entry in this .grf file.

Data is <03> <veh-type> <n-vid> <veh-id>... <num-vcid> [<cargo-type> <cid>]... <def-cid>

	B veh-type	see action 0
	B n-vid		bits 0-6: how many vehicle IDs this definition applies to
			bit 7: if set, this is a wagon override definition (see below)
	B veh-id	the vehicle IDs (counted from the first of its class)
	B num-vcid	number of vehicle-specific cargo IDs in this definition
			can be zero, in that case the def-cid is used always
	B cargo-type	type of this cargo type (e.g. mail=2, wood=7, see below)
	W cid		cargo ID for this type of cargo
	W def-cid	default cargo ID


If n-vid has bit 7 set, this action 3 must immediately follow an action 3.
The engines defined by the first action 3 will then have an override for
wagon sprites.  This means that you can specify here a number of wagons
that will have different graphics when attached to these engines.

These wagons will use the cargo IDs in the second action 3 whenever they are
attached to one of the engine(s) defined in the first action 3.  Additional
action 3 entries may follow, and if they are overrides, they always apply
to the last action 3 that wasn't an override, but they must always follow
one another with no other actions in between.

For example, if the first action 3 defines the graphics for a train engine,
the following action 3 can have bit 7 set in the n-vid byte, and list the
train wagons whose graphics shall be different if attached to that train
engine.

Note that you need to set the wagon's sprite number to FD using action 0,
or it will only show the default sprite.  You do not need to specify any
other cargo IDs for these wagons though, they will happily use the default
sprite if no other definitions exist.


Action 4:	Define new vehicle names or other texts.
~~~~~~~~~

May appear anywhere in the .grf file.

Data is <04> <veh-type> <language-id> <num-veh> <offset> <data...>

	B veh-type	see action 0
	B language-id	language ID with bit 7 cleared (see below)
	B num-veh	number of vehicles which are getting a new name
	B offset	number of the first vehicle that gets a new name
	S data		new names, each of them zero-terminated, after
			which the next name begins.

Action 4 is only applied if the language-id has a bit set for TTD's
current language.

	Language  Bit  Value
	American  0	01
	English	  1	02
	German	  2	04
	French	  3	08
	Spanish   4	10

Specify a language-id of 1F to apply this action 4 no matter what the
language of TTD is.

The language is determined from the filesize of the TTD executable file.
This means that if TTD Translator has been used to translate this copy,
action 4 will still be applied for the language that the file used to be in,
not the one it has been translated to, of course.

In addition, if bit 7 of language-ID is set, you aren't changing a vehicle
name, but (almost) any arbitrary text of TTD.  In that case, the data is
interpreted slightly differently:

Data is <04> <veh-type> <language-id> <num-entries> <text-id> <data...>

	B veh-type	see below
	B language-id	language ID with bit 7 set
	B num-entries	number of consecutive texts to change
	W text-id	first text ID to change
	S data		new texts, each of them zero-terminated, after
			which the next name begins.

This action is skipped unless the switch for the corresponding new vehicles
has been turned on (i.e., newtrain, newrvs, newships or newplanes).  Use the
special veh-type of "48" (hex) to do this action if *any* of these switches
is on.  This special veh-type is only valid for this particular action.

Note that this kind of action 4 cannot be skipped by either action 7 or
action 9.  If you try anyway, it will probably simply not be skipped, but
other weird consequences may occur.  So don't do that.

The text-id numbers are slightly complicated, unfortunately.  There exist
several classes of strings, each which has a number of string entries.  Only
some classes can be changed currently.  If you have the class, the text ID is
calculated as string_class + string_entry_num.  These classes exist in TTD:

	Class	Meaning		Example entry in the american version of TTD
	0000	General		0:Cannot remove obstacles on land
	0800	Bare land info	B:Rough land
	1000	Railroad tracks	0:Land sloped in wrong direction
	1800	Roads		0:Land sloped in wrong direction for road
	2000	Towns		0:Towns, 6:Population
	2800	Trees		0:Plant trees
	3000	Rail station	0:Rail station selection
	3800	Ship depot	0:Ship depot orientation
	4000	Savegames	0:Save game
	4800	Industries	2:Coal mine
	5000	Tunnels		0:Train in tunnel
	5800	Objects		0:Object in the way
	6000	Debugger(??)	0:Debugger
	6800	Difficulty	0:Difficulty level
	7000	Player Info	4:New face
	7800[*] User-defined	e.g. train names, signs, etc.
	8000	Vehicle names	0:Kirby Paul Tank
	8800	Trains		0:Train depot
	9000	Road vehicles	0:Road vehicle in the way
	9800	Ships		0:Dock construction
	A000	Aircraft	0:Airport construction
	B000	Disasters	0:Zeppelin disaster at ...

	[*] Strings in this class cannot be changed.  Do not try to do so.

To find the class and entry number for the string you're looking for, the
easiest way is probably to load TTD Translator, find the first string in the
class, and then count down to find the entry number.  This may not be
perfectly accurate in some cases.  Alternatively, download Marcin's IDA Pro
database, and find the text there.  It will have a label like a_Txxxx, where
the xxxx is the text ID.


Action 5:	Define new non-vehicle sprite blocks.
~~~~~~~~~

May appear anywhere in the .grf file.

Data is <05> <graphics-type> <num-sprites> <other data...>

	B graphics-type	What set of graphics the sprites define.
	B num-sprites	How many sprites are in this set?
	V other data	Graphics type specific data.  Currently unused.

Possible values for graphics-type:
	4  Pre-signal graphics (48 sprites or 112 with semaphores)
	5  Overhead wires and pylons for electrified railways (xx sprites)
	6  Foundations (retaining walls) for building on slopes (42 sprites)


Action 6:	Apply parameter to following pseudo-sprite or sprite.
~~~~~~~~~

May appear anywhere in the .grf file.

Data is <06> <param-num> <param-size> <offset> ... <FF>

	B param-num	Number of parameter to substitute (First = "zero")
			Ignored if that parameter was not specified in newgrf.cfg
	B param-size	How many bytes to replace.  If larger than 4, the
			bytes of the following parameter are used.  In that
			case, nothing is applied unless *all* parameters
			were specified.
	B offset	Offset into data from beginning of next sprite
			to place where parameter is to be stored

Notes:

The triplet of number, size and offset can be repeated as often
as necessary, for any kind of values.  The final byte must be
a literal "FF" to indicate the end of the list, as TTDPatch cannot
easily determine the length of a pseudo-sprite.

This action is processed only in the initialization of a .grf file and
is ignored during the activation.  Therefore, to conditionally skip this
action, you must use action 9 and not action 7.


Actions 7, 9:	Skip next n sprites if condition is true.
~~~~~~~~~~~~~

May appear anywhere in the .grf file.

Data is <07/09> <param-num> <param-size> <condition-type> <value> <num-sprites>

	B param-num	See action 6
			Additionally, the following values test in-game
			variables:

			83 B current climate, 0=temp, 1=arctic, 2=trop, 3=toyland
			84 B .grf loading stage, 0=initialization, 1=activation
			85 * TTDPatch flags, only for bit tests, see below
			     for a list of defined bit numbers
			86 B road traffic side, bit 4 clear=left, set=right
			87 B reserved
			88 B see if specified GRFID is active (only action 7,
			     not 9; and only valid for condition-types 6 or 7)

			(all other values greater 80 are reserved)

	B param-size	See action 6 (ignored for bit tests, must be 4 for GRFID tests)
	B condition-type
			What condition to test for:
				0  test for bit value being set
				1  test for bit value being unset
				2  param is equal to value
				3  param is not equal to value
				4  param is greater than value
				5  param is less than value
				6  GRFID is active (only for param-num=88)
				7  GRFID is not active (only for param-num=88)
	V value		Bit number (a byte), or value to compare with
			If a value is not a bit number, it has as many bytes
			as the param-size specifies.
	B num-sprites	How many sprites to skip if the condition is true
			Special value 00 means skip rest of this grf file

Bit numbers for TTDPatch flags (param-num = 85):
	Bit	Switch (bit set = switch on)
	0C	keepsmallairport
	0E	largestations
	0F	longbridges
	10	loadtime
	12	presignals
	13	extpresignals
	16	enginespersist
	1B	multihead
	1D	lowmemory
	1E	generalfixes
	27	moreairports
	28	mammothtrains
	29	trainrefit
	2B	subsidiaries
	2C	gradualloading
	32	(Set to bit 0 of unifiedmaglev mode)
	33	(Set to bit 1 of unifiedmaglev mode)
	34	bridgespeedlimits
	36	eternalgame
	37	newtrains
	38	newrvs
	39	newships
	3A	newplanes
	3B	signalsontrafficside
	3C	electrifiedrailway
	41	loadallgraphics
	43	semaphores
	4B	enhancegui
	4C	newagerating
	4D	buildonslopes
	4F	planespeed

Notes:

Both actions skip a number of sprites if the condition is true.  Action 7
skips are performed always, but action 9 skips are disregarded during
initialization.  This means it is only safe to use action 9 to skip an
action 6 entry.  For all others, you must use action 7, or they will not be
initialized properly.  This is especially true of action 3 (sprite IDs),
which need to be resolved during initialization.  If you skip an action 3
using action 9, the graphics will be incorrect.

Take care that the number of sprites to skip does not end in the middle
of a non-pseudo-sprite block, or TTDPatch will attempt to interpret these
regular sprites as pseudo-sprites, and will most likely crash.  Also don't
skip beyond the end of a .grf file.  If you need to skip the rest of a .grf
file, just use num-sprites = 0.

For condition-type 6 and 7, the jump is not taken if the GRFID doesn't exist.
Only if the GRFID is present in memory (i.e. the corresponding .grf file has
been loaded) *and* the condition is true, is the jump taken.  You can use this
to test for the mere presence of a GRFID, whether it is active or not.  Note
that the mere presence is independent of the order in newgrf(w).cfg, whereas
activation always happens in the order of the entries in newgrf(w).cfg.

See below for what actions can be skipped using either action 7 or action 9:

Action to skip	with 7	with 9
0 (new props)	yes	yes
1 (sprite blk)	yes	yes
2 (cargo ID)	no[*]	no	[*] skip the corresponding action 3 instead
3 (veh ID map)	yes	no
4 (veh names)	yes[*]	no	[*] except for general texts
5 (sprite blk)	yes	yes
6 (apply param)	no	yes
7 (skip sprite)	yes	yes
8 (GRF ID)	yes	yes
9 (skip sprite)	yes[*]	yes	[*] not during initialization, of course
A (repl.sprite)	yes	yes


Action 8:	Define GRF ID
~~~~~~~~~

Must be the first pseudo-sprite of a .grf file except for one or more
action 7 entries that may (and probably should) come before it.

Data is <08> <version> <grf-id> <description> <copyright>

	B version	newgrf version, currently 02
	4*B grf-id	globally unique ID of this .grf file
	S description	description of the contents of this .grf file
	S copyright	copyright string describing the author and copyright

This action is mandatory, grf files missing this action will not load, and
will show a "wrong version" error message.

The version must match or be compatible with the newgrf version of the
intended TTDPatch version, see below.

The grf-id must be a globally unique ID.  To choose an ID, use the initials
of your first and last name as the first two bytes, along with two more bytes
of your own choice as the last two bytes.  For example, if you are
"Foobar Z. Boozle", use 46 42 00 00 for your first file, and 46 42 00 01
for your second one.  If someone else has already used these initials,
please use a different capitalisation or simply two other letters to keep the
IDs unique.  The ID must not be the same as that of any other .grf file,
either yours or somebody else's.  It should however be the same for both
the DOS and Windows versions of a grf file.  If you make an update to a .grf
file and think that it will be backward compatible with the savegames, give
it the same ID as the original file.  To make it necessary to reactivate the
.grf file, use a new ID.

The ID is used to identify the .grf files to activate after loading a
savegame.  When a game is saved, the IDs of all currently active .grf
files will be stored, and when the game is loaded, only those .grf files
with matching IDs will be activated (if they are still available).  For
all other .grf files, this action 8 simply skips the rest of the .grf file,
as if it had been a successful action 7.

A .grf file is considered to be active if its action 8 has been processed
successfully.  This means that you should control activation by placing
an action 7 before the action 8, to skip a .grf file for the wrong
climate, for example.

The GRF ID "FFFFFFFF" is reserved for graphics files that are controlled
by other switches, for example pre-signals, the catenary system or track
foundations on slopes.  These will be loaded and activated whenever they
are in newgrf(w).cfg, disregarding whether they were active before or not.

The description should be a short zero-terminated string that describes
the contents of the .grf file.  It might for example be used by other
programs that allow selecting .grf files for newgrf.cfg.

The zero-terminated copyright string has no specified format.  It can
contain anything you want to, but if you want to be recognized as the
author of the .grf file, it should be something like
"Copyright (C) 2003 by Foobar Z. Boozle.  All rights reserved."
Optionally you can follow with your contact info and any other
information you want to include in the .grf file.

Newgrf version table

newgrf	compatible
version	with		TTDPatch version
00	00		1.9.1 alpha 27 and earlier
01	00-01		1.9.1 alpha 28 and above
02	02		2.0
03-FF	- not defined yet -


Action 9:	Skip next n sprites if condition is true.
~~~~~~~~~

(See actions 7, 9 above.)


Action 0A:	Replace arbitrary TTD sprites
~~~~~~~~~~

Using this action, you can replace arbitrary sprites in trg1.grf with your
own version.

Data is <0A> <num-sets> <set1> [<set2> ...]
A set is <num-sprites> <first-sprite>

	B num-sets	How many sets of sprites to replace.
			Sets are continguous chunks of one or several sprites.
Then for each set:
	B num-sprites	How many sprites are in this set
	W first-sprite	First sprite number to replace

The sprites with which to replace TTD's sprites then follow this pseudo-sprite,
just like in action 1.  The first of the following sprites will be the first
sprite from the first set, and the following sprites and sets are used in the
order of their appearance.

You can find the sprite numbers by looking in trg1.pcx, they're the little
numbers above each sprite.



4)  General information and hints and tips
------------------------------------------

a) An example .nfo file

Here's the simplest possible complete .nfo file.

It defines one train engine, no stats modified, 8 different directions
(i.e. not symmetric like the SH 40), no differences based on cargo type
or other factors.

You must include the first three comment lines or the file won't work.

---8<---cut here---8<---
// Automatically generated by GRFCODEC. Do not modify!
// (Info version 4)
// Format: spritenum pcxfile xpos ypos compression ysize xsize xrel yrel
  0 * 4  0D 00 00 00
  1 * 7  00 00 01 01 XX 12 FD
  2 * 4  01 00 01 08
  3 SPRITES\train.pcx 98 8 01 18 8 -3 -10
  4 SPRITES\train.pcx 114 8 09 14 20 -14 -6
  5 SPRITES\train.pcx 146 8 01 12 28 -14 -6
  6 SPRITES\train.pcx 194 8 09 16 20 -4 -8
  7 SPRITES\train.pcx 226 8 01 18 8 -3 -10
  8 SPRITES\train.pcx 242 8 09 16 20 -14 -7
  9 SPRITES\train.pcx 274 8 01 12 28 -14 -6
 10 SPRITES\train.pcx 322 8 09 14 20 -4 -6
 11 * 9  02 00 00 01 01 00 00 00 00
 12 * 7  03 00 01 XX 00 00 00
---8<---cut here---8<---

For the XX in sprite #1 and #12 substitute the train engine number you want
to change, e.g. use 00 to replace the Kirby Paul Tank.

You will probably have to modify the PCX file name, the X and Y coordinates
of the sprites (first two numbers after the PCX file name), as well as the
X and Y offsets (last two numbers).  Possibly the X and Y sizes too.

A very brief summary of the pseudo sprites:
 #0: define how many sprites are in the file (13 decimal=0D)
 #1: action 0; set the train engine properties (in this case the sprite)
 #2: action 1; declare the next 8 sprites as actual vehicle sprites
 #3 through #10 are therefore vehicle sprites
#11: action 2; declare cargo ID 0
#12: action 3; attach cargo ID 0 to the engine

If you want to modify the train properties (currently only the sprite
prop. 12 is set to FD), change the second 01 in sprite #1 to the number of
properties, add them at the end of the line, and adjust the number of
bytes (now 7).

If you want to make it look different depending on cargo, add them after
sprite #10, and modify sprite #2 appropriately.  Then define more cargo IDs
using action 2 and tell action 3 when to use which ID.  Don't forget to
adjust the total number of sprites specified in sprite #0.



b) The following cargo types are defined by TTDPatch:

Num1	Bitval	Num2	Type
 00	1	 00	Passengers
 01	2	 01	Coal
 02	4	 02	Mail
 03	8	 03	Oil
 04	10	 04	Livestock
 05	20	 05	Goods
 06	40	 06	Grain/Wheat/Maize
 07	80	 07	Wood
 08	100	 08	Iron Ore
 09	200	 09	Steel
 0A	400	 0A	Valuables/Gold/Diamonds
 0B	800	 09	Paper
 0C	1000	 0B	Food
 0D	2000	 04	Fruit
 0E	4000	 08	Copper Ore
 0F	8000	 09	Water
 10	10000	 01	Rubber
 11	20000	 01	Sugar
 12	40000	 03	Toys
 13	80000	 04	Batteries
 14	100000	 05	Candy (Sweets)
 15	200000	 06	Toffee
 16	400000	 07	Cola
 17	800000	 08	Cotton Candy (Candyfloss)
 18	1000000	 09	Bubbles
 19	2000000  0A	Plastic
 1A	4000000	 0B	Fizzy Drinks
 FF	n/a	 n/a	Shown in purchase list


Num1 is what you use in action 3.
Bitval is (1<<Num1), and it is what you add up to make the bit mask for action 0.
Num2 is what you use as cargo type in action 0.

Note that using a cargo type of FF in action 3 allows you to decide which
cargo ID to show in the purchase list.



c) General strategy for implementing new graphics in the .grf file:

1) First sprite is special, defining the total number of entries in the .grf
   file
2) Start with one or more action 7 entries that decide whether or not to
   load these graphics, for example based on the current climate.
3) After the action 7 entries, define your GRF ID with action 8.
4) Then define one or several action 0 entries, that (possibly among other
   things) set the vehicle sprite IDs to FD (trains) or FF (all other vehicle
   types).  Only vehicles with these sprite IDs will be using the new sprites.
5) Start a block of new graphics with an action 1 (sprite block) entry,
   followed by the actual sprite data.  Ideally, you put the graphics of all
   vehicles together in this one sprite block, taking note of what sets of
   sprites have what number (as determined by their position in the block).
6) After action 1, give action 2 (cargo ID) entries for each different
   combination of vehicle and cargo type.  The cargo IDs should start at zero
   and be numbered consecutively.
7) After all action 2 entries, use action 3 (veh ID to cargo ID maps) to
   specify what cargo IDs are to be shown for which vehicle and which cargo
   types.



d) Dealing with the sprite numbers and pseudo-sprite blocks

It can be quite a chore to make sure that the sprite numbers increase
by one, and that you have the correct length for the pseudo-sprite blocks.
Currently, GRFCodec has only limited parsing capabilities, so you need to
make sure that they are indeed correct.  Note that as of GRFCodec version
0.9.4, you can specify a sprite number of "-1", which turns off the number
checking for that sprite.  The following sprites still need correct numbers
(unless they also have "-1" as the number), and the sprite length still
needs to be specified.

One help in this task is a Perl script called renum.pl, which you can find
in this directory.  If you haven't heard of Perl before, it's a powerful
programming language that you can get for free.  For example, you can
install it with the Cygwin packages (www.cygwin.com), or from activestate.com
and perl.com.

If you have written a .nfo file, but it doesn't have the right numbers for
the sprites or the lengths, run the renum.pl script like this:

perl renum.pl < your.nfo > yournew.nfo

It will take the your.nfo (substitute your actual filename), and write
yournew.nfo with correct sprite numbers and pseudo-sprite lengths.

Note that the format of the .nfo needs to be correct for this to work
properly; in particular, the sprite numbers and pseudo-sprite lengths must
already be *there* (as dummy numbers), but they need not be correct.



e) How to only load your graphics in some circumstances

For example, you only want your graphics to be active in the right climate,
or only if some other condition is true.

For this, the first entries in your .grf file must be actions 7 which test
that condition, and skip the rest of the file if true.  To skip the rest
of the file, remember to specify a <num-sprites> parameter of 00.

Immediately *after* your initial action 7 entries, you place the action 8
that defines your GRF ID.

This way, the .grf file is considered active or inactive in the right
circumstances.



f) The two stages of loading a .grf file

Every .grf file is processed in two stages.  The first stage, initialization,
is run only once.  In this stage, TTDPatch records the GRF IDs, and resolves
all cargo IDs and sprite IDs as well as doing some other bookkeeping tasks.

During initialization, actions 0, 3, 4, 5 and 7 are ignored.  Action 6 is
carried out *only* during initialization.  Action 7 is ignored because
otherwise the sprite IDs and cargo IDs that are skipped won't be resolved.
Action 8 has the GRF ID recorded so that it can be looked up later.

A .grf file is activated only if it was active when the game was started.  If
a game is loaded, only its active .grfs will be reactivated, unless
"loadallgraphics on" is used.  A .grf file is considered active if its
action 8 has been processed, i.e. its action 8 hasn't been skipped using
an action 7.

During activation, only actions 0, 3, 4, 5, 7, 8, 9 and 0A are carried out.
All others are ignored, because they only need to be processed once at
initialization.



g) Final words

Now, after reading all this, go back to section 1, and see if you can
understand how that pseudo-sprite works.  Then all should be clear!
