Heresy: Changed the appropriate tables from t to sortable.

2022-08-30T21:20:46Z

Changed the appropriate tables from t to sortable.

← Older revision		Revision as of 21:20, 30 August 2022
Line 17:		Line 17:
	==Callbacks for vehicles==		==Callbacks for vehicles==

	{\| class="t"		{\| class="wikitable sortable"
	! name		! name
	! bit to set in callback_flags property		! bit to set in callback_flags property
Line 118:		Line 118:
	In order to set properties for vehicles via callback <code>VEH_CB_VEHICLE_PROPERTIES</code> it's necessary to query the general variable <code>extra_callback_info1</code> which can take different values depending upon the vehicle type:		In order to set properties for vehicles via callback <code>VEH_CB_VEHICLE_PROPERTIES</code> it's necessary to query the general variable <code>extra_callback_info1</code> which can take different values depending upon the vehicle type:

	{\| class="t"		{\| class="wikitable sortable"
	! property		! property
	! available for		! available for
Line 215:		Line 215:
	==Industry Tile Callbacks==		==Industry Tile Callbacks==

	{\| class="t"		{\| class="wikitable sortable"
	! Callback		! Callback
	! Values		! Values
Line 255:		Line 255:
	==Industry callback flags==		==Industry callback flags==

	{\| class="t"		{\| class="wikitable sortable"
	! callback and callback flag<br /> IND_CB_XXX and IND_CBF_XXX		! callback and callback flag<br /> IND_CB_XXX and IND_CBF_XXX
	! return values		! return values
Line 322:		Line 322:
	==Cargo callbacks==		==Cargo callbacks==

	{\| class="t"		{\| class="wikitable sortable"
	! value		! value
	! description		! description
Line 335:		Line 335:
	==Object callbacks==		==Object callbacks==

	{\| class="t"		{\| class="wikitable sortable"
	! Name		! Name
	! Meaning		! Meaning

FooBar: less code tags in table header ;)

2011-08-26T16:27:12Z

less code tags in table header ;)

← Older revision		Revision as of 16:27, 26 August 2011
Line 18:		Line 18:

	{\| class="t"		{\| class="t"
	! ~~<code>~~name~~</code>~~		! name
	! bit to set in callback_flags property		! bit to set in callback_flags property
	! available for		! available for

Planetmaker: some code tags. More needed

2011-08-26T08:33:59Z

some code tags. More needed

Show changes

FooBar: add nav template

2011-08-21T16:58:23Z

add nav template

← Older revision		Revision as of 16:58, 21 August 2011
Line 1:		Line 1:
			{{NMLNavNoSubpages}}

	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.		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.

FooBar: moved NML:Old to NML:Old style callbacks: NML:Old wasn't a very good page name to begin with

2011-08-21T12:25:41Z

moved NML:Old to NML:Old style callbacks: NML:Old wasn't a very good page name to begin with

← Older revision	Revision as of 12:25, 21 August 2011
(No difference)

FooBar: content of nml r1625

2011-08-21T12:24:48Z

content of nml r1625

New page

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==

{| class="t"
! name
! use
|-
| CB_RANDOM_TRIGGER
| re-randomize random data
|}

This callback may be called for all items that have triggers associated with them. See [[NML:Random switch|random switch]] for more information.

==Callbacks for vehicles==

{| class="t"
! 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 <code style="color:darkgreen">visual_effect_and_powered</code>
| 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 <code style="color:darkgreen">visual_effect</code>
| decide the visual effect to use (road vehicles / ships)
|-
| VEH_CB_WAGON_LENGTH
| VEH_CBF_WAGON_LENGTH
| Trains, Road Vehicles
| See train property <code style="color:darkgreen">shorten_vehicle</code>
| decide upon the length of the wagon (note: RVs have no equivalent property)
|-
| VEH_CB_LOAD_AMOUNT
| VEH_CBF_LOAD_AMOUNT
| All
| See property <code style="color:darkgreen">loading_speed</code>
| 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 <code style="color:darkgreen">VEH_CB_VEHICLE_PROPERTIES</code> it's necessary to query the general variable <code style="color:darkgreen">extra_callback_info1</code> which can take different values depending upon the vehicle type:

{| class="t"
! 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:

<pre style="color:blue">
/* 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;
}
}
</pre>

==Industry Tile Callbacks==

{| class="t"
! 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]
|}

==Industry callback flags==

{| class="t"
! 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 [[NML:Produce|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 [[NML:Produce|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 [[NML:List of default colour translation palettes|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==

{| class="t"
! value
! description
|-
| CARGO_CB_PROFIT
| Custom profit calculation
|-
| CARGO_CB_STATION_RATING
| Custom station rating calculation
|}

==Object callbacks==

{| class="t"
! 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.
|}

NML:Old style callbacks - Revision history

Heresy: Changed the appropriate tables from t to sortable.

FooBar: less code tags in table header ;)

Planetmaker: some code tags. More needed

FooBar: add nav template

FooBar: moved NML:Old to NML:Old style callbacks: NML:Old wasn't a very good page name to begin with

FooBar: content of nml r1625