NML:Old style callbacks

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

Old style callbacks

No subpages in this chapter.

This page contains information about the classical way of defining callbacks, which is handling them within a chain of switch-blocks. It is not recommended to use this method, but it is still supported for backwards compatibility, (temporary) support for nfo->nml converted grfs and because it may be useful in some cases. Do not use this for new NewGRFs unless you have a really good reason to do so. Note that this page is no longer updated, the information here may be out of date.

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.

Callbacks for vehicles

name	bit to set in callback_flags property	available for	return value	use
VEH_CB_VISUAL_EFFECT_AND_POWERED	VEH_CBF_VISUAL_EFFECT_AND_POWERED	Trains	See property visual_effect_and_powered	decide the visual effect to use and whether a wagon has power
VEH_CB_VISUAL_EFFECT	VEH_CBF_VISUAL_EFFECT	Road Vehicles, Ships	See property visual_effect	decide the visual effect to use (road vehicles / ships)
VEH_CB_WAGON_LENGTH	VEH_CBF_WAGON_LENGTH	Trains, Road Vehicles	See train property shorten_vehicle	decide upon the length of the wagon (note: RVs have no equivalent property)
VEH_CB_LOAD_AMOUNT	VEH_CBF_LOAD_AMOUNT	All	See property loading_speed	decide upon the loading speed (amount loaded per tick)
VEH_CB_REFITTED_CAPACITY	VEH_CBF_REFITTED_CAPACITY	All	Cargo capacity 0 ... 255	decide upon the capacity after refit
VEH_CB_ARTICULATED_PARTS	VEH_CBF_ARTICULATED_PARTS	Trains, Road Vehicles	ID of vehicle to attach, 0xFF if none	decide upon the ID of the next vehicle added to the articulated vehicle chain
VEH_CB_CARGO_SUFFIX	VEH_CBF_CARGO_SUFFIX	All	string	decide upon cargo subtype display for refit
VEH_CB_CAN_ATTACH_WAGON	None	Trains	string containing error message, or one of the following: 0xFD (disallow with message "incomatible railtypes"), 0xFE (allow) or 0xFF (allow if railtypes match)	decide whether a wagon can be attached
VEH_CB_TEXT_PURCHASE_SCREEN	None	All	string	decide upon an additional text for the purchase screen
VEH_CB_COLOUR_MAPPING	VEH_CBF_COLOUR_MAPPING	All	sprite number	decide upon the colour mapping instead of company colour
VEH_CB_START_STOP_CHECK	None	All	string containing error message, or 0xFF to allow	decide whether a vehicle may be started/stopped.
VEH_CB_32DAY	None	All	bitmask	Triggers one or both of Trigger vehicle trigger 10 (bit 0) and Update colour map via VEH_CB_COLOUR_MAPPING (bit 1)
VEH_CB_SOUND_EFFECT	None	All	sound effect number	decide whether and which sound is being played for certain situations
VEH_CB_AUTOREPLACE_SELECT	None	All	vehicle ID	decide upon appropriate replacement vehicles (not implemented in OpenTTD)
VEH_CB_VEHICLE_PROPERTIES	None	All	property-dependent	Change vehicle properties, see below

In order to set properties for vehicles via callback VEH_CB_VEHICLE_PROPERTIES it's necessary to query the general variable extra_callback_info1 which can take different values depending upon the vehicle type:

property	available for	value
cost_factor	all	PROP_XXX_COST_FACTOR
running_cost_factor	all	PROP_XXX_RUNNING_COST_FACTOR
speed	all	PROP_XXX_SPEED
power	trains and road vehicles	PROP_XXX_POWER
weight	trains and road vehicles	PROP_XXX_WEIGHT
tractive_effort_coefficient	trains and road vehicles	PROP_XXX_TRACTIVE_EFFORT_COEFFICIENT
cargo_capacity	all except aircraft	PROP_XXX_CARGO_CAPACITY
passenger_capacity	aircraft	PROP_AIRCRAFT_PASSENGER_CAPACITY
mail_capacity	aircraft	PROP_AIRCRAFT_MAIL_CAPACITY
bitmask_vehicle_info	trains	PROP_TRAINS_BITMASK_VEHICLE_INFO

