NML:Roadstops

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, Roadstops, Canals, Towns, Houses, Industries (Tiles), Cargos, Airports+Tiles, Objects, Railtypes, Roadtypes, Tramtypes, Bridges, Badges, Terrain

NML Tutorial

Props, Vars and CBs

General

• variables

Vehicles

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

Stations

• properties | variables | callbacks

Roadstops

• properties | variables | callbacks

Canals

• 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

Bridges

• properties | variables | callbacks

Badges

• properties | variables |callbacks

Road stops can only be defined in OpenTTD 14.0 or later.

Road stop IDs

OpenTTD supports 64000 road stop types per game.

Rpad stop IDs are NewGRF-local and can therefore freely be chosen within the ID ranges.

A road stop is allocated by setting the 'class'-property, which should therefore be set first.

Road stop sprite layouts should always set a suitable ground tile sprite, and should not assume that a road type GRF will provide suitable overlay sprites. Suggested ground sprite IDs include: GROUNDSPRITE_ROAD_X/GROUNDSPRITE_ROAD_Y (straight road on grass), 1314/1313 (straight road with pavement), 2692 - 2695 (bay road stop ground).

Road stop properties

property	value range	comment
class	String literal of length 4	This property must be set first, before any other properties or graphics. Road stops belonging to the same class are grouped in the GUI. There is one special class: "WAYP": 15.0  The road stop type will be shown in the waypoint construction window, instead of the station construction window. 15  Station classes which start with the byte FF are considered waypoint classes, and will appear in the waypoint construction window instead of the station construction window.
classname	string	You only need to set this for one road stop in every class.
name	string
availability_type	RST_AVAILABILITY_TYPE_XXX	XXX = [PASSENGER | FREIGHT | ALL] The default value is RST_AVAILABILITY_TYPE_ALL
draw_mode	bitmask(RST_DRAW_FLAG_XXX, ...)	See list of draw mode flags The default value is bitmask(RST_DRAW_FLAG_BAY_ROAD, RST_DRAW_FLAG_DRIVE_THROUGH_ROAD_OVERLAY)
cargo_random_triggers	cargo bitmask	Cargo types, which will trigger re-randomization when delivered, loaded or unloaded at the station.
animation_info	Array [ANIMATION_XXX, frame-count]	XXX = [LOOPING | NON_LOOPING], 1..253 frames
animation_speed	0..16	Speed of animation, see animation speed table for the meaning of the values.
animation_triggers	bitmask(ANIM_TRIGGER_ROAD_STOP_XXX, ...)	See list of animation triggers
general_flags	bitmask(RST_GENERAL_FLAG_XXX, ...)	See list of general flags
cost_multipliers	[build_cost, clear_cost]	Build and clear cost multipliers, 16 is the same as a non-NewGRF road stop
badges	Array of badge labels from the badgetable.	Since 15.0
heights	Array of unsigned ints	Since 15.0 NML 0.8.1 Each element of array corresponds to one view. Specifies the bridge height so bridges can be build above the road stop. The bridge height defines minimum clearances required for a bridge for the sprite layouts of this road stop (or zero to not allow any bridge). Values are given in "height level" units (1 level == 8px).
blocked_pillars	Array of bitmask(BRIDGE_PILLAR_XXX, ...)	Since 15.0 NML 0.8.1 Each element of array corresponds to one view. Allows information to provided about blocked bridge pillars to assist the game in hiding pillars if necessary depending on what is above the road stop tile. Blocking a pillar prevents the pillar from being drawn. It does not prevent the road stop being bridgeable. See list of bridge pillar flags.

List of draw mode flags

Name	Meaning
RST_DRAW_FLAG_BAY_ROAD	Draw road type ground sprite for bay stops.
RST_DRAW_FLAG_DRIVE_THROUGH_ROAD_OVERLAY	Draw road overlays for drive-through stops.
RST_DRAW_FLAG_WAYPOINT_GROUND	15.0  Draw spritelayout ground sprite on top of underlying road (if unset, the spritelayout ground sprite is not drawn).

List of general flags

