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.
STORE_TEMP(value, address)	Store value in temporary storage
STORE_PERM(value, address)	Store value in permanent storage (industries, airports, towns only). Note that accessing permanent town registers thrashes the contents of temporary register 0x100.
LOAD_TEMP(address)	Get value from temporary storage
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
version_openttd(major, minor, revision[, build])	Return the constant representing an OpenTTD version
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.
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.
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.
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.
abs(v1)	Return the absolute value of v1.
acos / asin / atan / cos / sin / tan	Standard trigonometric functions.
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.