Where for the properties available for all vehicle types XXX can either be TRAINS, ROADVEHS, SHIPS or AIRCRAFT. Note also that the return values don't yet support units, you'll need to enter the properties untranslated (e.g. road vehicle weights are in quantities of 0.25 tons).

The following code is an example for the use of callbacks and most notably also the creation of articulated vehicles which can only be created by means of the VEH_CB_ARTICULATED_PARTS:

 /* Here would have to be definition of sprite sets and groups */
 
 /* callback for articulated vehicles: 4 wagons with special sprites for first and last */
 switch(FEAT_TRAINS, SELF, rail_engine_articulated_parts, extra_callback_info1) {
     1..2: return rail_wagon; // middle parts use rail wagons
 	3: return rail_engine;   // last part is this rail engine again
     CB_FAILED;               // no more than 4 vehicles
 }
 
 /* Set the (empty) weight of the vehicle depending on the cargo it carries */
 switch (FEAT_TRAINS, SELF, rail_wagon_cb_property_weight_switch, cargo_type_in_veh) {
     PASS: return 30; // Passenger wagons are heavier
     TOUR: return 30; // Tourists are also passengers
     CB_FAILED;       // use value set in the property block for other cargos
 }
 
 /* Set (conditionally) different properties of the train */
 switch (FEAT_TRAINS, SELF, rail_engine_cb_property_switch, extra_callback_info1) {
     PROP_TRAINS_WEIGHT          : rail_engine_cb_property_weight_switch;
     PROP_TRAINS_CARGO_CAPACITY  : rail_engine_cb_capacity_switch; // not shown here
     CB_FAILED;                                                    // we don't set other properties
 }
 
 /* Check for each (active) callback */
 switch (FEAT_TRAINS, SELF, rail_engine_switch, current_callback) {
     VEH_CB_REFITTED_CAPACITY:  rail_engine_cb_capacity_switch; // switch not shown here
     VEH_CB_VEHICLE_PROPERTIES: rail_engine_cb_property_switch;
     VEH_CB_ARTICULATED_PARTS: rail_engine_articulated_parts;
     rail_engine_graphics_switch; // go to graphics branch, if no callback asked for; not shown here
 }
 
 /* Define this rail engine */
 item(FEAT_TRAINS, rail_engine) {
     property {
         callback_flags:                 bitmask(VEH_CBF_ARTICULATED_PARTS, VEH_CBF_REFITTED_CAPACITY); // activate callbacks
         cargo_capacity:                 20;
         weight:                         24 ton;
     }
     graphics {
         rail_engine_switch;
     }
 }

Industry Tile Callbacks

Callback	Values	Meaning
INDTILE_CB_ANIM_STARTSTOP	animation frame or CB_RESULT_XXX	NEXT_FRAME | DO_NOTHING]
INDTILE_CB_ANIM_NEXT_FRAME	animation frame or CB_RESULT_XXX	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	NO_FOUNDATIONS]
INDTILE_CB_AUTOSLOPE	CB_RESULT_XXX	NO_AUTOSLOPE]

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.

Cargo callbacks

value	description
CARGO_CB_PROFIT	Custom profit calculation
CARGO_CB_STATION_RATING	Custom station rating calculation

Object callbacks

Name	Meaning
OBJ_CB_SLOPE_CHECK	Check for the slope of a tile
OBJ_CB_DECIDE_ANIM	Decide whether animation continues: 0xFF stops animation, 0xFE continues with next frame
OBJ_CB_DECIDE_ANIM_SPEED	Decide the animation frame to jump to. Or alternatively: 0xFF to stop animation, 0xFE to start animation with current frame, 0xFD to keep the current animation frame and do nothing
OBJ_CB_DECIDE_COLOUR	Return the colour, or for 2 company colours the two colours, to be used. In the case of 2CC the 2nd company colour goes into the high 4 bits of the return value
OBJ_CB_ADDITIONAL_TEXT	Return an additional string which is shown in the purchase menu. It should not exceed in length three lines.
OBJ_CB_AUTOSLOPE	Return a value different from 0 in order to disable autoslope behaviour.