Name	Meaning
RST_GENERAL_FLAG_RANDOM_ANIMATION	Animation callback requires random bits in variable extra_callback_info1.
RST_GENERAL_FLAG_NO_CATENARY	Do not show catenary graphics.
RST_GENERAL_FLAG_DRIVE_THROUGH_ONLY	Only allow drive-through stops (not bay stops).
RST_GENERAL_FLAG_NO_AUTO_ROAD_CONNECTION	Do not automatically build connecting road pieces.
RST_GENERAL_FLAG_BUILD_MENU_ROAD_ONLY	Only show in the road build menu (not tram).
RST_GENERAL_FLAG_BUILD_MENU_TRAM_ONLY	Only show in the tram build menu (not road).
RST_GENERAL_FLAG_DRAW_MODE_REGISTER	15.0  Read the road stop draw mode from variable 0x100 (set using STORE_TEMP), this overrides the draw_mode property.

List of bridge pillar flags

Name	Meaning
BRIDGE_PILLAR_CORNER_W	Tile layout blocks a pillar on the west corner of the tile.
BRIDGE_PILLAR_CORNER_S	Tile layout blocks a pillar on the south corner of the tile.
BRIDGE_PILLAR_CORNER_E	Tile layout blocks a pillar on the east corner of the tile.
BRIDGE_PILLAR_CORNER_N	Tile layout blocks a pillar on the north corner of the tile.
BRIDGE_PILLAR_EDGE_NE	Tile layout blocks a wall on the north east side of the tile.
BRIDGE_PILLAR_EDGE_SE	Tile layout blocks a wall on the south east side of the tile.
BRIDGE_PILLAR_EDGE_SW	Tile layout blocks a wall on the south west side of the tile.
BRIDGE_PILLAR_EDGE_NW	Tile layout blocks a wall on the north west side of the tile.

Road stop variables

Base station variables

The following variables are shared between road stops, stations and airports:

name	value range	comment
random_bits_station	0..65535	16 random bits, shared between all station sections (rail station sections, airports, ...)
had_vehicle_of_type	bitmask(HAD_VEHICLE_OF_TYPE_XXX, ...)	Bitmask of vehicle types that have visited the station. XXX = [TRAIN | BUS | TRUCK | AIRCRAFT | SHIP].
is_waypoint	[0 | 1]	Whether the station is a waypoint
facilities	bitmask(FACILITY_XXX, ...)	Bitmask of facilities associated with the station. XXX = [TRAIN | TRUCK_STOP | BUS_STOP | AIRPORT | DOCK].
airport_type	AIRPORTTYPE_XXX	Type of airport, contains a bogus value if the station has no airport. XXX = [SMALL | LARGE | HELIPORT | OILRIG].
build_date	date(yyyy,mm,dd)	Date when the station was built. Is clamped to the 1920-2099 range.

The following variables are also shared with stations and airports. They all require a single argument: a cargo type from your cargo translation table.

name	value range	comment
cargo_amount_waiting	0..32767	Units of cargo of waiting
cargo_rating	0..100	Rating for this cargo type (in %)
cargo_time_since_pickup	0..255	Time since the cargo was last picked up. 1 unit equals 185 ticks, or about 2.5 game days.
cargo_time_en_route	0..255	Time this cargo has spent en-route. 1 unit equals 185 ticks, or about 2.5 game days.
cargo_last_vehicle_speed	0..255	Speed of the last vehicle picking up this cargo type. The unit depends on the type of vehicle. For trains and road vehicles, one unit is 1 km/h; for ships, it's 0.5 km/h; for aircraft, it's 8 mph. If the max. speed is above 255 speed units, 255 is used instead. 0 if no vehicle as picked up the cargo type yet.
cargo_last_vehicle_age	0..255	Age of the last vehicle picking up this cargo type, in years. 255 if no vehicle has picked up the cargo type yet.
cargo_accepted	[0 | 1]	1 if this cargo type is currently being accepted at the station, 0 otherwise.
cargo_accepted_ever	[0 | 1]	1 if this cargo type has ever been accepted at the station, 0 otherwise.
cargo_accepted_last_month	[0 | 1]	1 if this cargo type was accepted last month at the station, 0 otherwise.
cargo_accepted_this_month	[0 | 1]	1 if this cargo type was accepted this month at the station, 0 otherwise.
cargo_accepted_bigtick	[0 | 1]	1 if this cargo type was accepted at the station since the last periodic processing, which happens every 250 ticks. 0 otherwise.

