NML documentation

# Industries

## Industry variables

name | value range | comment
--- | --- | ---
waiting_cargo_1 | 0..65535 | If IND_CBF_PROD_CB_CARGO_ARRIVE or IND_CBF_PROD_CB_256_TICKS are set in the callback_flags property, this variable will contain the amount of the first cargo type awaiting to be processed.
waiting_cargo_2 | 0..65535 | If IND_CBF_PROD_CB_CARGO_ARRIVE or IND_CBF_PROD_CB_256_TICKS are set in the callback_flags property, this variable will contain the amount of the second cargo type awaiting to be processed.
waiting_cargo_3 | 0..65535 | If IND_CBF_PROD_CB_CARGO_ARRIVE or IND_CBF_PROD_CB_256_TICKS are set in the callback_flags property, this variable will contain the amount of the third cargo type awaiting to be processed.
produced_last_month_1 | 0..65535 | The amount of 'output cargo type 1' that was produced last month.
produced_last_month_2 | 0..65535 | The amount of 'output cargo type 2' that was produced last month.
water_distance | Distance to the tile | If the industry is built on water, this variable gives the distance of the closest dry land tile, otherwise it gives the distance of the closest water tile.
layout_num | 1..255 | Number of the layout being used by the industry.
founder | 0..16 | Company number of the industry founder. It will be 16 (0x10) if the industry was generated randomly. TTDPatch only supports up to 8 companies (0..7).
founder_type | PLAYERTYPE_XX | PLAYERTYPE_HUMAN, PLAYERTYPE_AI, PLAYERTYPE_HUMAN_IN_AI (human managing AI company) or 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.
founder_colour1 | 0..15 | Index of founding company's first colour. 0 if not founded by a company.
founder_colour2 | 0..15 | Index of founding company's second colour. It's the same as company_colour1, if no second company colour is chosen. 0 if not founded by a company.
colour | 0..15 | Random colour for this industry.
build_date | 0..1826212865 | Date of the industry foundation in days since year 0.
build_type | BUILDTYPE_XX | BUILDTYPE_UNKNOWN (if created in an old version or with newindustries disabled), BUILDTYPE_GAMEPLAY (if founded or created by the in-game random industry generator), BUILDTYPE_GENERATION (if created during random map generation) or BUILDTYPE_EDITOR (if created with the scenario editor).

Variables that require some parameters.

name | arguments | comment
--- | --- | ---
industry_count | industry_type, grfid = -1 | The value of this variable is the number of industries of a given type that are currently on the map. industry_type is either the ID of an industry. GRFid is the grf in which the industry was defined. The default value is -1, which means current newgrf. A grfid of 0 lets you check the number of default industries of a given type. Warning: using this variable trashes the contents of temporary storage register 0x100
industry_distance | industry_type, grfid = -1 | The value of this variable is the manhattan distance the closest instance of the given industry or 0xFFFF if not applicable. See industry_count for a description of the parameters. Warning: using this variable trashes the contents of temporary storage register 0x100.
industry_layout_count / industry_layout_distance | industry_type, layout, grfid = -1. | See industry_count / industry_distance for description of industry_type, grfid and return value. The results are filtered to industries that have the given layout number. Warning: using this variable trashes the contents of temporary storage registers 0x100 and 0x101.
industry_town_count | industry_type, grfid = -1. | See industry_count / industry_distance for description of industry_type, grfid and return value. The results are filtered to industries that have the same town than the current industry. Warning: using this variable trashes the contents of temporary storage registers 0x100 and 0x101.
town_manhattan_dist | x, y | Parameters indicate a signed offset relative to the northern tile. Returns the Manhattan distance (dx + dy) from the selected tile to the closest town
town_euclidean_dist | x, y | Parameters indicate a signed offset relative to the northern tile. Returns the squared Eucleidean distance (dx^2 + dy^2) from the selected tile to the closest town.
town_zone | x, y | Parameters indicate a signed offset relative to the northern tile. Returns the town zone that the selected tile is in.
nearby_tile_random_bits | x, y | Parameters indicate an unsigned offset relative to the northern tile. Returns the random bits of the selected industry tile, or 0 if it is not an industry tile that's part of this industry.

