View source for NML:Builtin functions

{{NMLNavExpressions}}

Available builtin functions are

{| class="wikitable sortable"
! 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. 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 {{ottd|&lt;1.9}} 0..15, {{ottd|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)
|-
| {{ottd|&le;1.11}} version_openttd(''major'', ''minor'', ''revision''[, ''build'']) <br> {{ottd|&ge;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)"
{{ottd|&le;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:
<pre style="color:blue">
 param[10] = reserve_sprites(1);
 replace(param[10]) {
 	recolour_sprite {
 		// your colour remap.
 	}
 }
 spritelayout xyz {
 	building {
 		...
 		recolour: param[10];
 	}
 }
</pre>
|-
| 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 {{ottdp|1.0|no}} 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 [[NML:List of tile slopes|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 [[NML:List of tile slopes|here]] for more information about slopes. The section on [[NML:Spritelayout|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 [[NML:List_of_default_colour_translation_palettes#Company colour helper functions|here]] for more info.
|-
| palette_2cc(''colour1'', ''colour2'')
|
Returns the 2cc palette for the given first and second company colour, see [[NML:List_of_default_colour_translation_palettes#Company colour helper functions|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 <code style="color:darkgreen">curv_info</code>
|-
| 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.
|}