Difference between revisions of "NML:Railtypes"

From GRFSpecs
Jump to navigationJump to search
(reference list of railtype labels)
 
(37 intermediate revisions by 11 users not shown)
Line 2: Line 2:
   
 
Railtypes can only be defined in OpenTTD {{ottd|1.0|r18969}} or later.
 
Railtypes can only be defined in OpenTTD {{ottd|1.0|r18969}} or later.
  +
  +
  +
==Railtype IDs==
  +
Railtype IDs are limited to 64 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..63 range. If other railtype GRFs are loaded, it may be that there are not enough railtype slots available. To prevent your entire NewGRF from being deactivated with the 'Attempt to use invalid ID'-error, you can use the following code:
  +
  +
if (railtype_available("LABL") || loading_stage == LOADING_STAGE_RESERVE)
  +
... item definition ...
  +
} else if (loading_stage == LOADING_STAGE_ACTIVATE) {
  +
... warning / error ...
  +
}
  +
The warning / error is optional, but can be used to inform the user about the missing railtypes.
  +
  +
== Vehicle and Railtype availability ==
  +
  +
Vehicle and railtype availability and compatibility is influenced by multiple properties.
  +
Generally, the vehicle defines which railtype it is, and the railtypes define the compatibility between each other.
  +
* A vehicle exists, if its railtype (train property <code style="color:green">track_type</code>) is defined. Otherwise the vehicle is disabled.
  +
* When a vehicle is introduced, it always introduces its railtype (train property <code style="color:green">track_type</code>).
  +
* A railtype is introduced, if at least one of the following conditions is met:
  +
** A vehicle is introduced, that references the railtype (train property <code style="color:green">track_type</code>).
  +
** Another railtype is introduced, that references the railtype via the introduced railtype list (railtype propery <code style="color:green">introduces_railtype_list</code>).
  +
** The introduction date (railtype property <code style="color:green">introduction_date</code>) is passed and all required railtypes (railtype property <code style="color:green">requires_railtype_list </code>) are available.
  +
  +
Via railtype property <code style="color:green">compatible_railtype_list</code> multiple railtypes can be defined, which shall be considered equivalent to a railtype.
  +
This affects the interpretation of train property <code style="color:green">track_type</code>. If train property <code style="color:green">track_type</code> references an undefined railtype, then
  +
railtype property <code style="color:green">compatible_railtype_list</code> is checked for all defined railtypes, whether the vehicle can be reassigned to some other railtype.
  +
Otherwise the vehicle is disabled. However note also that <code style="color:green">alternative_railtype_list</code> provides an alternative/complementary approach to handling undefined railtypes.
  +
  +
Note that when routing trains onto railtypes, the compatibility is only evaluated for the lead engine of a consist. This means that trains will run on incompatible rail types if they are in a consist where the lead engine is compatible with the rail type. This applies to both engines and wagons.
   
   
 
==Railtype properties==
  
==Railtype properties==
   