### Common variables

The following variables are available to both industries and industry tiles. All of them require an x, y offset. For industries, this offset is unsigned and relative to the northernmost tile. For industry tiles, it is signed and relative to the current tile.

name | value range | comment
--- | --- | ---
nearby_tile_slope | Which corners are raised on the given tile. | Bit 0: west corner is above the lowest corner. Bit 1: south corner is above the lowest corner. Bit 2: east corner is above the lowest corner. Bit 3: north corner is above the lowest corner. Bit 4: this tile is a steep slope (the corner opposite to the lowest corner is 2 units higher). See tile slopes for an illustration
nearby_tile_is_water | 1 if the tile is water, 0 otherwise |
nearby_tile_terrain_type | TILETYPE_XX | TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
nearby_tile_height | 0..120 | The height of the lowest corner of the given tile.
nearby_tile_class | Tile class |
nearby_tile_animation_frame | 0..255 | Animation frame of the given tile
nearby_tile_industrytile_id | 0x00aa, 0xFFbb, 0xFFFE or 0xFFFF | 0x00aa: The tile is an industry tile that is part of this GRF, the tile id is aa. 0xFFbb: The tile is an original industry tile with id bb. 0xFFFE: The tile is an industry tile defined in another GRF. 0xFFFF: The tile is not an industry tile or it belongs to another GRF.

## Industry tile variables

name | value range | comment
--- | --- | ---
construction_state | 0..3 | Current construction state of the industry tile.
terrain_type | TILETYPE_XX | TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
town_zone | town zone | The town zone of the current tile.
relative_x | 0..255 | X-coordinate (top right -> bottom left) of the tile relative to the northernmost tile.
relative_y | 0..255 | Y-coordinate (top left -> bottom right) of the tile relative to the northernmost tile.
relative_pos | 0xYYXX | A combination of relative_x and relative_y in the format 0xYYXX. Useful if you want to check for a single position.
animation_frame | 0..255 | Current animation frame.

Industry tiles have access to the common variables described above. Additionally, they have access to the following:

name | arguments | comment
--- | --- | ---
nearby_tile_is_same_industry | x, y | Parameters indicate a signed tile offset relative to the current tile. Returns 1 if the tile is part of the same industry, 0 otherwise

## Industry tile properties

property | value range | comment
--- | --- | ---
substitute | 0..174 | Number of the default industry tile that replaces this one, if this industry tile is not available for some reason. This property must be set first, before any other properties or graphics. All properties of the old type are copied to your new house.
override | 0..174 | id of the default industry tile which this industry tile replaces. This will cause your industry tile to be placed instead of the default industry tile. This is ignored, if the default industry tile has already been overridden. You can define this property multiple times
accepted_cargos | Array with up to 3 [cargo_id, amount]-pairs. | The cargos that are accepted by this tile. CargoID is a cargo type from your cargo translation table, amount is the acceptance of the given cargo in 1/8 units. Example: to make a tile accept both COAL and IORE you could use this: `accepted_cargos: [[COAL, 8], [IORE, 8]];` Example: for a tile that doesn't any cargos at all you'd use: `accepted_cargos: [];`
land_shape_flags | bitmask(Land shape flags) |
callback_flags | bitmask(INDTILE_CBF_XXX, INDTILE_CBF_YYY) | XXX = ANIM_NEXT_FRAME | ANIM_SPEED | CARGO_AMOUNT_ACCEPT | CARGO_TYPE_ACCEPT | SLOPE_IS_SUITABLE | FOUNDATIONS | AUTOSLOPE
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(Animation control callback triggers) | Triggers which control whether the animatin is started or stopped
special_flags | 0..1 | Set to 1 if INDTILE_CB_ANIM_NEXT_FRAME needs random bits

### Land shape flags

