NML:Builtin functions

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

Expressions

Elementary values

Builtin functions

Available builtin functions are

Function	Description
min(v1, v2)	Return the smallest value
max(v1, v2)	Return the biggest value
date(year, month, day)	If all values are constants, returns the number of days since year 0. If the year is a variable, the month and day should be 1.
day_of_year(month, day)	Return the day of the year since January 1st. Both values must be compile-time constants.
bitmask(bitpos1, ...)	Compose an integer by switching the bits at the given positions on (indexed starting at 1).
STORE_TEMP(value, address)	Store value in temporary storage. Temporary storage holds data until the final "return" of the current switch-chain of the current callback. Addresses 0..127 are available for the GRF to use. Addresses 0x100 and above have special purposes, which are described where they are used.
STORE_PERM(value, address)	Store value in permanent storage (industries, airports, towns only). Addresses <1.9 0..15, 1.9 0..255 are available for the GRF to use. Note that accessing permanent town registers thrashes the contents of temporary register 0x100.
LOAD_TEMP(address)	Get value from temporary storage. Addresses 0..127 are available for the GRF to use.
LOAD_PERM(address [, grfid])	Get value from permanent storage (industries, airports, towns only). For towns only, specifying a grfid (4-byte string, optional) allows reading the storage of other grfs. Note that accessing permanent town registers thrashes the contents of temporary register 0x100.
hasbit(value, bit_num)	Test whether a bit in a value is on
getbits(value, first, amount)	NML 0.4.1 Extract some bits from a value. Result is (value >> first) & (1 << amount - 1)
≤1.11 version_openttd(major, minor, revision[, build]) ≥12 version_openttd(major, minor)	Return the constant representing an OpenTTD version, for example OpenTTD 1.4.0: "version_openttd(1, 4, 0)" OpenTTD 13.0: "version_openttd(13, 0)" ≤1.8 Old versions before OpenTTD 1.9 also could check for specific SVN revisions. This is no longer available.
cargotype_available(cargotype)	Check if a certain cargo type is available in this game. cargotype must be a literal string of length 4.
railtype_available(railtype)	Check if a railtype is available in this game. railtype must be a literal string of length 4.
roadtype_available(roadtype)	Check if a roadtype is available in this game. roadtype must be a literal string of length 4.
tramtype_available(tramtype_available)	Check if a tramtype_available is available in this game. tramtype_available must be a literal string of length 4.
grf_current_status(grfid[, mask])	1 if the given GRF is currently active 0, otherwise. If mask is set, only the bits set in the mask will be tested. Both parameters must be a literal string of length 4.
grf_future_status(grfid[, mask])	Same as above, but tests whether the grf will become active instead of whether it's currently active.
grf_order_behind(grfid[, mask])	Same as above, but tests whether current grf will become active in the order behind the referenced grf.
create_effect(effect_sprite, l_x_offset, t_y_offset, z_offset)	Helper function for the vehicle callback 'create_effect'. effect_sprite: Sprite for the effect. One of EFFECT_SPRITE_[NONE|STEAM|DIESEL|ELECTRIC|AIRCRAFT_BREAKDOWN_SMOKE]. l_x_offset: Longitudinal or X position of the effect, depending on callback result CB_RESULT_CREATE_EFFECT_NO_ROTATION. t_y_offset: Transversal or Y position of the effect, depending on callback result CB_RESULT_CREATE_EFFECT_NO_ROTATION. z_offset: Z position of the effect.
visual_effect_and_powered(effect, offset, powered	Helper function for the train property visual_effect_and_powered and the VEH_CB_VISUAL_EFFECT_AND_POWERED callback.
str2number(4-byte long string)	Interpret the given string as a dword and return the value as integer.
cargotype(4-byte long string)	Return the index of the given cargo type in the cargo translation table.
railtype(4-byte long string)	Return the index of the given railtype in the railtype translation table.
roadtype(4-byte long string)	Return the index of the given roadtype in the roadtype translation table.
tramtype(4-byte long string)	Return the index of the given tramtype in the tramtype translation table.
reserve_sprites(number of sprites)	Reserve a number of sprites in the TTD sprite range. This is needed if you want to use your own recolour sprites. Example: param[10] = reserve_sprites(1); replace(param[10]) { recolour_sprite { // your colour remap. } } spritelayout xyz { building { ... recolour: param[10]; } }
int(v1)	Converts v1 to an int. This is done by cutting off everything after the decimal point, i.e. rounding toward zero.
round(v1)	NML 0.5.4 Converts v1 to an int. This is done by rounding towards the closest integer.
abs(v1)	Return the absolute value of v1.
acos / asin / atan / cos / sin / tan	Standard trigonometric functions.
sqrt	NML 0.5.4 Square root.
CMP(param1, param2)	Compares param1 and param2 (considering them as signed values). Returns CMP_LESS if param1 is less than param2, CMP_EQUAL if they are equal and CMP_GREATER if param1 is greater than param2.
UCMP(param1, param2)	Compares param1 and param2 (considering them as unsigned values). Returns CMP_LESS if param1 is less than param2, CMP_EQUAL if they are equal and CMP_GREATER if param1 is greater than param2.
rotate(value, amount)	Rotates value to the right amount steps. This is always a 32 bits rotation.
sound(soundfile[, volume])	Import sound from .wav-file soundfile into the grf file and return its numeric ID. Including a file multiple times will not cause it to be duplicated. Loaded sound files must be in WAV format, PCM encoding: mono 8-bit or 1.0  16-bit 11025 Hz, 22050 Hz or 44100 Hz. volume is in the [0, 100] range, the default value (if not set) is 100.
import_sound(grfid, id[, volume])	Import sound from a different grf file. grfid refers to the grf-file to import the sound from. id is the zero-based internal ID of the sound within the other grf-file. volume is in the [0, 100] range, the default value (if not set) is 100.
relative_coord(x, y)	Returns the coordinates in 0xYYXX format. x and y must be in the [0, 255] range.
num_corners_raised(slope)	Returns the number of corners raised in a slope. Return value is 0 .. 3 for normal slopes and 4 for steep ones. See also here for more information about slopes. Using this on values that are not slopes results in undefined behaviour.
slope_to_sprite_offset(slope)	Returns the sprite offset corresponding to a given slope. Return value is in range 0 .. 18. See also here for more information about slopes. The section on spritelayouts contains some more information one possible uses, as well as an example. Using this on values that are not slopes results in undefined behaviour.
palette_1cc(colour)	Returns the 1cc palette for the given company colour, see here for more info.
palette_2cc(colour1, colour2)	Returns the 2cc palette for the given first and second company colour, see here for more info.
vehicle_curv_info(prev_cur, cur_next)	Returns the curvature state of a vehicle, given the direction differences between the (previous-current) and (current-next) vehicle pairs. For use with the vehicle variable curv_info
format_string(format, args)	Use the python string formatting functions to create a literal string. Keep in mind that the output is a literal string which cannot be used by string(). This function can however be used to create filenames.