Variables without a parameter

name	value range	comment
view	RST_VIEW_XXX	The view/rotation of the road stop. See list of road stop views
stop_type	RST_TYPE_XXX	XXX = [BUS | TRUCK | 15 WAYPOINT]
terrain_type	TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
tile_slope	SLOPE_XXX	See tile slopes for an overview of possible values
has_road	[0 | 1]	1 if this road stop has road
has_tram	[0 | 1]	1 if this road stop has tram
road_type	[Road type | 0xFF]	Entry from roadtype translation table, or 0xFF if there is no road
tram_type	[Tram type | 0xFF]	Entry from tramtype translation table, or 0xFF if there is no tram
animation_frame	0 .. (frame_count - 1)	Current animation frame, with the maximum defined in the animation_info property.
town_manhattan_dist		Manhattan distance to the nearest town
town_euclidean_dist		Euclidean distance to the nearest town
town_zone	town zone	The town zone of the current tile. The town zone from the closest town (measured in manhattan distance) is used.
company_num	0 ... 14	Company number of the roadstop owner.
company_type	PLAYERTYPE_XX	PLAYERTYPE_HUMAN human player PLAYERTYPE_AI AI player PLAYERTYPE_HUMAN_IN_AI human managing AI company PLAYERTYPE_AI_IN_HUMAN AI managing human company OpenTTD only uses PLAYERTYPE_HUMAN and PLAYERTYPE_AI. If you cheat yourself to be part of an AI company OpenTTD will still report PLAYERTYPE_AI for the company with yourself and the AI and it'll report PLAYERTYPE_HUMAN for the now uncontrolled company.
company_colour1	COLOUR_XXX	Refer to the table here for possible values.
company_colour2	COLOUR_XXX	Same as company_colour1, if no 2nd company colour is chosen. Refer to the table here for possible values.
random_bits_tile	0..255	8 random bits, specific to this road stop tile.
waiting_triggers	0..255	Random triggers waiting to be matched. (see Random switch)
drawn_in_gui	[0 | 1]	15  1 if this road stop is being drawn in the build window

Variables that require one or more parameters

name	arguments	value range	comment
nearby_tile_slope	x, y offset (-8..7)		See tile_slope
nearby_tile_is_water	x, y offset (-8..7)	0 .. 1	Is the given tile a water tile?
nearby_tile_terrain_type	x, y offset (-8..7)		See terrain_type
nearby_tile_water_class	x, y offset (-8..7)	WATER_CLASS_XXX	XXX = [NONE | SEA | CANAL | RIVER] Note that tiles for which nearby_tile_is_water is 0 may still have a water class, e.g. industry tiles with water beneath them.
nearby_tile_height	x, y offset (-8..7)	0 .. 120	The minimum height of the given tile. 8 units correspond to one height level
nearby_tile_class	x, y offset (-8..7)	Tile class
nearby_tile_animation_frame	x, y offset (-8..7)		See animation_frame. Only valid for tiles of the same object.
nearby_tile_is_road_stop	x, y offset (-8..7)	0 .. 1	Is the given tile a road stop?
nearby_tile_road_stop_id	x, y offset (-8..7)		If nearby_tile_same_grf is true, ID of a road stop on a nearby tile
nearby_tile_same_grf	x, y offset (-8..7)	0 .. 1	Is a road stop on a nearby tile defined by the same GRF?
nearby_tile_other_grf	x, y offset (-8..7)	0 .. 1	Is a road stop on a nearby tile defined by another GRF?
nearby_tile_original_gfx	x, y offset (-8..7)	0 .. 1	Is a road stop on a nearby tile using original graphics?
nearby_tile_same_station	x, y offset (-8..7)	0 .. 1	Is a road stop on a nearby tile the same station as this?
nearby_tile_view	x, y offset (-8..7)	RST_VIEW_XXX	The view/rotation of a nearby road stop tile. See list of road stop views
nearby_tile_different_view	x, y offset (-8..7)	0 .. 1	Is the view/rotation of a road stop on a nearby tile different to that of this tile?
nearby_tile_is_drive_through	x, y offset (-8..7)	0 .. 1	Is nearby road stop tile a drive-through road stop?
nearby_tile_stop_type	x, y offset (-8..7)	RST_TYPE_XXX	Road stop type of a nearby tile. See stop_type
nearby_tile_same_stop_type	x, y offset (-8..7)	0 .. 1	Is the stop type of a nearby road stop tile the same as this tile?
nearby_tile_grfid	x, y offset (-8..7)	[0xFFFFFFFF | 0 | GRFID]	0xFFFFFFFF if the nearby tile is not a road stop, 0 if the nearby tile is a non-custom road stop, or else the GRFID of the NewGRF defining the road stop on the nearby tile
has_badge	Label from the badgetable.	[0 | 1]	15.0 Check if the road stop has that specific badge attached.