Flag | Meaning
--- | ---
LSF_CANNOT_LOWER_NW_EDGE | North-west edge cannot be lowered
LSF_CANNOT_LOWER_NE_EDGE | North-east edge cannot be lowered
LSF_CANNOT_LOWER_SW_EDGE | South-west edge cannot be lowered
LSF_CANNOT_LOWER_SE_EDGE | South-east edge cannot be lowered
LSF_ONLY_ON_FLAT_LAND | This tile can only be built on flat land
LSF_ALLOW_ON_WATER | The land/water check is disabled for this tile so it can be built on water. If you need more control over this use callback 0x2F.

### Callbacks

Callback | Values | Meaning
--- | --- | ---
INDTILE_CB_ANIM_STARTSTOP | animation frame or CB_RESULT_XXX | Called by a trigger. It decides upon the next animation frame. Special values: XXX=[STOP_ANIMATION | NEXT_FRAME | DO_NOTHING]
INDTILE_CB_ANIM_NEXT_FRAME | animation frame or CB_RESULT_XXX | Called each animation frame. It decides upon the next animation frame. Special values: XXX=[STOP_ANIMATION | NEXT_FRAME]
INDTILE_CB_ANIM_SPEED | length | Length of the animation frame as defined in the apendix. This is a very expensive callback and try to avoid it, if possible, by using identical animation frames.
INDTILE_CB_CARGO_AMOUNT_ACCEPT | special | accepted cargo amounts in 1/8. Bits 0...3: 1st cargo, bits 4 ... 7: 2nd cargo, bits 8 ... 11: 3rd cargo
INDTILE_CB_CARGO_TYPE_ACCEPT | special | accepted cargo types as entry in the CTT. Bits 0...4: 1st cargo, bits 5 ... 9: 2nd cargo, bits 10 ... 14: 3rd cargo
INDTILE_CB_SLOPE_IS_SUITABLE |  | decide whether the location is suitable for the tile (for build checks of the industry)
INDTILE_CB_FOUNDATIONS | CB_RESULT_XXX | with XXX=[FOUNDATIONS | NO_FOUNDATIONS]
INDTILE_CB_AUTOSLOPE | CB_RESULT_XXX | with XXX=[AUTOSLOPE | NO_AUTOSLOPE]

### Animation control callback triggers

Trigger | Meaning
--- | ---
INDTILE_TRIGGER_CONSTRUCTION_STATE | the construction state changes
INDTILE_TRIGGER_TILE_LOOP | the tile is processed in the periodic processing loop
INDTILE_TRIGGER_INDUSTRY_LOOP | the industry of the tile is processed in the periodic processing loop (synchronized animation)
INDTILE_TRIGGER_INDUSTRY_RECEIVED_CARGO | the industry of the tile receives input cargo from a station
INDTILE_TRIGGER_INDUSTRY_DISTRIBUTES_CARGO | the industry distributes its output cargo to one of the stations nearby

## Industry properties

Industry properties. Default industry type numbers can be found at default industries.

