NML:Tramtypes

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

Tramtypes can only be defined in OpenTTD 1.10 and NML 0.5 or later.

Tramtype IDs

Tramtypes and Roadtypes share a pool of 63 IDs. Either feature can use as many IDs as needed (i.e. it is not limited to 32 per type), but both features combined are limited to 63 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..62 range. If other tramtype/roadtype GRFs are loaded, it may be that there are not enough 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 (tramtype_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 tramtypes.

Vehicle and Tramtype availability

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

• Remember that the road vehicle flag 'ROADVEH_FLAG_TRAM' must be set in order for a road vehicle to be considered a tram.
• A vehicle exists, if its tramtype (road vehicle property tram_type) is defined. Otherwise the vehicle is disabled.
• When a vehicle is introduced, it always introduces its tramtype (road vehicle property tram_type).
• A tramtype is introduced, if at least one of the following conditions is met:
  • A vehicle is introduced, that references the tramtype (road vehicle property tram_type).
  • Another tramtype is introduced, that references the tramtype via the introduced tramtype list (tramtype property introduces_tramtype_list).
  • The introduction date (tramtype property introduction_date) is passed and all required tramtypes (tramtype property requires_tramtype_list ) are available.

Via tramtype property powered_tramtype_list multiple tramtypes can be defined, which shall be considered equivalent to a tramtype. This affects the interpretation of road vehicle property tram_type. If road vehicle property tram_type references an undefined tramtype, then tramtype property powered_tramtype_list is checked for all defined tramtypes, whether the vehicle can be reassigned to some other tramtype. Otherwise the vehicle is disabled.

Tramtype properties

property	value range	comment
label	4-byte string	names of default tram types: "RAIL" and "ELRL". See the List of tramtype labels in the NewGRF Specs for currently defined custom labels.
introduction_date	date(yyyy,mm,dd)	Valid range for yyyy is 0 ... 5000000.
name	string	Name of this tramtype
toolbar_caption	string	Caption of the build tram toolbar. In earlier versions this is the same as the 'name'
menu_text	string	Shown in the dropdown menu for all tramtypes
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 <tram type> engine" news message
powered_tramtype_list	list of tramtype labels	Provide a list of tram types that tram vehicles of this type are powered on, e.g. ["RAIL", "ELRL"]. Note that there is no "compatible_tramtype_list" since there is no difference between "powered" and "compatible" for tramtypes
tramtype_flags	bitmask(TRAMTYPE_FLAG_XXX, ...)	CATENARY Enable catenary NO_LEVEL_CROSSING Disable level crossings NO_HOUSES Disallows house construction HIDDEN Hides the tramtype from players, but remains available to towns...which can't use them TOWN_BUILD Towns don't build tramtracks...so not sure what the purpose of this is
construction_cost	0 ... 65525	Per piece of track as multiplier to PR_BUILD_ROAD base cost. Default cost factors are 8 and 16 for RAIL and ELRL, respectively.
speed_limit	0 ... 65525 km/h (speed units)	A speed limit of 0 means unlimited speed
map_colour	0 ... 255	Entry in the colour palette.
requires_tramtype_list	list of tramtype labels	List of tram types that need to be available to the company of the player for this tram type to be introduced at (or after) the introduction date. This limit does not apply when the tram type is introduced by the introduction of a vehicle.
introduces_tramtype_list	list of tramtype labels	List of tram types that get introduced when this tram type is introduced. For example, to make sure that when a fast tram type is introduced the slow variant exists.
sort_order	0 ... 255	Number which defines the sort order among tram types. If this entry is not defined, it gets assigned sort order n*10+7 for the n-th tramtype.
maintenance_cost	0 ... 255	Maintenance cost factor for each piece of tram of this tramtype. Default cost factors are 16 and 24 for RAIL and ELRL, respectively.
alternative_tramtype_list	list of tramtype labels	List of tram types which this tram type will act as fallback for, if the corresponding tram type is not defined separately

Sort order

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

Value	Meaning
07	normal tram
17	electrified tram
n7	tramtype #n

Thus the tram 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.

Tramtype 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
random_bits		2 pseudo random bits

Tramtype callbacks

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

callbacks	number of sprites	meaning
gui	12	6 gui icons, 6 cursors
track_overlay	19	11 track combinations, 4 slopes, and 4 dead ends. These sprites are required
underlay	19	11 track combinations, 4 slopes, and 4 dead ends. These sprites are required
catenary_front	29	11 track combinations, 4 slopes, 4 dead ends, 4 tunnels, 2 bridge middle, 4 bridge ramps
catenary_back	29	11 track combinations, 4 slopes, 4 dead ends, 4 tunnels (unused), 2 bridge middle, 4 bridge ramps
bridge_surfaces	6	2 bridge middle, 4 bridge ramps
depots	6	If not present, the default depot sprites (depending on catenary flag) plus track overlay are drawn. If present, the depot sprites are expected to include track overlay graphics.

Note that there is no "default" graphics callback.

Example sprites

gui

underlay

overlay

catenary_front

catenary_back

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.

bridge_surfaces

Example code

A typical implementation for tramtypes can look like:

 item(FEAT_TRAMTYPES, dctram, 0x01) {
     property {
         label:                      "DCTM";
         name:                       string(STR_DC_TRAM);
         menu_text:                  string(STR_DC_TRAM);
         build_window_caption:       string(STR_BUILD_CAPTION);
         autoreplace_text:           string(STR_AUTOREPLACE);
         new_engine_text:            string(STR_NEW_ENGINE);
         powered_tramtype_list:      ["DCTM","ELRL"];                          // These trams are compatible with other electric trams
         tramtype_flags:             bitmask(TRAMTYPE_FLAG_CATENARY);          // These tramways require catenary
         construction_cost:          24;                                       // Electric tramways are pricey
         speed_limit:                50 km/h;
     }
     graphics {
         underlay:        ground_switch_underlay;    // defines the tramtrack underlay
         overlay:         track_overlay_switch;      // defines the tramtrack overlay
         tunnels:         tunnel_switch;             // defines the track drawn on a tunnel tile
         depots:          depot_switch;              // defines the depot sprites
         bridge_surfaces: bridge_terrain_switch;     // defines the overlay drawn over bridges depending on climate
     }
 }

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