List of road stop views

Name	Type	Meaning	Value
RST_VIEW_BAY_NE	Bay	Facing north-east	0
RST_VIEW_BAY_SE	Bay	Facing south-east	1
RST_VIEW_BAY_SW	Bay	Facing south-west	2
RST_VIEW_BAY_NW	Bay	Facing north-west	3
RST_VIEW_DRIVE_THROUGH_X	Drive-through	X-axis: north-east to south-west	4
RST_VIEW_DRIVE_THROUGH_Y	Drive-through	Y-axis: north-west to south-east	5

Road stop callbacks

callback	return value	comment
default	Sprite layout	Normal graphics for a road stop placed on the map
purchase	Sprite layout	Graphics shown in the build menu
availability	0 | 1	Whether this road stop type is available in the build menu, 1 is available, 0 is unavailable
anim_next_frame	Next animation frame or CB_RESULT_XXX	Called for every animation frame, returns the next frame to display. Alternatively, return CB_RESULT_NEXT_FRAME or CB_RESULT_STOP_ANIMATION to show the next frame or stop animation, respectively. Returning a sound effect in the high byte will cause that sound effect to be played (e.g. return (sound("mysound.wav") << 8) | CB_RESULT_NEXT_FRAME;). extra_callback_info1: 32 random bits, if the object flag OBJ_FLAG_RANDOM_ANIMATION is set.
anim_control	Next animation frame or CB_RESULT_XXX	Called whenever an object animation trigger happens. Return the animation frame to show, or CB_RESULT_XXX with XXX = [START_ANIMATION | STOP_ANIMATION | DO_NOTHING] to respectively start the animation in its current frame, stop the animation or do nothing. Returning a sound effect in the high byte will cause that sound effect to be played. extra_callback_info1: 32 random bits, if the object flag OBJ_FLAG_RANDOM_ANIMATION is set. getbits(extra_callback_info2, 0, 8): Reason for the callback trigger, see the table below.
anim_speed	0 .. 16	Decide the time an animation frame should last. Return value is interpreted as (num_ticks = 2^anim_speed), which each tick lasting 30 ms. Avoid using this callback if possible, since it has to be called each tick for every animated tile. This can be used to create animation frames that last between 30 ms and 33 minutes.

Animation triggers

Animation trigger	Description	Happens on	extra_callback_info2
ANIM_TRIGGER_ROAD_STOP_BUILT	Road stop is built	Newly built tile
ANIM_TRIGGER_ROAD_STOP_NEW_CARGO	New cargo arrives at station	All tiles	Bits 8..15 contain the triggering cargo type
ANIM_TRIGGER_ROAD_STOP_CARGO_TAKEN	CRGO removed from station	All tiles	Bits 8..15 contain the triggering cargo type
ANIM_TRIGGER_ROAD_STOP_VEH_ENTER	Road vehicle enters stop (starts loading/unloading)	Tile where the vehicle is
ANIM_TRIGGER_ROAD_STOP_VEH_LEAVE	Road vehicle leaves stop (done loading/unloading)	Tile where the vehicle is
ANIM_TRIGGER_ROAD_STOP_VEH_LOAD	Road vehicle loads/unloads cargo	Tile where the vehicle is
ANIM_TRIGGER_ROAD_STOP_250_TICKS	Every 250 ticks	All tiles
15.0 ANIM_TRIGGER_ROAD_STOP_TILELOOP	Tile is processed in the periodic processing loop