NML documentation

# General

## General variables

A number of global variables are available. Some are only available in switch-blocks, while others can be used in any expression. This is indicated by the second column in the following table:

name | Available outside switch blocks | Value range | Comment
--- | --- | --- | ---
ttd_platform | Yes | PLATFORM_TTDPATCH or PLATFORM_OPENTTD |
ttdpatch_version | Yes |  |
openttd_version | Yes |  | use version_openttd(MAJOR, MINOR, BUILD) to test and compare for a release version and version_openttd(MAJOR, MINOR, BUILD, REVISION) to test for a specific svn version of OpenTTD
current_palette | Yes | PALETTE_DOS or PALETTE_WIN |
current_date | No | days since year 0 | Use date (year, month, day) to compare with.
current_year | No | years since year 0 |
current_month | No | 0 .. 11 |
current_day_of_month | No | 0 .. 30 |
current_day_of_year | No | 0 .. 364 (365 in leap years) |
is_leapyear | No | 0 or 1 |
date_loaded | Yes | days since year 0 | Set to the time of game load, which is the current date in single player, and the date the server started in multiplayer. This to prevent desyncs.
year_loaded | Yes | years since year 0 | See date_loaded.
starting_year | Yes | years since year 0 | Years before 1920 are clamped to 1920
animation_counter | No | 0 .. 65535 | Increased by 1 each tick
climate | Yes (a) | CLIMATE_XXX with XXX = [TEMPERATE | ARCTIC | TROPICAL | TOYLAND] |
game_mode | Yes | GAMEMODE_XXX with XXX = [MENU | GAME | EDITOR] |
loading_stage | Yes | LOADING_STAGE_XXX with XXX = [INITIALIZE | RESERVE | ACTIVATE | TEST] | 'Phase' of the GRF loading process.
difficulty_level | Yes (a) | DIFFICULTY_XXX with XXX = [EASY | MEDIUM | HARD | CUSTOM] |
display_options | No | bitmask of DISPLAY_XXX with XXX = [TOWN_NAMES | STATION_NAMES | SIGNS | ANIMATION | FULL_DETAIL] | Use hasbit(display_options, DISPLAY_XXX) to test a particular bit.
desert_paved_roads | Yes (b) | 0 or 1 | If 1, desert roads have pavement and street lights.
train_width_32_px | Yes (b) | 0 or 1 | If 1, train vehicles are 32 instead of 29 pixels wide in the depot view.
traininfo_y_offset | Yes (b) | -128 .. 127 | Used to correctly position the depot view of trains.
snowline_height | No | 16 .. 120 in steps of 8, or 0xFF if no snow. | One tile height is equivalent to 8 units.
traffic_side | Yes (a) | TRAFFIC_SIDE_LEFT or TRAFFIC_SIDE_RIGHT |
freight_trains | Yes | 1 .. 255 | Weight multiplier for freight trains
plane_speed | Yes | 1 .. 4 | Speed multiplier for planes. Value of 1 is equal to the original speed (1/4), while 4 means that planes move at full speed (4/4)
ttdpatch_flags | Yes |  |
current_callback | No |  | Set to the ID of the current callback, see the various features for more information / examples.
extra_callback_info1 | No | Varies | Extra callback information, meaning differs per callback.
extra_callback_info2 | No | Varies | Extra callback information, meaning differs per callback.
last_computed_result | No |  | Result of the last (previously evaluated) switch block.
base_sprite_2cc | Yes | 0 .. 65535 | Base sprite for 2cc (dual company colour) colour-maps
map_type | Yes | MAP_TYPE_XXX with XXX = [RECTANGULAR | X_BIGGER | Y_BIGGER] |
map_min_edge | Yes | 64 .. 2048 | Length of the smallest map edge (in tiles)
map_max_edge | Yes | 64 .. 2048 | Length of the biggest map edge (in tiles)
map_x_edge | Yes | 64 .. 2048 | Length of the x (top-left) map edge (in tiles)
map_y_edge | Yes | 64 .. 2048 | Length of the y (top-right) map edge (in tiles)
map_size | Yes | 64*64 .. 2048*2048 | Total number of tiles on the map
long_bridges | Yes | 0 or 1 |
gradual_loading | Yes | 0 or 1 |
bridge_speed_limits | Yes | 0 or 1 |
signals_on_traffic_side | Yes | 0 or 1 |
electrified_railways | Yes | 0 or 1 |
unified_maglev | Yes | 0 .. 3 |
temperate_snowline | Yes | 0 or 1 |
dynamic_engines | Yes | 0 or 1 |
variable_runningcosts | Yes | 0 or 1 |
newtrains | Yes | 0 or 1 |
newrvs | Yes | 0 or 1 |
newships | Yes | 0 or 1 |
newplanes | Yes | 0 or 1 |
newhouses | Yes | 0 or 1 |
newindustries | Yes | 0 or 1 |
newcargos | Yes | 0 or 1 |

(a) The value of these variables can change during the game. Reading them from a switch block (which reads the current value) may result in a different value than in the rest of the code (which is evaluated when the game is loaded).

(b) These variables can be written as well as read. Use a normal assignment, for example:

    traininfo_y_offset = -2;

### General callbacks

name | use
--- | ---
CB_RANDOM_TRIGGER | re-randomize random data

This callback may be called for all items that have triggers associated with them. See random switch for more information.

## Snowline properties

The snowline is specified by a `snowline` statement. See the example below:

    snowline (linear) {
    	day_of_year(2,  1):  2;
    	day_of_year(11, 1):  4;
    	177: 29;
    	day_of_year(10, 1): 29;
    }

It starts with the `snowline` keyword followed by the mode. It contains a number of `<day-of-the-year> : <height>` pairs. These define the height of the snowline at that day in the year. The day of the year value is actually an integer from 1 up to and including 365, so you may also define a day as a number. Heights run from 2 (for snow everywhere) to 29, although 17 is already sufficient to remove all traces of snow from the game.

For the days not listed, the program computes a height. It can do that in two modes, namely in `equal` mode and in `linear` mode (last line of text in the example). In `equal` mode, the height of the snow is the same as the day before, unless the day is listed in the `snowline` statement. In `linear` mode, the height of the snowline gets linearly interpolated between two heights specified in the statement. In both cases, note that days `wrap around' at the end of the year, to get the snow height of January 1st (if not listed in the statement), the last specified height of the year is used in the calculation.