−
{| class="t"
 +
{| class="wikitable sortable"
 
! property
  
! property
 
! value range
  
! value range
Line 13: Line 42:
 
| label
  
| label
 
| 4-byte string
  
| 4-byte string
−
| names of default rail types: "RAIL", "ELRL", "MONO", "MLEV", "3RDR". See the [[RailtypeLabels|List of railtype labels]] in the NewGRF Specs for currently defined custom labels.
 +
| names of default rail types: "RAIL", "ELRL", "MONO", "MGLV". See the [[RailtypeLabels|List of railtype labels]] in the NewGRF Specs for currently defined custom labels.
 
|-
  
|-
 
| introduction_date
  
| introduction_date
Line 22: Line 51:
 
| name
  
| name
 
| string
  
| string
  +
| Name of this railtype
−
| Caption of the build rail toolbar
  
  +
|-
  +
| toolbar_caption
  +
| string
  +
| {{ottdp|1.2|no|ottdrev=23129}} Caption of the build rail toolbar. In earlier versions this is the same as the 'name'
 
|-
  
|-
 
| menu_text
  
| menu_text
Line 42: Line 75:
 
| compatible_railtype_list
  
| compatible_railtype_list
 
| list of railtype labels
  
| list of railtype labels
−
| Provide a list of rail types that trains of this type can also run on. e.g. ["RAIL", "ELRL", "MONO"]
 +
| Provide a list of rail types that trains of this type can also run on. e.g. ["RAIL", "ELRL", "MONO"]. Note that when routing trains, the compatibility is only evaluated for the lead engine of a consist. This means that trains will run on incompatible rail types if they are in a consist where the lead engine is compatible with the rail type. This applies to both engines and wagons.
 
|-
  
|-
 
| powered_railtype_list
  
| powered_railtype_list
Line 50: Line 83:
 
| railtype_flags
  
| railtype_flags
 
| bitmask(RAILTYPE_FLAG_XXX, ...)
  
| bitmask(RAILTYPE_FLAG_XXX, ...)
  +
|
−
| XXX = [CATENARY|NO_LEVEL_CROSSING] Flags enable catenary and/or disable level crossings.
  
  +
; CATENARY
  +
: Enable catenary
  +
; NO_LEVEL_CROSSING
  +
: Disable level crossings
  +
; HIDDEN {{ottd|1.9}}
  +
: Hides railtype from player
  +
; PRECOMBINED {{ottd|1.10}}
  +
: Enable use of precombined overlay sprites
  +
; ALLOW_90DEG {{ottd|1.10}}
  +
: Always allow 90 degree turns
  +
; DISALLOW_90DEG {{ottd|1.10}}
  +
: Always prohibit 90 degree turns (takes precedence over ALLOW_90DEG)
 
|-
  
|-
 
| curve_speed_multiplier
  
| curve_speed_multiplier
−
| 0...65525
 +
| 0...255
 
| max curve speed is defined as multiple of the base curve speed (see below)
  
| max curve speed is defined as multiple of the base curve speed (see below)
 
|-
  
|-
Line 63: Line 108:
 
| 0 ... 65525
  
| 0 ... 65525
 
|
  
|
−
{{ottd|1.1|r19307}} per piece of track as multiplier to PR_BUILD_RAIL base cost.
 +
{{ottd|1.1|r19307}} per piece of track as multiplier to PR_BUILD_RAIL base cost. Default cost factors are 8, 12, 16 and 24 for RAIL, ELRL, MONO and MGLV.
 
|-
  
|-
 
| speed_limit
  
| speed_limit
Line 92: Line 137:
 
|
  
|
 
{{ottd|1.1|r21866}} number which defines the sort order among rail types. If this entry is not defined, it gets assigned sort order n*10+7 for the n-th railtype.
  
{{ottd|1.1|r21866}} number which defines the sort order among rail types. If this entry is not defined, it gets assigned sort order n*10+7 for the n-th railtype.
  +
|-
  +
| maintenance_cost
  +
| 0 ... 255
  +
|
  +
{{ottd|1.2|r23415}} Maintenance cost factor for each piece of tracks of this railtype. Default cost factors are 8, 12, 16 and 24 for RAIL, ELRL, MONO and MGLV.
  +
|-
  +
| alternative_railtype_list
  +
| list of railtype labels
  +
|
  +
{{ottd|1.2|r23758}} List of rail types which this rail type will act as fallback for, if the corresponding rail type is not defined separately
 
|}
  
|}
   
Line 167: Line 222:
 
| 115
  
| 115
 
|}
  
|}
−  
   
 
==Railtype variables==
  
==Railtype variables==
   
−
{| class="t"
 +
{| class="wikitable sortable"
 
! name
  
! name
 
! value range
  
! value range
Line 182: Line 236:
 
| enhanced_tunnels
  
| enhanced_tunnels
 
| 0
  
| 0
−
| should custom tunnel entrances be modified other values than 0 might be returned
 +
| Reserved for future use, always returns 0 in OpenTTD. Should custom tunnel entrances be implemented, other values than 0 might be returned
 
|-
  
|-
 
| level_crossing_status
  
| level_crossing_status
Line 191: Line 245:
 
| 0 .. 5000000
  
| 0 .. 5000000
 
| for depots only: build date of the depot in days since 0
  
| for depots only: build date of the depot in days since 0
  +
|-
  +
| town_zone
  +
| [[NML:List of town zones|town zone]]
  +
| Town zone of the tile. (Only available for level crossings and depots.)
  +
|-
  +
| random_bits
  +
|
  +
| 2 pseudo-random bits, based on tile location
 
|}
  
|}
−  
   
 
==Railtype callbacks==
  
==Railtype callbacks==
   
