NML:Old style callbacks

From GRFSpecs
Jump to navigationJump to search

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.
Retrieved from ‘https://newgrf-specs.tt-wiki.net/index.php?title=NML:Old_style_callbacks&oldid=4257’