Action3/Railtypes

From GRFSpecs
Jump to: navigation, search

Introduction

Action 3 assigns graphics sets (referenced to by (chains of) action 2(s) to feature IDs.

Supported by OpenTTD 1.0 (r19056)1.0 Not supported by TTDPatch Railtypes are available only in OpenTTD > r19056

Format

The format of the data is feature-dependent. For railtypes it looks like

 <Sprite-number> * <Length> 03 10 <n-id> <ids...> <num-cid> <cargo-type> <set-ID>... <default set-ID>
Element Size Description
<Sprite-number> dec A sequential sprite number
<length> dec The total number of bytes used in this action
03 B Defines action 03
10 B The feature byte for railtypes
<n-id> B Number of IDs this action 3 associates graphics with
<ids...> B/B* IDs of the current feature this action 3 associates graphics with. There must be as many IDs as <n-id> specifies
<num-cid> B Number of different "cargo" types to support
<cargo-type> B "Cargo" type for which to use the following set-ID
<set-ID> W Set-ID (from action 2 or from a varaction2 chain) to use for this cargo type
<default set-ID> W Default set-ID to use if none of the above matches

Description

Sprite-number

This is just the number you are at.

Length

Count the number of bytes in this action.

n-id

How many items of the current feature this action 3 defines new graphics for. If this is more than one, all items listed will get the same graphics. If this value has bit 7 set (i.e. 80 added), it is a wagon override. See Action 3 - Livery Override for more info on this feature.

You can make a definition with n-id equal to zero (and thus no ids that follow).  This creates a generic feature-specific definition not associated with any particular item.  At the moment, this is used for generic callbacks, but might be extended to other functions eventually.

ids

Feature IDs to use this action 3 for. All IDs are counted from the first of their class, i.e. the first road vehicle has 00, as does the first plane, the first ship, and the first train vehicle.

num-cid

Number of "cargo" type definitions that follow.

cargo-type

Railtypes re-uses in its Action3 the 'cargo'-type definition in order to assign the type of graphics defined by the associated set-ID:

'Cargo' Type Sprite Type #Sprites Useage
00 Icons and cursors 16 4 rail directions, autorail, depot, tunnel and convert rail. First all icons, then all cursors.
01 Track overlays for junctions and PBS[1] 10 6 flat and 4 slope pieces. Sprites should contain only the track, with no landscape.
02 Underlay[1] 16 6 flat and 4 slope, and 1 X crossing pieces with track, and 5 junction pieces without track. Sprites should contain the track and the 'ballast' below it. No landscape should be drawn.
03 Tunnel[1] 4 1 sprite for each direction. Sprite is overlay for track in existing tunnel graphics. The original ground sprite is drawn, then the overlay, then possibly a train and the original tunnel head is drawn over the top. This keeps compatibility with different landscape types. Sprite order: SW, NW, NE, SE. Supported by OpenTTD 1.2 (r23952)1.2 If type 0A is defined as well, this sprite is used slightly different, see Tunnel portal overlay (0A).
04 Catenary wire 28 Follows the same layout for wires of the first 28 sprites as Action5 type 5.
05 Catenary pylons 8 Follows the same layout for pylons of the 8 sprites after the wires as Action5 type 5.
06 Bridge surfaces[1] 6 10 sprites if we ever include diagonal bridges.
07 Level crossing overlay[1] 10 1 rail overlay and 4 light sprites for X and Y.
08 Depots[2] 6 2 sprites for each southish, 1 sprite for each northish. Follows the original layout for depot sprites.
09 Fences 8 / 16 X, Y, Vertical, Horizontal, SW slope, SE slope, NE slope and NW slope. Follows the same layout as original original fence sprites at sprite 1301. Supported by OpenTTD 1.6 (r27343)1.6 Not supported by TTDPatch Since OpenTTD r27343 there is also a 16 sprites version, see below.
0A Tunnel portal overlay[3] 4 Supported by OpenTTD 1.2 (r23952)1.2 1 sprite for each direction, order is SW, NW, NE, SE.
0B Signal sprites 8 Supported by OpenTTD 1.3 (r24367)1.3 1 sprite for each direction, order is SW, NE, NW, SE, E, W, S, N (i.e. like for the corresponding Action 5 entry).
  1. 1.0 1.1 1.2 1.3 1.4 Either all or none of these sprites should be provided.
  2. Supported by OpenTTD 1.2 (r22854)1.2 In OpenTTD prior to r22854, depot sprites would not be used if the above 'all or none' sprites were not supplied.
  3. Above 'all or none' sprites must be supplied, if these sprites are to be used.

GUI sprites (00)

Railtype gui.png

Rail overlay (01)

Railtype overlay.png

Rail underlay (02)

Railtype underlay.png

Level crossing sprites (07)

You can define a special track piece which crosses the road and for each of two directions and each of the corners of the tile a separate sprite for a light, sign, or whatever should go there.

Sprite number for X Sprite number for Y Useage
0    1    Rail overlay
2    3    North light
4    5    East light
6    7    West light
8    9    South light

Railtype levelcrossing.png

Depot sprites (08)

Sprite Number Usage
0    NE wall for SE-entry depot.
1    Depot building for SE-entry depot.
2    NW wall for SW-entry depot.
3    Depot building for SW-entry depot.
4    Depot building for NE-entry depot.
5    Depot building for NW-entry depot.

Fences (09)

Railtype fences.png

Supported by OpenTTD 1.6 (r27343)1.6 Not supported by TTDPatch Since OpenTTD r27343 there is also a 16 sprites version, this allows to use different sprites resp. offsets for the fences on either track side.

Sprite number Tile slope Track bit Fence position Version
0 flat X NW Supported by OpenTTD 1.0 (r19056)1.0 Not supported by TTDPatch
1 flat Y NE Supported by OpenTTD 1.0 (r19056)1.0 Not supported by TTDPatch
2 flat left E Supported by OpenTTD 1.0 (r19056)1.0 Not supported by TTDPatch
3 flat upper S Supported by OpenTTD 1.0 (r19056)1.0 Not supported by TTDPatch
4 SW X NW Supported by OpenTTD 1.0 (r19056)1.0 Not supported by TTDPatch
5 SE Y NE Supported by OpenTTD 1.0 (r19056)1.0 Not supported by TTDPatch
6 NE X NW Supported by OpenTTD 1.0 (r19056)1.0 Not supported by TTDPatch
7 NW Y NE Supported by OpenTTD 1.0 (r19056)1.0 Not supported by TTDPatch
8 flat X SE Supported by OpenTTD 1.6 (r27343)1.6 Not supported by TTDPatch
9 flat Y SW Supported by OpenTTD 1.6 (r27343)1.6 Not supported by TTDPatch
10 flat left W Supported by OpenTTD 1.6 (r27343)1.6 Not supported by TTDPatch
11 flat upper N Supported by OpenTTD 1.6 (r27343)1.6 Not supported by TTDPatch
12 SW X SE Supported by OpenTTD 1.6 (r27343)1.6 Not supported by TTDPatch
13 SE Y SW Supported by OpenTTD 1.6 (r27343)1.6 Not supported by TTDPatch
14 NE X SE Supported by OpenTTD 1.6 (r27343)1.6 Not supported by TTDPatch
15 NW Y SW Supported by OpenTTD 1.6 (r27343)1.6 Not supported by TTDPatch

Tunnel portal overlay (0A)

If this 'cargo' type is defined, tunnels for this railtype will be drawn differently.

First, a grass underlay base sprite is drawn, then the sprite returned from type 03. Next, train sprites if applicable and then a grass overlay and finally the sprite from this type (0A). The grass sprites are defined in the base set and do not contain any parts of the tracks or portal, so these have to be fully provided by the railtype sprites.

Illustration: RailtypeTunnelExample.png

Variable 10 can be used to distinguish between several requested tunnel variations:

Lowest byte of variable 10 Meaning
00 This is a plain portal without any extra features (like tracks above).
all other values reserved for future extensions (e.g. basetunnels).

The other bytes of variable 10 are reserved, and must be masked.

Signal sprites (0B)

This 'cargo' type can be used to supply custom signal graphics.

The resulting sprite set must consist of 8 sprites, corresponding to the following signal directions: SW-facing, NE-facing, NW-facing, SE-facing, E-facing, W-facing, S-facing, N-facing. Variable 18 contains information about the kind of signal to be drawn. If resolving fails or results in an empty sprite group, the matching base set sprite will be used instead.

Format of variable 18: xxTTVVSS

TT: Signal type Meaning
00 Normal block signal
01 Entry pre-signal
02 Exit pre-signal
03 Combo pre-signal
04 Two-way path signal
05 One-way path signal
all other values Reserved


VV: Signal variant Meaning
00 Light (electric) signal
01 Semaphore
all other values Reserved


SS: Signal state Meaning
00 Red signal
01 Green signal
all other values Reserved

All other bytes of variable 18 are reserved and must be masked.

Variable 10 can be used to distinguish between map and GUI sprites:

Lowest byte of variable 10 Meaning
00 Signal is drawn in a viewport, i.e. on the map.
10 Signal is drawn in the signal GUI. The returned sprite set must still have 8 sprites, but OpenTTD will only use the 7th sprite, so all other sprites can be empty.
all other values Reserved

The other bytes of variable 10 are reserved, and must be masked.

default set-ID

The default set-ID would be used for railtype callbacks. However, since there are currently no callbacks for railtypes it should always result in a callback-failure.

Example