−
For rail types a number of callbacks are used to define rail type graphics. Each should refer to a sprite set containing the relevant sprites. Refer to the example railtype grf for an example on what sprites are needed in what order.
 +
For rail types a number of callbacks are used to define rail type graphics. Each should refer to a sprite set containing the relevant sprites. Refer to the [[#Example sprites|example sprites]] or the example railtype grf in the NML repository, for an example on what sprites are needed in what order.
   
−
{| class="t"
 +
{| class="wikitable sortable"
 
! callbacks
  
! callbacks
 
! number of sprites
  
! number of sprites
Line 205: Line 266:
 
| gui
  
| gui
 
| 16
  
| 16
−
| 4 rail directions, autorail, depot, tunnel and convert rail sprites for rail menu
 +
| 4 rail directions, autorail, depot, tunnel and convert rail sprites for rail menu.
 
|-
  
|-
  +
| track_overlay<ref name=leftout>Either all or none of these sprites should be provided.</ref>
−
| track_overlay*
  
 
| 10
  
| 10
−
| 6 flat and 4 slope sprites. Track without landscape
 +
| 6 flat and 4 slope sprites. Track without landscape. Used in junctions, and also with path signals, if the "Show reserved tracks" option is enabled in the game settings.
 
|-
  
|-
−
| underlay*
 +
| underlay<ref name=leftout />
 
| 16
  
| 16
−
| 6 flat and 4 slope, one crossing WITH track, 5 junction pieces without track. Tracks with foundations but without landscape
 +
| 6 flat and 4 slope, one crossing WITH track, 5 junction pieces without track. Tracks with ballast but without landscape.
 
|-
  
|-
−
| tunnels*
 +
| tunnels<ref name=leftout />
 
| 4
  
| 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.
−
| 4 track sprites, one for each tunnel entrance. Only track with foundations, no landscape
  
 
|-
  
|-
 
| catenary_wire
  
| catenary_wire
Line 227: Line 288:
 
|
  
|
 
|-
  
|-
−
| bridge_surfaces*
 +
| bridge_surfaces<ref name=leftout />
 
| 6
  
| 6
 
|
  
|
 
|-
  
|-
−
| level_crossings*
 +
| level_crossings<ref name=leftout />
 
| 10
  
| 10
 
| For each direction: one track sprite and 4 sprites for road lights etc
  
| For each direction: one track sprite and 4 sprites for road lights etc
 
|-
  
|-
  +
| depots<ref name=depotr22854>{{ottd|1.2|r22854}} In OpenTTD prior to r22854, depot sprites would not be used if the above 'all or none' sprites were not supplied.</ref>
−
| depot
  
 
| 6
  
| 6
 
| 2 sprites for each south-ish, 1 sprite for each north-ish depot. Like original depots.
  
| 2 sprites for each south-ish, 1 sprite for each north-ish depot. Like original depots.
 
|-
  
|-
 
| fences
  
| fences
  +
| 8 / 16
  +
| x, y, vertical, horizontal, SW, SE, NE and NW slopes like original fences at sprite 1301. {{ottdp|1.6|no|ottdrev=r27343}} Since OpenTTD r27343 there is also a 16 sprites version, see below.
  +
|-
  +
| tunnel_overlay<ref name=tunnel_overlay>Above 'all or none' sprites must be supplied, if these sprites are to be used.</ref>
  +
| 4
  +
| If this callback is defined, tunnels for this railtype will be drawn differently. First, a grass underlay base sprite is drawn, then the 'tunnels'-sprite. Next, train sprites if applicable and then a grass overlay and finally the sprite from this type (tunnel_overlay). 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.
  +
* <code style:darkgreen>getbits(extra_callback_info1, 0, 8)</code>: 0 for normal tunnels, without any extra features (like tracks above). All other values are reserved for future extensions.
  +
|-
  +
| signals
 
| 8
  
| 8
  +
| {{ottd|1.3|r24367}} 1 sprite for each direction, order is SW(-facing), NE, NW, SE, E, W, S, N. For more information, see [[#signals|below]]
−
| x, y, vertical, horizontal, SW, SE, NE and NW slopes like original fences at sprite 1301
  
  +
|-
  +
| precombined<ref name=leftout />
  +
| 63
  +
| {{ottd|1.10}} 1 sprite for each combination of track on a tile. The index is determined by treating each track piece as a bit in the order X Y N S W E, subtracting 1, see [[#Precombined overlay sprites|below]]
 
|}
  
|}
   
  +
<references />
−
The entries marked by * are required. If a non-required callback is not implemented or fails, graphics from the fallback railtype (picked via the <code style="color:darkgreen">station_graphics</code> property) will be used instead.<br /> Note that there is no "default graphics"-callback.
  
  +
If a callback is not implemented or fails, graphics from the fallback railtype (picked via the <code style="color:darkgreen">station_graphics</code> property) will be used instead.<br />
  +
Note that there is no "default graphics"-callback.
  +
  +
===Example sprites===
  +
==== gui ====
  +
  +
[[File:railtype_gui.png]]
  +
  +
==== track_overlay ====
  +
  +
[[File:railtype_overlay.png]]
  +
  +
==== underlay ====
  +
  +
[[File:railtype_underlay.png]]
  +
  +
==== level_crossings ====
  +
  +
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.
  +
  +
{| class="wikitable"
  +
|-
  +
!Sprite number for X
  +
!Sprite number for Y
  +
!Useage
  +
|-
  +
|0
  +
| &nbsp; &nbsp;1
  +
| &nbsp; &nbsp;Rail overlay
  +
|-
  +
|2
  +
| &nbsp; &nbsp;3
  +
| &nbsp; &nbsp;North light
  +
|-
  +
|4
  +
| &nbsp; &nbsp;5
  +
| &nbsp; &nbsp;East light
  +
|-
  +
|6
  +
| &nbsp; &nbsp;7
  +
| &nbsp; &nbsp;West light
  +
|-
  +
|8
  +
| &nbsp; &nbsp;9
  +
| &nbsp; &nbsp;South light
  +
|}
  +
  +
[[File:railtype_levelcrossing.png]]
  +
  +
==== depots ====
  +
  +
{| class="wikitable
  +
|-
  +
!Sprite Number
  +
!Usage
  +
|-
  +
|0
  +
| &nbsp; &nbsp;NE wall for SE-entry depot.
  +
|-
  +
|1
  +
| &nbsp; &nbsp;Depot building for SE-entry depot.
  +
|-
  +
|2
  +
| &nbsp; &nbsp;NW wall for SW-entry depot.
  +
|-
  +
|3
  +
| &nbsp; &nbsp;Depot building for SW-entry depot.
  +
|-
  +
|4
  +
| &nbsp; &nbsp;Depot building for NE-entry depot.
  +
|-
  +
|5
  +
| &nbsp; &nbsp;Depot building for NW-entry depot.
  +
|}
  +
  +
==== fences ====
  +
  +
[[File:railtype_fences.png]]
  +
  +
{{ottdp|1.6|no|ottdrev=r27343}} 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 || {{ottdp|1.0|no|ottdrev=r19056}}
  +
|-
  +
| 1 || flat || Y || NE || {{ottdp|1.0|no|ottdrev=r19056}}
  +
|-
  +
| 2 || flat || left || E || {{ottdp|1.0|no|ottdrev=r19056}}
  +
|-
  +
| 3 || flat || upper || S || {{ottdp|1.0|no|ottdrev=r19056}}
  +
|-
  +
| 4 || SW || X || NW || {{ottdp|1.0|no|ottdrev=r19056}}
  +
|-
  +
| 5 || SE || Y || NE || {{ottdp|1.0|no|ottdrev=r19056}}
  +
|-
  +
| 6 || NE || X || NW || {{ottdp|1.0|no|ottdrev=r19056}}
  +
|-
  +
| 7 || NW || Y || NE || {{ottdp|1.0|no|ottdrev=r19056}}
  +
|-
  +
| 8 || flat || X || SE || {{ottdp|1.6|no|ottdrev=r27343}}
  +
|-
  +
| 9 || flat || Y || SW || {{ottdp|1.6|no|ottdrev=r27343}}
  +
|-
  +
| 10 || flat || left || W || {{ottdp|1.6|no|ottdrev=r27343}}
  +
|-
  +
| 11 || flat || upper || N || {{ottdp|1.6|no|ottdrev=r27343}}
  +
|-
  +
| 12 || SW || X || SE || {{ottdp|1.6|no|ottdrev=r27343}}
  +
|-
  +
| 13 || SE || Y || SW || {{ottdp|1.6|no|ottdrev=r27343}}
  +
|-
  +
| 14 || NE || X || SE || {{ottdp|1.6|no|ottdrev=r27343}}
  +
|-
  +
| 15 || NW || Y || SW || {{ottdp|1.6|no|ottdrev=r27343}}
  +
|}
  +
  +
==== tunnel_overlay ====
  +
  +
If this callback is defined, tunnels for this railtype will be drawn differently.
  +
  +
First, a grass underlay base sprite is drawn, then the 'tunnels'-sprite. Next, train sprites if applicable and then a grass overlay and finally the sprite from this callback. 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: [[File:RailtypeTunnelExample.png]]
  +
  +
==== signals ====
  +
  +
This callback 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. If resolving fails or results in an empty sprite group, the matching base set sprite will be used instead.
  +
  +
Variable <code style:darkgreen>extra_callback_info2</code> contains the state, variant and type of the signal. Use the builtin function <code style:darkgreen>getbits()</code> in the following fashion to access the information:
  +
<ul><li>
  +
Signal state: <code style:darkgreen>getbits(extra_callback_info2, 0, 8)</code>:
  +
{| |-
  +
! Result !! Meaning
  +
|-
  +
| 00 || Red signal
  +
|-
  +
| 01 || Green signal
  +
|-
  +
| all other values || Reserved
  +
|}
  +
</li><li>
  +
Signal variant: <code style:darkgreen>getbits(extra_callback_info2, 8, 8)</code>:
  +
{| |-
  +
! Result !! Meaning
  +
|-
  +
| 00 || Light (electric) signal
  +
|-
  +
| 01 || Semaphore
  +
|-
  +
| all other values || Reserved
  +
|}
  +
</li><li>
  +
Signal type: <code style:darkgreen>getbits(extra_callback_info2, 16, 8)</code>:
  +
{| |-
  +
! Result !! 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
  +
|}
  +
</li></ul>
  +
Variable <code style:darkgreen>extra_callback_info1</code> contains the drawing context.
  +
<ul><li>
  +
<code style:darkgreen>getbits(extra_callback_info1, 0, 8)</code>:
  +
{| |-
  +
! Result !! Meaning
  +
|-
  +
| 0 || Signal is drawn in a viewport, i.e. on the map.
  +
|-
  +
| 0x10 || 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
  +
|}
  +
</li></ul>
  +
  +
====Precombined overlay sprites====
  +
  +
[[File:Rails_combined.png]]
   
−
===Example===
 +
===Example code===
   
 
A typical implementation for railtypes can look like:
  
A typical implementation for railtypes can look like:
Line 260: Line 525:
 
new_engine_text: string(STR_NEW_ENGINE);
  
new_engine_text: string(STR_NEW_ENGINE);
 
compatile_railtype_list: ["SHIN","RAIL","ELRL"]; // Tracks of rail and electrified rail are compatible
  
compatile_railtype_list: ["SHIN","RAIL","ELRL"]; // Tracks of rail and electrified rail are compatible
−
powered_railtype_list: ["ELRL","SHIN"]; // But we got only power when we have electricity
 +
powered_railtype_list: ["ELRL","SHIN"]; // But we only have power when we have electricity
 
railtype_flags: bitmask(RAILTYPE_FLAG_NO_LEVEL_CROSSING); // High speed tracks should not have level crossings
  
railtype_flags: bitmask(RAILTYPE_FLAG_NO_LEVEL_CROSSING); // High speed tracks should not have level crossings
 
curve_speed_multiplier: 1;
  
curve_speed_multiplier: 1;
Line 272: Line 537:
 
underlay: ground_switch_underlay; // defines the usual tracks and the underlay for junctions
  
underlay: ground_switch_underlay; // defines the usual tracks and the underlay for junctions
 
level_crossings: level_crossing_switch; // defines level crossings including traffic lights and blocking bars
  
level_crossings: level_crossing_switch; // defines level crossings including traffic lights and blocking bars
−
tunnels: tunnel_switch; // defines the tracks drawn on a funnel tile
 +
tunnels: tunnel_switch; // defines the tracks drawn on a tunnel tile
 
depots: depot_switch_electric; // defines the depot sprites
  
depots: depot_switch_electric; // defines the depot sprites
 
bridge_surfaces: bridge_terrain_switch; // defines the overlay drawn over bridges
  
bridge_surfaces: bridge_terrain_switch; // defines the overlay drawn over bridges
 
fences: fences_set; // defines the look of fences
  
fences: fences_set; // defines the look of fences
−
// we don't define catenery wire and pylons, thus we use the default which comes with the base graphics.
 +
// we don't define catenary wire and pylons, thus we use the default which comes with the base graphics.
 
}
  
}
 
}
  
}

Latest revision as of 15:20, 9 December 2023

Props, Vars and CBs

Railtypes can only be defined in OpenTTD Supported by OpenTTD 1.0 (r18969)1.0 or later.


Railtype IDs

Railtype IDs are limited to 64 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..63 range. If other railtype GRFs are loaded, it may be that there are not enough railtype slots available. To prevent your entire NewGRF from being deactivated with the 'Attempt to use invalid ID'-error, you can use the following code: 

if (railtype_available("LABL") || loading_stage == LOADING_STAGE_RESERVE)
    ... item definition ...
} else if (loading_stage == LOADING_STAGE_ACTIVATE) {
    ... warning / error ...
}