property | value range | comment
--- | --- | ---
substitute | industry type | Number of the original industry type that replaces this one, should it not be available for some reason (e.g. missing NewGRF). This must be the first property to be set, before any other properties or graphics. All properties of the old type are copied to your new industry.
override | industry type | Number of the original industry type overridden. This will cause other grfs / industries to consider your industry type the same as the old type. Only set this property if your type is (more or less) the same as the old type.
layouts | Array of tilelayouts | See Tilelayout syntax.
life_type | One of IND_LIFE_TYPE_XXX, XXX = BLACK_HOLE | EXTRACTIVE | ORGANIC | PROCESSING | The generic type of industry. This determines the production changes that occur by default (when not using the callback). Examples are respectively power plants, coal mines, forests en steel mills.
closure_msg | string | Message displayed when the industry announces closure.
prod_increase_msg | string | Message displayed when industry increases production.
prod_decrease_msg | string | Message displayed when industry decreases production.
fund_cost_multiplier | 0..255 | Fund cost multiplier. Note that in OpenTTD the unmodified base cost is 8x higher for building (not prospecting) raw (=extractive / organic, see life_type) industries.
prod_cargo_types | array of up to 2 ints | Types of cargo produced. Use the cargotype(<label>) built-in function to specify a label from the cargotable.
accept_cargo_types | array of up to 3 ints | Types of cargo accepted. Use the cargotype(<label>) built-in function to specify a label from the cargotable
prod_multiplier | array of up to 2 ints (0..255) | Amount of each output cargo to produce every 256 ticks (8 or 9 times a month)
min_cargo_distr | 0..255 | Minimal amount of cargo before transporting to stations.
random_sound_effects | array of ints | Sound effect numbers that are played some times.
conflicting_ind_types | array of up to 3x industry_type(IND_TYPE_OLD | IND_TYPE_NEW, id) | Three industry types that should not be nearby. Use the builtin-function industry_type(..) to define either an old industry (using the global ID) or a new industry from your grf (using the grf-local ID).
prob_random | 0..10 | Probability of occurring while generating initial industries.
prob_in_game | 0..10 | Probability of occurring while creating industries during the game.
map_colour | 0..255 | Colour index from the DOS palette to use on the minimap for this industry.
spec_flags | bitmask(flags) | for flag values see Industry special flags
new_ind_msg | string | Message displayed when industry gets built during game play.
input_multiplier_1 | array of up to 2 floats (0..255) | Output cargo multiplication factors for getting a unit of the first accepted cargo.
input_multiplier_2 | array of up to 2 floats (0..255) | Output cargo multiplication factors for getting a unit of the second accepted cargo.
input_multiplier_3 | array of up to 2 floats (0..255) | Output cargo multiplication factors for getting a unit of the third accepted cargo.
name | string | Name of the industry
prospect_chance | Fraction between 0 and 1 | Chance of successful prospecting.
callback_flags | bitmask(flags) | for flag values see Industry callback flags
remove_cost_multiplier | int | Cost multiplier for removing the industry (currently only possible with magic bulldozer).
nearby_station_name | string | Default additional name for a nearby station

### Industry callback flags

