NML:Railtypes

NewGRF Meta Language

Preface

Getting started

Graphics files

Blocks

Units

Expressions

Elementary values

Builtin functions

Language files

Lists of props, vars and CBs

Warnings

Additional references

NewGRF compatibility

Deprecated syntax

Changes from NML 0.2 to 0.3

Changes from NML 0.3 to 0.4

Changes from NML 0.4 to 0.5

Vehicles, Stations, Canals, Bridges, Towns, Houses, Industries (Tiles), Cargos, Airports+Tiles, Objects, Railtypes, Roadtypes, Tramtypes, Terrain

NML Tutorial

Props, Vars and CBs

General

• variables

Vehicles

• common props | vars | CBs
• train | roadveh | ship | aircr props

Stations

• properties | variables | callbacks

Canals

• properties | variables | callbacks

Bridges

• properties | variables | callbacks

Towns

Houses

• properties | variables | callbacks

Industries

• common variables
• industry props | vars | CBs
• tile props | vars | CBs

Cargos

• properties | variables | callbacks

Airports

• airport props | vars | CBs
• tile props | vars | CBs

Objects

• properties | variables | callbacks

Railtypes

• properties | variables | callbacks

Roadtypes

• properties | variables | callbacks

Tramtypes

• properties | variables | callbacks

Railtypes can only be defined in OpenTTD 1.0 or later.

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)	1.1 Valid range for yyyy is 0 ... 5000000.
name	string	Name of this railtype
toolbar_caption	string	1.2  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"]
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, ...)	XXX = [CATENARY | NO_LEVEL_CROSSING] Flags enable catenary and/or disable level crossings.
curve_speed_multiplier	0...65525	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	1.1 per piece of track as multiplier to PR_BUILD_RAIL base cost.
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	1.1 entry in the colour palette.
requires_railtype_list	list of railtype labels	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	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	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		1.2 Maintenance cost factor for each piece of tracks of this railtype
alternative_railtype_list	list of railtype labels	1.2 List or 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	should custom tunnel entrances be modified 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

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.

callbacks	number of sprites	meaning
gui	16	4 rail directions, autorail, depot, tunnel and convert rail sprites for rail menu
track_overlay*	10	6 flat and 4 slope sprites. Track without landscape
underlay*	16	6 flat and 4 slope, one crossing WITH track, 5 junction pieces without track. Tracks with ballast but without landscape
tunnels*	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*	6
level_crossings*	10	For each direction: one track sprite and 4 sprites for road lights etc
depot	6	2 sprites for each south-ish, 1 sprite for each north-ish depot. Like original depots.
fences	8	x, y, vertical, horizontal, SW, SE, NE and NW slopes like original fences at sprite 1301

Some of the graphics callbacks are marked by a *. You should either implement all or none of these, failing to do so will result in undefined behaviour. 1.2 In OpenTTD before r22854, depot graphics require the *-marked entries to be present in order 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

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 got only 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 funnel 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 catenery 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.