The warning / error is optional, but can be used to inform the user about the missing railtypes.

Vehicle and Railtype availability

Vehicle and railtype availability and compatibility is influenced by multiple properties. Generally, the vehicle defines which railtype it is, and the railtypes define the compatibility between each other.

  • A vehicle exists, if its railtype (train property track_type) is defined. Otherwise the vehicle is disabled.
  • When a vehicle is introduced, it always introduces its railtype (train property track_type).
  • A railtype is introduced, if at least one of the following conditions is met:
    • A vehicle is introduced, that references the railtype (train property track_type).
    • Another railtype is introduced, that references the railtype via the introduced railtype list (railtype propery introduces_railtype_list).
    • The introduction date (railtype property introduction_date) is passed and all required railtypes (railtype property requires_railtype_list ) are available.

Via railtype property compatible_railtype_list multiple railtypes can be defined, which shall be considered equivalent to a railtype. This affects the interpretation of train property track_type. If train property track_type references an undefined railtype, then railtype property compatible_railtype_list is checked for all defined railtypes, whether the vehicle can be reassigned to some other railtype. Otherwise the vehicle is disabled. However note also that alternative_railtype_list provides an alternative/complementary approach to handling undefined railtypes.

Note that when routing trains onto railtypes, the compatibility is only evaluated for the lead engine of a consist. This means that trains will run on incompatible rail types if they are in a consist where the lead engine is compatible with the rail type. This applies to both engines and wagons.