callback and callback flag IND_CB_XXX and IND_CBF_XXX | return values | meaning
--- | --- | ---
IND_CBF_AVAILABILITY | CB_RESULT_IND_ALLOW CB_RESULT_IND_DISALLOW | decide upon availability of the industry type. extra_callback_info_2 allows to get information on how the industry is being built: 0: during map generation 1: random generation ingame 2: user trying to fund or prospect the industry
IND_CBF_PROD_CB_CARGO_ARRIVE (no callback, use produce block) | n/a (use produce block) | handle production when cargo is delivered. See produce block
IND_CBF_PROD_CB_256_TICKS (no callback, use produce block) | n/a (use produce block) | handle production every 256 ticks. See produce block
IND_CBF_LOCATION_CHECK | string CB_RESULT_IND_ALLOW_LOCATION CB_RESULT_IND_DISALLOW_UNSUITABLE CB_RESULT_IND_DISALLOW_ONLY_RAINFOREST CB_RESULT_IND_DISALLOW_ONLY_DESERT | handle check for permissible build locations extra_callback_info_2 allows to get information on how the industry is being built: 0: during map generation 1: random generation ingame 2: user trying to fund the industry 3: user trying to prospect the industry
IND_CBF_RANDOM_PROD_CHANGE | see monthly production changes below | handle random production changes
IND_CBF_MONTHLY_PROD_CHANGE | CB_RESULT_IND_PROD_NO_CHANGE CB_RESULT_IND_PROD_HALF CB_RESULT_IND_PROD_DOUBLE CB_RESULT_IND_PROD_CLOSE CB_RESULT_IND_PROD_RANDOM CB_RESULT_IND_PROD_DIVIDE_BY_4 CB_RESULT_IND_PROD_DIVIDE_BY_8 CB_RESULT_IND_PROD_DIVIDE_BY_16 CB_RESULT_IND_PROD_DIVIDE_BY_32 CB_RESULT_IND_PROD_MULTIPLY_BY_4 CB_RESULT_IND_PROD_MULTIPLY_BY_8 CB_RESULT_IND_PROD_MULTIPLY_BY_16 CB_RESULT_IND_PROD_MULTIPLY_BY_32 CB_RESULT_IND_PROD_DECREMENT_BY_1 CB_RESULT_IND_PROD_INCREMENT_BY_1 CB_RESULT_IND_PROD_SET_BY_0x100 | handle monthly production changes
IND_CBF_CARGO_SUBTYPE_DISPLAY | string | decide on displayed cargo subtypes
IND_CBF_EXTRA_TEXT_FUND | string | decide on extra text displayed in industry funding window
IND_CBF_EXTRA_TEXT_INDUSTRY | string | decide on extra text in the industry window
IND_CBF_CONTROL_SPECIAL | CB_RESULT_IND_DO_NOT_USE_SPECIAL CB_RESULT_IND_USE_SPECIAL | decide whether the special defined in spec_flags shall be used or not
IND_CBF_STOP_ACCEPT_CARGO |  | decide on cargo acceptance
IND_CBF_COLOUR | 0...15 | decide on industry colour. See also the palettes. DARK_BLUE (#775) corresponds to the colour 0.
IND_CBF_CARGO_INPUT | cargo label | decide on accepted cargo types. extra_callback_info_1 gives the input cargo number. Return 0xFF for any other value than 0, 1 or 2 for extra_callback_info_1.
IND_CBF_CARGO_OUTPUT | cargo label | decide on output cargo types. extra_callback_info_1 gives the output cargo number. Return 0xFF for any other value than 0 or 1 for extra_callback_info_1.

### Industry special flags

flag | meaning
--- | ---
IND_FLAG_PLANT_FIELDS_PERIODICALLY | The industry periodically plants fields around itself (temperate and arctic farms)
IND_FLAG_CUT_TREES | The industry cuts trees around itself and produces its first output cargo from them (lumber mill)
IND_FLAG_BUILT_ON_WATER | The industry is built on water (oil rig)
IND_FLAG_ONLY_IN_LARGE_TOWNS | The industry can only be built in towns (i.e. it has to replace houses) with population larger than 1200 (temperate bank)
IND_FLAG_ONLY_IN_TOWNS | The industry can only be built in towns (i.e. it has to replace houses) (arctic and tropic banks, water tower)
IND_FLAG_BUILT_NEAR_TOWN | The industry is always built near towns (i.e. near town sign; additionally the industry is allowed to replace houses) (toy shop)
IND_FLAG_PLANT_FIELDS_WHEN_BUILT | Fields are planted around the industry when it's built (all farms)
IND_FLAG_NO_PRODUCTION_INCREASE | The industry cannot increase its production on the temperate climate (oil wells)
IND_FLAG_BUILT_ONLY_BEFORE_1950 | The industry is built only before 1950 (oil wells)
IND_FLAG_BUILT_ONLY_AFTER_1960 | The industry is built only after 1960 (oil rig)
IND_FLAG_AI_CREATES_AIR_AND_SHIP_ROUTES | AI players will attempt to establish air and ship routes going to this industry (oil rig)
IND_FLAG_MILITARY_AIRPLANE_CAN_EXPLODE | The industry can be exploded by a military airplane (oil refinery)
IND_FLAG_MILITARY_HELICOPTER_CAN_EXPLODE | The industry can be exploded by a military helicopter (factory)
IND_FLAG_CAN_CAUSE_SUBSIDENCE | The industry can cause a subsidence (coal mine)
IND_FLAG_AUTOMATIC_PRODUCTION_MULTIPLIER | Automatic production multiplier handing (No industry has this bit set by default.).
IND_FLAG_RANDOM_BITS_IN_PRODUCTION_CALLBACK | The production callback needs random bits in var. 10 (No industry has this bit set by default.)
IND_FLAG_DO_NOT_FORCE_INSTANCE_AT_MAP_GENERATION | Do not force one instance of this type to appear during initial map generation (No industry has this bit set by default.)
IND_FLAG_ALLOW_CLOSING_LAST_INSTANCE | Allow closing down the last instance of this type (No industry has this bit set by default.)