Action2/Stations
Introduction
Defining station set-IDs.
For stations, Action2 is used to define set-IDs, similar to the way it works for vehicles. See the description below for details.
Do not skip an Action2 using Action9 (unless it skips the whole file). Action2 must not be skipped by Action9 or TTDPatch will most likely crash. Skip or modify Action3 instead. Skipping an Action2 with an Action7 has no effect.
Basic Action 2
For stations, the data looks as follows:
<Sprite-number> * <Length> 02 04 <set-id> <numlittlesets> <numlotssets> <sets...>
| Element | Size | Description |
|---|---|---|
| <Sprite-number> | dec | A sequential sprite number |
| <length> | dec | The total number of bytes used in this action |
| 02 | B | Defines action2 |
| 04 | B | Stations is feature 4 |
| <set-id> | B | What set-ID this action2 defines |
| <numlittlesets> | B | How many different cargo amounts to show when there is little cargo |
| <numlotssets> | B | Same but when there is lots of cargo |
| <sets...> | W | Sprite sets for each of the cargo amounts |
Advanced sprite layout using register offsets
<Sprite-number> * <Length> 02 07/09/0F/11 <set-id> <0x40 + num-sprites>
<groundsprite> <flags> [<register/value>]...
[ <buildingsprite> <flags>
( <xoffset> <yoffset> <zoffset> <xextent> <yextent> <zextent>
| <xpixeloffset> <ypixeloffset> 80)
[<register/value>]...
]...
1.2 
The spritelayout defines fixed spritesets to use from the Action 1. The registers can be used to individually select sprites from the spritesets instead of always using the construction stage. The registers are evaluated and their values are saved when the Action 2 sprite layout is evaluated. Other callbacks called during drawing (like CB 1E) have no effect on the used values of the registers.
| Element | Size | Description |
|---|---|---|
| <Sprite-number> | dec | A sequential sprite number |
| <length> | dec | The total number of bytes used in this action |
| 02 | B | Defines action 02 |
| 04/07/09/0F/11/14 | B | feature: 07 town buildings, 09 industry tiles, 0F objects, 11 airport tiles, or 14 road stops |
| <set-id> | B | ID for this definition |
| 40 + <num-sprites> | B | Number of following building sprites (the primary groundsprite mustn't be counted). Allowed range: 0x40+0 to 0x40+63 (0x40 to 0x7F). |
| <groundsprite> | D | Primary ground sprite for the building (see format below) |
| <flags> | W | Flags for the primary ground sprite (see format below) |
| <register/value> | V | Registers / values to be used. Depending on <flags> (see format below) |
| <buildingsprite> | D | The sprite to be drawn. Unlike the basic format, zero isn't allowed here. |
| <flags> | W | Flags for the building sprite (see format below) |
| -- for sprites defining a new bounding box -- | ||
| <xofs> | B | x-offset from northern tile corner (as a signed byte) |
| <yofs> | B | y-offset from northern tile corner (as a signed byte) |
| <zofs> | B | z-offset from the ground |
| <xextent> | B | size of sprite in x direction |
| <yextent> | B | size of sprite in y direction |
| <zextent> | B | size of sprite in z direction |
| -- for sprites sharing their bounding box with the previous sprite -- | ||
| <xpixeloffset> | B | x offset from the top left corner of the previous sprite |
| <ypixeloffset> | B | y offset from the top left corner of the previous sprite |
| 80 | B | a literal 80h byte to distinguish from new-bounding-box definitions |
| <register/value> | V | Registers / values to be used. Depending on <flags> (see format below) |
Descriptions of elements
Sprite-number
This is just the number you are at.
Length
Count the number of bytes in this action.
Set-id
The set-ID that you want to define for this set. You can choose any value between 00 and FF, and you can reuse them within a grf file at a later point (if being equal to an existing set ID, the existing one is overwritten and the new one is used).
Sprite definition for ground and building sprites
The ground and building sprite fields have the following format:
| Bits | Version | Content |
|---|---|---|
| 0-13 | 0.6  2.5 |
Sprite number, exact meaning specified by bit 31 |
| 14-15 | 0.6 2.5 |
0: draw sprite normally, 1: draw sprite in transparent mode, 2: recolor sprite |
| 16-29 | 0.6 2.5 |
Color translation special sprite number, see below |
| 30 | 0.6 2.5 |
If set, sprite is drawn normally even in transparent buildings mode (for building sprites only) |
| 31 | 0.6 2.5 |
Sprite type, see below |
0.6 2.5 Since TTDPatch 2.0.1 alpha 57, the groundsprite value can be zero if no ground sprite is needed (this is useful if you need to draw custom foundations, see example). Ground sprites are always drawn normally, so bit 30 is ignored for them. Bit 30 may get a different meaning for ground sprites in a later version of TTDPatch, so please leave it zero for now. This does not apply to additional groundsprites using the "<xpixeloffset> <ypixeloffset> 80"-syntax (see above); for these bit 30 has the same meaning as for building sprites.
Colour translation special sprite number
This is used only if bits 14 or 15 are nonzero. Bits 16-29 must be the number of a regular TTD sprite containing a colour translation table (see below for available translation tables). For transparent mode, a suitable translation table is needed, e.g. that of TTD´s sprite number 802 (s.b.). See RecolorSprites for more information on the usage of transparent and recolouring sprites.
For houses, if no recolour sprite is given but recolouring is turned on in bits 14-15, there are two possibilities:
- If you have callback 1E enabled, it is called to determine the colour mapping.
- If callback 1E is disabled or fails, one of the colours specified in property 17 will be chosen randomly.
See RecolorSprites for a list of available colour translations.
For industry tiles, if this field is zero, but recolouring is turned on in bits 14 or 15, the colour of the containing industry will automatically be applied.
The ground sprite should be exactly the same size and shape as TTD's flat tile. In general, it shouldn't contain anything that has a z-dimension because any non-ground sprite will cover it.
Useful values for ground sprites:
| Sprite number (decimal) | Contents |
|---|---|
| 3924 | bare land |
| 3981 | grass |
| 4061 | water |
| 4550 | snow or desert (depending on climate) |
| 1420 | concrete |
Please note that all the ground sprite becomes visible in "transparent buildings" mode, so you should draw parts that seem to be hidden as well.
Sprite type
If bit 31 is clear, the bottom 14 bits contain a regular TTD sprite number.
If bit 31 is set, the bottom 14 bits contain a number of a sprite set in the most recent action 1, and the used sprite is decided according to the current construction state and the number of sprites in the set:
- if there's only one sprite, it's used always
- if there are two sprites, the first is used during construction (stages 0-2), and the second is used for the finished building (stage 3)
- if there are three sprites, the first will be used in the beginning of the construction (stage 0), the second will be used during the rest of the construction (stages 1 and 2) and the third will be used for the complete building (stage 3)
- if there are four or more sprites, the first four will be used for the four construction stages. Sprites after the first four are always ignored.
Flags in advanced sprite layouts
<flags> is a bitset of word size with these meanings:
| Bit | Hex | Parentsprite | Groundsprite/Childsprite |
|---|---|---|---|
| 0 | 0001 | Skip bounding box including child sprites | Skip sprite |
| 1 | 0002 | Add offset to sprite, disable default usage of construction stage or railtype-offset | |
| 2 | 0004 | Add offset to recoloursprite | |
| 3 | 0008 | Recolour sprite is from Action 1 (will be affected by the same construction stage resp. railtype-offsets as sprites, unless bit 2 is set) | |
| 4 | 0010 | Add offset for <xoffset> and <yoffset> | Add offset for <xpixeloffset> |
| 5 | 0020 | Add offset for <zoffset> | Add offset for <ypixeloffset> |
| 6 | 0040 | Resolve sprite with Variable 10 set to a specific value[1] | |
| 7 | 0080 | Resolve recoloursprite with Variable 10 set to a specific value[1] | |
| 8..15 | Reserved, should be zero. If the GRF sets unknown bits, it will be disabled. | ||
- ↑ 1.0 1.1
Only valid for stations: The Action 1/2/3 chain is resolved multiple times, sprites can be part of different Action 1: The associated value in <register/value> is the raw value (not a register!) to put into Variable 10 while resolving the sprites.
- only allowed values currently 0-7
- the value '2' is used when resolving custom foundations, (so, do not conflict with that)
- even if the sprite is not from an Action 1, the value still defines which Action2 chains defines the values for the referenced registers.
- The register for "Add offset to recoloursprite" is defined by the Action 1/2/3 chain with Variable 10 as defined for the recolour sprite.
- The other registers are defined by the Action 1/2/3 chain with Variable 10 as defined for the sprite.
- If no variable 10 values are defined, then station property 13 bit 0 takes effect; i.e. variable 10 is set to 0 or 1 depending on the bit and whether the first groundsprite is resolved or a different sprite. This applies to both the groundsprite and the palette of the groundsprite.
Register or value in advanced sprite layouts
These are the temporary storage registers to add to the individual parts. The register values are considered signed. The order of the registers is the same as the bits in <flags>. If a bit is not set, then no registers appears for it. Most bits require one register.
- <xoffset> and <yoffset> can only be enabled together, using two registers,
- the "skip bounding box"-register uses value 1 to draw the sprite, and 0 to skip it,
- the "recolorsprite from Action 1" uses no register at all,
- the Variable 10 values are not set via a register, but via a byte-constant.
numlittlesets, numlotssets
Like for vehicles, this decides the graphics set to use depending on the amount of cargo waiting. There are two caveats, though. Firstly, a station can have 12 different cargoes waiting, not just a single one. Secondly, the maximum amount is 4095 for all stations and all cargo types.
Regarding the first issue, the amount of cargo this refers to depends on the action3 that triggered this action2:
- if the cargo type matched exactly, it's the amount of the matching cargo (e.g. the action3 said "for coal, use this action2")
- if the default was used, it's the amount of all cargo types added together
- if the station is displayed for construction, the maximum amount is shown
Regarding the second issue, TTDPatch introduces the distinction between "little" and "lots of" cargo. The amount where this occurs is set by property 10, which is zero by default. But if set to a non-zero value, for example 200, then the range 0 to 199 is divided by numlittlesets, and the remaining range 200 to 4095 is divided by numlotssets. If property 10 is zero, the "little" sets are never used, and so numlittlesets may be zero. numlotssets must never be zero, however.
sets
The sets from the most recent action1 to use for this set-ID, for each stage of numlittlesets and numlotssets, i.e. in total numlittlesets+numlotssets entries.
Example
Something to go here