Railtype properties

property value range comment
label 4-byte string names of default rail types: "RAIL", "ELRL", "MONO", "MGLV". See the List of railtype labels in the NewGRF Specs for currently defined custom labels.
introduction_date date(yyyy,mm,dd)

Supported by OpenTTD 1.1 (r21842)1.1 Valid range for yyyy is 0 ... 5000000.

name string Name of this railtype
toolbar_caption string Supported by OpenTTD 1.2 (23129)1.2 Not supported by TTDPatch Caption of the build rail toolbar. In earlier versions this is the same as the 'name'
menu_text string Shown in the dropdown menu for all railtypes
build_window_caption string Caption of the build vehicle window
autoreplace_text string String for the autoreplace window
new_engine_text string String for the "We have invented a new <rail type> engine" news message
compatible_railtype_list list of railtype labels Provide a list of rail types that trains of this type can also run on. e.g. ["RAIL", "ELRL", "MONO"]. Note that when routing trains, the compatibility is only evaluated for the lead engine of a consist. This means that trains will run on incompatible rail types if they are in a consist where the lead engine is compatible with the rail type. This applies to both engines and wagons.
powered_railtype_list list of railtype labels Provide a list of rail types that trains of this type are powered on.
railtype_flags bitmask(RAILTYPE_FLAG_XXX, ...)
CATENARY
Enable catenary
NO_LEVEL_CROSSING
Disable level crossings
HIDDEN Supported by OpenTTD 1.91.9
Hides railtype from player
PRECOMBINED Supported by OpenTTD 1.101.10
Enable use of precombined overlay sprites
ALLOW_90DEG Supported by OpenTTD 1.101.10
Always allow 90 degree turns
DISALLOW_90DEG Supported by OpenTTD 1.101.10
Always prohibit 90 degree turns (takes precedence over ALLOW_90DEG)
curve_speed_multiplier 0...255 max curve speed is defined as multiple of the base curve speed (see below)
station_graphics RAILTYPE_STATION_NORMAL, RAILTYPE_STATION_MONORAIL, RAILTYPE_STATION_MAGLEV Type of station graphics to use for the default stations
construction_cost 0 ... 65525

Supported by OpenTTD 1.1 (r19307)1.1 per piece of track as multiplier to PR_BUILD_RAIL base cost. Default cost factors are 8, 12, 16 and 24 for RAIL, ELRL, MONO and MGLV.

speed_limit 0 ... 65525 km/h (speed units) A speed limit of 0 means unlimited speed
acceleration_model ACC_MODEL_RAIL, ACC_MODEL_MONORAIL, ACC_MODEL_MAGLEV ACC_MODEL_RAIL and ACC_MODEL_MONORAIL behave the same currently
map_colour 0 ... 255

Supported by OpenTTD 1.1 (r19307)1.1 entry in the colour palette.

requires_railtype_list list of railtype labels

Supported by OpenTTD 1.1 (r21842)1.1 List of rail types on that need to be available to the company of the player for this rail type to be introduced at (or after) the introduction date. This limit does not apply when the rail type is introduced by the introduction of a vehicle.

introduces_railtype_list list of railtype labels

Supported by OpenTTD 1.1 (r21841)1.1 List of rail types that get introduced when this rail type is introduced. For example, to make sure that when a fast rail type is introduced the slow variant exists.

sort_order 0 ... 255

Supported by OpenTTD 1.1 (r21866)1.1 number which defines the sort order among rail types. If this entry is not defined, it gets assigned sort order n*10+7 for the n-th railtype.

maintenance_cost 0 ... 255

Supported by OpenTTD 1.2 (r23415)1.2 Maintenance cost factor for each piece of tracks of this railtype. Default cost factors are 8, 12, 16 and 24 for RAIL, ELRL, MONO and MGLV.

alternative_railtype_list list of railtype labels

Supported by OpenTTD 1.2 (r23758)1.2 List of rail types which this rail type will act as fallback for, if the corresponding rail type is not defined separately

Sort order

The sort_order influences the sort order of the drop down lists with rail types. Default values are as follows:

Value Meaning
07 normal rail
17 electrified rail
27 monorail
37 maglev
n7 railtype #n

Thus the rail type that (internally) gets index 8 will get a default value of 87. These defaults are to keep the ordering when this property is not supported as they were.

Base speeds for curves

The base speeds relevant for the curve_speed_multiplier are:

curve length base speed [km/h]
0 (90 degree turn) 30
1 44
2 55
3 66
4 75
5 84
6 91
7 98
8 103
9 108
10 111
11 114
12+ 115

Railtype variables

name value range comment
terrain_type TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
enhanced_tunnels 0 Reserved for future use, always returns 0 in OpenTTD. Should custom tunnel entrances be implemented, other values than 0 might be returned
level_crossing_status LEVEL_CROSSING_CLOSED, LEVEL_CROSSING_OPEN
build_date 0 .. 5000000 for depots only: build date of the depot in days since 0
town_zone town zone Town zone of the tile. (Only available for level crossings and depots.)
random_bits 2 pseudo-random bits, based on tile location

Railtype callbacks

For rail types a number of callbacks are used to define rail type graphics. Each should refer to a sprite set containing the relevant sprites. Refer to the example sprites or the example railtype grf in the NML repository, for an example on what sprites are needed in what order.

callbacks number of sprites meaning
gui 16 4 rail directions, autorail, depot, tunnel and convert rail sprites for rail menu.
track_overlay[1] 10 6 flat and 4 slope sprites. Track without landscape. Used in junctions, and also with path signals, if the "Show reserved tracks" option is enabled in the game settings.
underlay[1] 16 6 flat and 4 slope, one crossing WITH track, 5 junction pieces without track. Tracks with ballast but without landscape.
tunnels[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.
catenary_wire 28
catenary_pylons 8
bridge_surfaces[1] 6
level_crossings[1] 10 For each direction: one track sprite and 4 sprites for road lights etc
depots[2] 6 2 sprites for each south-ish, 1 sprite for each north-ish depot. Like original depots.
fences 8 / 16 x, y, vertical, horizontal, SW, SE, NE and NW slopes like original fences 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.
tunnel_overlay[3] 4 If this callback is defined, tunnels for this railtype will be drawn differently. First, a grass underlay base sprite is drawn, then the 'tunnels'-sprite. Next, train sprites if applicable and then a grass overlay and finally the sprite from this type (tunnel_overlay). 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.
  • getbits(extra_callback_info1, 0, 8): 0 for normal tunnels, without any extra features (like tracks above). All other values are reserved for future extensions.
signals 8 Supported by OpenTTD 1.3 (r24367)1.3 1 sprite for each direction, order is SW(-facing), NE, NW, SE, E, W, S, N. For more information, see below
precombined[1] 63 Supported by OpenTTD 1.101.10 1 sprite for each combination of track on a tile. The index is determined by treating each track piece as a bit in the order X Y N S W E, subtracting 1, see below
  1. ↑ 1.0 1.1 1.2 1.3 1.4 1.5 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.

If a callback is not implemented or fails, graphics from the fallback railtype (picked via the station_graphics property) will be used instead.
Note that there is no "default graphics"-callback.

Example sprites

gui

Railtype gui.png

track_overlay

Railtype overlay.png

underlay

Railtype underlay.png

level_crossings

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

depots

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

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_overlay

If this callback is defined, tunnels for this railtype will be drawn differently.

First, a grass underlay base sprite is drawn, then the 'tunnels'-sprite. Next, train sprites if applicable and then a grass overlay and finally the sprite from this callback. 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

signals

This callback 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. If resolving fails or results in an empty sprite group, the matching base set sprite will be used instead.

Variable extra_callback_info2 contains the state, variant and type of the signal. Use the builtin function getbits() in the following fashion to access the information:

  • Signal state: getbits(extra_callback_info2, 0, 8):
    Result Meaning
    00 Red signal
    01 Green signal
    all other values Reserved
  • Signal variant: getbits(extra_callback_info2, 8, 8):
    Result Meaning
    00 Light (electric) signal
    01 Semaphore
    all other values Reserved
  • Signal type: getbits(extra_callback_info2, 16, 8):
    Result 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

Variable extra_callback_info1 contains the drawing context.

  • getbits(extra_callback_info1, 0, 8):
    Result Meaning
    0 Signal is drawn in a viewport, i.e. on the map.
    0x10 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

Precombined overlay sprites

Rails combined.png

Example code

A typical implementation for railtypes can look like: 

 item(FEAT_RAILTYPES, elrail, 0x01) {
     property {
         label:                      "SHIN";
         name:                       string(STR_EL_RAIL);
         menu_text:                  string(STR_EL_RAIL);
         build_window_caption:       string(STR_BUILD_CAPTION);
         autoreplace_text:           string(STR_AUTOREPLACE);
         new_engine_text:            string(STR_NEW_ENGINE);
         compatile_railtype_list:    ["SHIN","RAIL","ELRL"];                   // Tracks of rail and electrified rail are compatible
         powered_railtype_list:      ["ELRL","SHIN"];                          // But we only have power when we have electricity
         railtype_flags:             bitmask(RAILTYPE_FLAG_NO_LEVEL_CROSSING); // High speed tracks should not have level crossings
         curve_speed_multiplier:     1;
         station_graphics:           RAILTYPE_STATION_MAGLEV;                  // We want the most modern stations
         construction_cost:          32;                                       // should be pretty steep
         speed_limit:                500 km/h;
         acceleration_model:         ACC_MODEL_RAIL;                           // This is still rail, though
     }
     graphics {
         track_overlay:   ground_switch_overlay;     // defines the sprites drawn as overlay for junctions and highlight
         underlay:        ground_switch_underlay;    // defines the usual tracks and the underlay for junctions
         level_crossings: level_crossing_switch;     // defines level crossings including traffic lights and blocking bars
         tunnels:         tunnel_switch;             // defines the tracks drawn on a tunnel tile
         depots:          depot_switch_electric;     // defines the depot sprites
         bridge_surfaces: bridge_terrain_switch;     // defines the overlay drawn over bridges
         fences:          fences_set;                // defines the look of fences
         // we don't define catenary wire and pylons, thus we use the default which comes with the base graphics.
     }
 }

The switches and graphics blocks are defined in the usual way as described in sections switches, random switches and graphics block sections.

Retrieved from ‘https://newgrf-specs.tt-wiki.net/index.php?title=NML:Railtypes&oldid=4675’