TTWiki - User contributions [en-gb]

NMLTutorial/Train recolour

2013-12-08T13:40:56Z

Frosch: fix nml 0.2->0.3

{{NMLTutorial}}
''The example used here is from the [http://dev.openttdcoop.org/projects/nml/repository/show/examples NML source]. The code for this was originally written in NFO by DJNekkid for the 2cc Trainset and rewritten in NML by Hirundo. The graphics used in the example are by Purno. Code and graphics are both licensed according to the GPL v2 or later. The code has been modified for the purpose of this tutorial''

This continues and concludes the [[NMLTutorial/Train four part refit|fourth part]] of the train example. A parameter setting will be added (with a GUI for OpenTTD) to allow choosing between 1cc, 2cc or real life colours for our train. And we'll do some further visual improvements.

== GRF Parameter setting ==
The GRF parameter setting will allow choosing between 1cc, 2cc or real life colours. This is done by adding a param block to the grf block. In this param block one (named) parameter will be defined:

<pre class="example">
param {
/* There is one parameter, which can be used to alter the colour scheme */
param_colour_scheme {
type: int;
name: string(STR_PARAM_COLOUR_SCHEME_NAME);
desc: string(STR_PARAM_COLOUR_SCHEME_DESC);
/* There are currently three possible values:
* - 1cc
* - 2cc (default)
* - real-world
*/
min_value: 0;
max_value: 2;
def_value: 1;
names: {
0: string(STR_PARAM_COLOUR_SCHEME_1CC);
1: string(STR_PARAM_COLOUR_SCHEME_2CC);
2: string(STR_PARAM_COLOUR_SCHEME_REAL);
};
}
}
</pre>

The GRF parameter is named <code>param_colour_scheme</code>. This identifier needs to be unique and can be used elsewhere in the code to make decisions upon. Because we want three possible values, the GRF parameter needs to be of the integer type. The boolean type wouldn't work, as that only allows two possible values (on and off). The minimum value will be 0, the maximum 2 (resulting in three possible values 0, 1 and 2) and the default (in OpenTTD, TTDPatch always defaults to 0) will be 1. Strings are defined for the GRF parameter name and description. Each GRF parameter value will also get custom strings to display the settings rather than just numbers.

This means we have to add these strings to the language file as well:

<pre class="example">
STR_PARAM_COLOUR_SCHEME_NAME :Colour scheme
STR_PARAM_COLOUR_SCHEME_DESC :Select the type of colour scheme to use
STR_PARAM_COLOUR_SCHEME_1CC :One company colour
STR_PARAM_COLOUR_SCHEME_2CC :Two company colours
STR_PARAM_COLOUR_SCHEME_REAL :Real-world colours
</pre>

== Colour mapping callback ==
This only added the parameter setting, but it doesn't do anything yet. We'll use the <code>colour_mapping</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_callbacks callback]. This callback allows recolouring a sprite using, well errr, recolour sprites. This is a slightly complicated callback, but the first step is easy. Reference a switch block from the graphics block:

<pre class="example">
colour_mapping: sw_icm_colour_mapping;
</pre>

The switch block itself we'll just give to you, attempting to explain what it does afterwards. If you don't understand how this switch block works, just copy it or ignore the callback altogether. Try yourself at some more easy NewGRFs first to get the hang of NML and come back to this later.

<pre class="example">
switch(FEAT_TRAINS, SELF, sw_icm_colour_mapping, param_colour_scheme) {
/* Emulate 1cc by making the first colour always yellow, this looks much better (and more realistic) */
0: return palette_2cc(COLOUR_YELLOW, company_colour1);
/* Use realistic colours, i.e. yellow + dark blue */
2: return palette_2cc(COLOUR_YELLOW, COLOUR_DARK_BLUE);
/* Use the default, i.e. 2 company colours */
return base_sprite_2cc + CB_RESULT_COLOUR_MAPPING_ADD_CC;
}
</pre>

The decision of this switch block is made on the <code>param_colour_scheme</code>. The name of this variable is what we gave to it when defining the param block, so that's how you use a predefined GRF parameter. The values this GRF parameter can have are those defined in the same param block, so these values can be used as range in the switch block. It's useful to consider one value as default here, in case a user manages to make a setting outside the range of the minimum and maximum GRF parameter setting.

The <code>colour_mapping</code> needs to return the sprite number of a recolour sprite. We'll be using the default recolour sprites for this and NML has some functions and variables to retrieve these sprite numbers for you. You can find more about that in the [http://newgrf-specs.tt-wiki.net/wiki/NML:List_of_default_colour_translation_palettes NML Documentation].
; 1cc (<code>param_colour_scheme</code> == 0)
: Here we use the <code>palette_2cc</code> function even though we only want 1cc. To make the train look better we make one of the two company colours yellow rather than keeping the normal company colour range, using the <code>COLOUR_YELLOW</code> from the default [http://newgrf-specs.tt-wiki.net/wiki/NML:List_of_default_colour_translation_palettes#Company_colour_helper_functions colour constants]. The other company colour will depend on what first company colour the user has selected, which we'll get from the <code>company_colour1</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_variables vehicle variable].
; real life colours (<code>param_colour_scheme</code> == 2)
: The real life colours of this Dutch NS train are blue and yellow. We can force the train to be recoloured in these colours regardless of the company colours selected by the user. This is similar to the 1cc recolour from above, but now we return two specific colours rather than depend on the company colour variable.
; 2cc (default)
: This is what will be used as default if the GRF parameter setting is not equal to 0 or 2. Here a different way of returning the recolour sprite is used. The sprite number of the first 2cc recolour sprite can be found with the <code>base_sprite_2cc</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:General#General_variables variable]. Add <code>CB_RESULT_COLOUR_MAPPING_ADD_CC</code> to this (see the [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_callbacks callback description]) to find the company colours used.

With that the GRF parameter setting to choose the vehicle colours is done.

== Visual effect ==
The train currently has a visual effect (electric spark) on all parts of the vehicle, but only the first part has a pantograph. We can limit the effect to only this first part by using the <code>visual_effect_and_powered</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_callbacks callback]. Making a decision only on the <code>position_in_consist</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_variables variable] we can do this using a conditional assignment directly from the graphics block without the need for a switch block:

Add to the graphics block:

<pre class="example">
visual_effect_and_powered: return (position_in_consist % 4 == 0) ?
visual_effect_and_powered(VISUAL_EFFECT_ELECTRIC, 2, DISABLE_WAGON_POWER) :
visual_effect_and_powered(VISUAL_EFFECT_DISABLE, 0, DISABLE_WAGON_POWER);
</pre>

For the first part of the vehicle we return the electric spark [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Train_properties visual effect] with an offset of 2 and not making this a powered wagon. For all other parts we disable the visual effect (offset doesn't matter now) and also not make this a powered wagon.

== Lights out ==
There's one more thing that can be improved about this train. We still have not used the sprites that show no lights at the front and rear of the train. It would be nice if two EMUs are coupled that there are no lights on where the coupling is, only at the front and back.

For this we have to change the graphics switch block, not referencing the spritesets for back and front directly, but using an intermediate switch block to decide if we want lights or not.

Change the current switch block:

<pre class="example">
/* Choose between front, middle and back parts */
switch(FEAT_TRAINS, SELF, sw_icm_graphics, position_in_consist % 4) {
0: sw_icm_graphics_front;
3: sw_icm_graphics_rear;
sw_icm_graphics_middle;
}
</pre>

This now links to two additional switch blocks, one for the front and one for the rear:

<pre class="example">
/* Only the frontmost vehicle should have its lights on */
switch(FEAT_TRAINS, SELF, sw_icm_graphics_front, position_in_consist) {
0: set_icm_front_lighted;
set_icm_front;
}

/* Only the rearmost vehicle should have red lights */
switch(FEAT_TRAINS, SELF, sw_icm_graphics_rear, position_in_consist_from_end) {
0: set_icm_rear_lighted;
set_icm_rear;
}
</pre>

In case of the front part, we make a decision based on the <code>position_in_consist</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_variables variable]. If it's the very first of the consist, show front lights, otherwise show no front lights for further connected EMUs.

In case of the last part, we make a decision based on the <code>position_in_consist_from_end</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_variables variable]. This counts exactly opposite than <code>position_in_consist</code>, now starting from the back. If it's the very last of the consist, show rear lights, otherwise show no rear lights for further connected EMUs.

== Total code ==
When put in the correct order, this should now encode as a working NewGRF. The total code:

<pre class="example small">
/* Define grf */
grf {
grfid: "NML\00";
/* GRF name and description strings are defined in the lang files */
name: string(STR_GRF_NAME);
desc: string(STR_GRF_DESC);
/* This is the first version, start numbering at 0. */
version: 0;
min_compatible_version: 0;

/* Define user-configurable parameters */
param {
/* There is one parameter, which can be used to alter the colour scheme */
param_colour_scheme {
type: int;
name: string(STR_PARAM_COLOUR_SCHEME_NAME);
desc: string(STR_PARAM_COLOUR_SCHEME_DESC);
/* There are currently three possible values:
* - 1cc
* - 2cc (default)
* - real-world
*/
min_value: 0;
max_value: 2;
def_value: 1;
names: {
0: string(STR_PARAM_COLOUR_SCHEME_1CC);
1: string(STR_PARAM_COLOUR_SCHEME_2CC);
2: string(STR_PARAM_COLOUR_SCHEME_REAL);
};
}
}
}

/* Define a rail type table,
* this allows referring to railtypes
* irrespective of the grfs loaded.
*/
railtypetable {
ELRL
}

/* Basic template for 4 vehicle views */
template tmpl_vehicle_basic(x, y) {
// arguments x, y: coordinates of top-left corner of first sprite
[x, y, 8, 24, -3, -12] //xpos ypos xsize ysize xrel yrel
[x + 9, y, 22, 20, -14, -12]
[x + 32, y, 32, 16, -16, -12]
[x + 65, y, 22, 20, -6, -12]
}

/* Template for a vehicle with only 4 views (symmetric) */
template tmpl_vehicle_4_views(num) {
// argument num: Index in the graphics file, assuming vertical ordering of vehicles
tmpl_vehicle_basic(1, 1 + 32 * num)
}

/* Template for a vehicle with 8 views (non-symmetric) */
template tmpl_vehicle_8_views(num, reversed) {
// argument num: Index in the graphics file, assuming vertical ordering of vehicles
// argument reversed: Reverse visible orientation of vehicle, if set to 1
tmpl_vehicle_basic(reversed ? 89 : 1, 1 + 32 * num)
tmpl_vehicle_basic(reversed ? 1 : 89, 1 + 32 * num)
}

/* Template for a single vehicle sprite */
template tmpl_vehicle_single(num, xsize, ysize, xoff, yoff) {
[1, 1 + 32 * num, xsize, ysize, xoff, yoff]
}

/* Define the spritesets, these allow referring to these sprites later on */
spriteset (set_icm_front_lighted, "gfx/icm.png") { tmpl_vehicle_8_views(0, 0) }
spriteset (set_icm_rear_lighted, "gfx/icm.png") { tmpl_vehicle_8_views(1, 1) }
spriteset (set_icm_front, "gfx/icm.png") { tmpl_vehicle_8_views(2, 0) }
spriteset (set_icm_rear, "gfx/icm.png") { tmpl_vehicle_8_views(3, 1) }
spriteset (set_icm_middle, "gfx/icm.png") { tmpl_vehicle_4_views(4) }
spriteset (set_icm_purchase, "gfx/icm.png") { tmpl_vehicle_single(5, 53, 14, -25, -10) }
spriteset (set_icm_invisible, "gfx/icm.png") { tmpl_vehicle_single(6, 1, 1, 0, 0) }

/* --- Graphics callback --- */

/* Only the frontmost vehicle should have its lights on */
switch(FEAT_TRAINS, SELF, sw_icm_graphics_front, position_in_consist) {
0: set_icm_front_lighted;
set_icm_front;
}

/* Only the rearmost vehicle should have red lights */
switch(FEAT_TRAINS, SELF, sw_icm_graphics_rear, position_in_consist_from_end) {
0: set_icm_rear_lighted;
set_icm_rear;
}

/* In the 3-part version, the 3rd car is invisible */
switch(FEAT_TRAINS, SELF, sw_icm_graphics_middle, ((position_in_consist % 4) == 2) && (cargo_subtype == 0)) {
1: set_icm_invisible;
set_icm_middle;
}

/* Choose between front, middle and back parts */
switch(FEAT_TRAINS, SELF, sw_icm_graphics, position_in_consist % 4) {
0: sw_icm_graphics_front;
3: sw_icm_graphics_rear;
sw_icm_graphics_middle;
}

/* --- Cargo subtype text --- */
switch(FEAT_TRAINS, SELF, sw_icm_cargo_subtype_text, cargo_subtype) {
0: return string(STR_ICM_SUBTYPE_3_PART);
1: return string(STR_ICM_SUBTYPE_4_PART);
return CB_RESULT_NO_TEXT;
}

/* --- Colour mapping callback --- */
switch(FEAT_TRAINS, SELF, sw_icm_colour_mapping, param_colour_scheme) {
/* Emulate 1cc by making the first colour always yellow, this looks much better (and more realistic) */
0: return palette_2cc(COLOUR_YELLOW, company_colour1);
/* Use realistic colours, i.e. yellow + dark blue */
2: return palette_2cc(COLOUR_YELLOW, COLOUR_DARK_BLUE);
/* Use the default, i.e. 2 company colours */
return base_sprite_2cc + CB_RESULT_COLOUR_MAPPING_ADD_CC;
}

/* --- Articulated part callback --- */
switch(FEAT_TRAINS, SELF, sw_icm_articulated_part, extra_callback_info1) {
/* Add three articulated parts, for a total of four */
1 .. 3: return item_icm;
return CB_RESULT_NO_MORE_ARTICULATED_PARTS;
}

/* --- Start/stop callback --- */
switch(FEAT_TRAINS, SELF, sw_icm_start_stop, num_vehs_in_consist) {
/* Vehicles may be coupled to a maximum of 4 units (12-16 cars) */
1 .. 16: return CB_RESULT_NO_TEXT;
return string(STR_ICM_CANNOT_START);
}

/* --- Wagon attach callback --- */
switch(FEAT_TRAINS, SELF, sw_icm_can_attach_wagon, vehicle_type_id) {
/* SELF refers to the wagon here, check that it's an ICM */
item_icm: return CB_RESULT_ATTACH_ALLOW;
return string(STR_ICM_CANNOT_ATTACH_OTHER);
}

/* --- Shorten vehicle callback --- */
switch(FEAT_TRAINS, SELF, sw_icm_shorten_3_part_vehicle, position_in_consist % 4) {
/* In the three part version, shorten the 2nd vehicle to 7/8 and the 3rd to 1/8
* The rear (1/8) part is then made invisisble */
1: return 7;
2: return 1;
return 8;
}

switch(FEAT_TRAINS, SELF, sw_icm_shorten_vehicle, cargo_subtype) {
0: sw_icm_shorten_3_part_vehicle;
return 8; // 4-part vehicle needs no shortening
}

/* Power, weight and TE are all applied to the front vehicle only */
switch(FEAT_TRAINS, SELF, sw_icm_power, cargo_subtype) {
0: return int(1260 / 0.7457); // kW -> hp
return int(1890 / 0.7457); // kW -> hp
}

switch(FEAT_TRAINS, SELF, sw_icm_weight, cargo_subtype) {
0: return 144; //ton, 3 part train
return 192; //ton, 4 part train
}

switch(FEAT_TRAINS, SELF, sw_icm_te, cargo_subtype) {
/* Base TE coefficient = 0.3
* 3 parts: 4/12 of weight on driving wheels
* 4 parts: 6/16 of weight on driving wheels */
0: return int(0.3 * 255 / 3);
return int(0.3 * 255 * 3 / 8);
}

/* Define the actual train */
item(FEAT_TRAINS, item_icm) {
/* Define properties first, make sure to set all of them */
property {
name: string(STR_ICM_NAME);
// not available in toyland:
climates_available: bitmask(CLIMATE_TEMPERATE, CLIMATE_ARCTIC, CLIMATE_TROPICAL);
introduction_date: date(1983, 1, 1);
model_life: VEHICLE_NEVER_EXPIRES;
vehicle_life: 30;
reliability_decay: 20;
refittable_cargo_classes: bitmask(CC_PASSENGERS);
non_refittable_cargo_classes: bitmask();
// refitting is done via cargo classes only, no cargo types need explicit enabling/disabling
// It's an intercity train, loading is relatively slow:
loading_speed: 6;
cost_factor: 45;
running_cost_factor: 100; // Changed by callback
sprite_id: SPRITE_ID_NEW_TRAIN;
speed: 141 km/h; // actually 140, but there are rounding errors
misc_flags: bitmask(TRAIN_FLAG_2CC, TRAIN_FLAG_MU);
refit_cost: 0; //refit costs don't apply to subcargo display
// callback flags are not set manually
track_type: ELRL; // from rail type table
ai_special_flag: AI_FLAG_PASSENGER;
power: 1260 kW; // Changed by CB
running_cost_base: RUNNING_COST_ELECTRIC;
dual_headed: 0;
cargo_capacity: 36; // per part, changed by callback
weight: 144 ton; // Total, changed by callback
ai_engine_rank: 0; // not intended to be used by the ai
engine_class: ENGINE_CLASS_ELECTRIC;
extra_power_per_wagon: 0 kW;
// 4/12 of weight on driving wheels, with a default friction coefficient of 0.3:
tractive_effort_coefficient: 0.3 / 3; // changed by callback
air_drag_coefficient: 0.06;
shorten_vehicle: SHORTEN_TO_8_8;
// Overridden by callback to disable for non-powered wagons:
visual_effect_and_powered: visual_effect_and_powered(VISUAL_EFFECT_ELECTRIC, 2, DISABLE_WAGON_POWER);
extra_weight_per_wagon: 0 ton;
bitmask_vehicle_info: 0;
}
/* Define graphics and callbacks
* Setting all callbacks is not needed, only define what is used */
graphics {
default: sw_icm_graphics;
purchase: set_icm_purchase;
cargo_subtype_text: sw_icm_cargo_subtype_text;
additional_text: return string(STR_ICM_ADDITIONAL_TEXT);
colour_mapping: sw_icm_colour_mapping;
start_stop: sw_icm_start_stop;
articulated_part: sw_icm_articulated_part;
can_attach_wagon: sw_icm_can_attach_wagon;
running_cost_factor: return (cargo_subtype == 1) ? 150 : 100;
/* Capacity is per part */
cargo_capacity: return (cargo_subtype == 0) && ((position_in_consist % 4) == 2) ? 0 : 36;
/* In the purchase menu, we want to show the capacity for the three-part version,
* i.e. divide the capacity of three cars across four */
purchase_cargo_capacity: return 36 * 3 / 4;
/* Only the front vehicle has a visual effect */
visual_effect_and_powered: return (position_in_consist % 4 == 0) ?
visual_effect_and_powered(VISUAL_EFFECT_ELECTRIC, 2, DISABLE_WAGON_POWER) :
visual_effect_and_powered(VISUAL_EFFECT_DISABLE, 0, DISABLE_WAGON_POWER);
length: sw_icm_shorten_vehicle;
/* Only the front vehicle has power */
power: sw_icm_power;
//purchase_power: return int(1260 / 0.7457); // kW -> hp
/* Only the front vehicle has weight */
weight: sw_icm_weight;
/* Only the front vehicle has TE */
tractive_effort_coefficient: sw_icm_te;
/* Only 1/3 of the weight is on the driving weels. */
}
}
</pre>

=== The complete language file ===
english.lng now contains this:

<pre class="example small">
##grflangid 0x01

STR_GRF_NAME :NML Example NewGRF: Train
STR_GRF_DESC :{ORANGE}NML Example NewGRF: Train{}{BLACK}This NewGRF is intended to provide a coding example for the high-level NewGRF-coding language NML.{}Original graphics by {SILVER}Purno, {BLACK}coding by {SILVER}DJNekkid.{}{BLACK}This NewGRF defines a Dutch EMU, the ICM 'Koploper'.

STR_PARAM_COLOUR_SCHEME_NAME :Colour scheme
STR_PARAM_COLOUR_SCHEME_DESC :Select the type of colour scheme to use
STR_PARAM_COLOUR_SCHEME_1CC :One company colour
STR_PARAM_COLOUR_SCHEME_2CC :Two company colours
STR_PARAM_COLOUR_SCHEME_REAL :Real-world colours

STR_ICM_NAME :ICM 'Koploper' (Electric)
STR_ICM_ADDITIONAL_TEXT :Choose between 3- and 4-part EMU via refit{}Stated values are for the 3-part variant, the 4-part version has 33% more capacity and 50% more power and running cost.
STR_ICM_SUBTYPE_3_PART : (3 parts)
STR_ICM_SUBTYPE_4_PART : (4 parts)
STR_ICM_CANNOT_START :... train too long (max. 4 coupled EMUs).
STR_ICM_CANNOT_ATTACH_OTHER :... only other ICMs can be attached to ICM.
</pre>

Now our train is really completed and that makes this the end of the train example.

{{NMLTutorialNavbar|Parameters|Object}}

NMLTutorial/Train four part refit

2013-12-08T13:37:15Z

Frosch: c&p error between cargo subtypes and artic parts

{{NMLTutorial}}
''The example used here is from the [http://dev.openttdcoop.org/projects/nml/repository/show/examples NML source]. The code for this was originally written in NFO by DJNekkid for the 2cc Trainset and rewritten in NML by Hirundo. The graphics used in the example are by Purno. Code and graphics are both licensed according to the GPL v2 or later. The code has been modified for the purpose of this tutorial''

This continues the [[NMLTutorial/Train three part articulated|third part]] of the train example. The three part EMU will be made refittable to a four part EMU.

== What's going to happen ==
A lot of things need to be added to make this train refittable between three and four parts.

The method used to do this is actually the other way round than the user will think from the behaviour ingame. The train will be changed to a four part EMU. For the (default) three part refit one of these four parts will be hidden. A lot of switches will be used to make the train look right, make it have the correct capacity, power, weight, running costs and tractive effort.

There are some drawbacks to this method. There is a way to charge the player for the extra vehicle part, but it has some issues, and we shall not bother with it here (if you want more details, feel free to check out [http://www.tt-forums.net/viewtopic.php?f=26&t=62672#p1046538 the source code of the Fake Subways GRF]). Also autoreplacing will be difficult, as there's no way for the user to select which vehicle length they want. For that reason the author of this tutorial thinks making two different vehicles and having both available from the purchase menu is a better solution, but this method is a good illustration for some of the more advanced features of NML. It's up to you to decide which implementation you think is best for your vehicles.

What we'll be doing:
* Add the refit option;
* Make the graphics work;
* Add callbacks to supply the correct vehicle properties;
* Make the purchase menu display the correct values.

== Refit option ==
The refit option will be added by means of the "cargo subtype". This allows to split each cargo into multiple entities which can be assigned different properties by means of other callbacks.

The first step towards this is defining names for these separate entries using the <code>cargo_subtype_text</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_callbacks callback]. This callback requires the use of a switch, so reference a switch from the graphics block:

<pre style="color:darkblue; white-space: pre-wrap">
cargo_subtype_text: sw_icm_cargo_subtype_text;
</pre>

The switch itself will use the <code>cargo_subtype</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_variables variable]. This variable starts at 0 and will be increased by 1 until the callback returns <code>CB_RESULT_NO_TEXT</code>. Return strings to use as cargo subtype. Each returned string will be a separate cargo subtype:

<pre style="color:darkblue; white-space: pre-wrap">
switch(FEAT_TRAINS, SELF, sw_icm_cargo_subtype_text, cargo_subtype) {
0: return string(STR_ICM_SUBTYPE_3_PART);
1: return string(STR_ICM_SUBTYPE_4_PART);
return CB_RESULT_NO_TEXT;
}
</pre>

This adds two cargo subtypes. Also add these strings to the language file:

<pre style="color:darkblue; white-space: pre-wrap">
STR_ICM_SUBTYPE_3_PART : (3 parts)
STR_ICM_SUBTYPE_4_PART : (4 parts)
</pre>

== Graphics ==
The graphics defined previously were for a three part vehicle. Now we have to make this into a four part vehicle and hide one wagon for the three part refit.

=== Four part articulated vehicle ===
In order to make the vehicle four parts, the articulated vehicle callback switch needs to be changed:

<pre style="color:darkblue; white-space: pre-wrap">
switch(FEAT_TRAINS, SELF, sw_icm_articulated_part, extra_callback_info1) {
/* Add three articulated parts, for a total of four */
1 .. 3: return item_icm;
return CB_RESULT_NO_MORE_ARTICULATED_PARTS;
}
</pre>

This is done by changing the value range from <code>1 .. 2</code> into <code>1 .. 3</code>.

=== Start/stop callback ===
The start/stop callback checking the vehicle length needs to be changed as well. If we still want a maximum of four EMUs, the maximum length will now be 4 * 4 instead of 4 * 3. This means changing the switch for this callback:

<pre style="color:darkblue; white-space: pre-wrap">
switch(FEAT_TRAINS, SELF, sw_icm_start_stop, num_vehs_in_consist) {
/* Vehicles may be coupled to a maximum of 4 units (12-16 cars) */
1 .. 16: return CB_RESULT_NO_TEXT;
return string(STR_ICM_CANNOT_START);
}
</pre>

This is done by changing the value range from <code>1 .. 12</code> into <code>1 .. 16</code>.

=== Graphics ===
Now that the vehicle is four parts, the default graphics switch needs to be changed as well to allow for two middle parts instead of one:

<pre style="color:darkblue; white-space: pre-wrap">
switch(FEAT_TRAINS, SELF, sw_icm_graphics, position_in_consist % 4) {
0: set_icm_front_lighted;
3: set_icm_rear_lighted;
sw_icm_graphics_middle;
}
</pre>

Instead of modulo 3 we're now taking modulo 4. And the value for the rear vehicle part was changed from 2 to 3. For the middle parts, we also need to hide the one of the wagons for the three part EMU. Therefore we can't directly reference the spriteset but need an extra intermediate switch block.

The extra switch block:

<pre style="color:darkblue; white-space: pre-wrap">
switch(FEAT_TRAINS, SELF, sw_icm_graphics_middle, ((position_in_consist % 4) == 2) && (cargo_subtype == 0)) {
1: set_icm_invisible;
set_icm_middle;
}
</pre>

Even an expression this advanced can be used for switch block decision. Here we again check the position of the vehicle part, but also which cargo subtype is used for this vehicle. If it is the three part EMU (cargo subtype 0) AND it is the third vehicle part (position 2 counting from 0), we hide this vehicle part by displaying no graphics for it. In all other cases we display the regular middle part.

=== Vehicle length ===
If you were to encode the result so far as a NewGRF, you end up with a three part train that has a big gap between the second and last part. This is because it's essentially still a four part vehicle, just with no graphics for the third part. This can be solved by changing the length of the two middle parts. If we make the second part (7/8) long and the third part (1/8), both together are a full wagon length, completely hiding the invisible third part.

This is done by means of the <code>length</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_callbacks callback], referencing a switch block as we first need to differentiate between the two cargo subtypes and then by the position in consist. Reference the switch block from the graphics block:

<pre style="color:darkblue; white-space: pre-wrap">
length: sw_icm_shorten_vehicle;
</pre>

Then we get the two switch blocks:

<pre style="color:darkblue; white-space: pre-wrap">
/* --- Shorten vehicle callback --- */
switch(FEAT_TRAINS, SELF, sw_icm_shorten_3_part_vehicle, position_in_consist % 4) {
/* In the three part version, shorten the 2nd vehicle to 7/8 and the 3rd to 1/8
* The rear (1/8) part is then made invisisble */
1: return 7;
2: return 1;
return 8;
}

switch(FEAT_TRAINS, SELF, sw_icm_shorten_vehicle, cargo_subtype) {
0: sw_icm_shorten_3_part_vehicle;
return 8; // 4-part vehicle needs no shortening
}
</pre>

The second of these switch blocks (called first from the graphics block) differentiates between the two cargo subtypes. For subtype 0 (three part vehicle) we need to do the shortenings and reference the first switch block. For the four part vehicle we need no shortening, so directly return to "shorten" to full length.

The first switch again makes a decision based on the <code>position_in_consist</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_variables variable] we've seen several times now. As said, the second part will be shortened to (7/8), the third part to (1/8) and the front and back part are kept full length (8/8).

Now the vehicle looks good in both refits.

== Vehicle properties ==
Both refits still have identical properties. Surely the four part EMU has a higher capacity. We'll also change the running costs, power, weight and tractive effort depending on the refit chosen. This is all done by callbacks. You can find the available vehicle callbacks [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_callbacks here], with the second table especially on callbacks that change certain properties.

=== Running cost factor ===
You can easily imagine that the longer vehicle will be more expensive to run. The three part has a running cost factor of 100, the four part will get a factor of 150. This requires adding the <code>running_cost_factor</code> callback to the graphics block. From there we can link to a switch block and base the decision on the <code>cargo_subtype</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_variables variable]. A different method as shown below is not to use a switch block but to make the decision directly from the graphics block using a conditional assignment. We've used a conditional assignment [[Train_single_engine#Templates|before]] in one of the template blocks.

Add to the graphics block:

<pre style="color:darkblue; white-space: pre-wrap">
running_cost_factor: return (cargo_subtype == 1) ? 150 : 100;
</pre>

In case the <code>cargo_subtype</code> is 1 (the four part vehicle), a running cost factor of 150 is used. Otherwise, a factor of 100 is used. If you'd rather used a switch block then that's up to you. Just reference one from the graphics block instead of the conditional assignment and use the switch block to make the decision based on the <code>cargo_subtype</code> variable.

=== Cargo capacity ===
The cargo capacity is 36 passengers per unit. Now the three part EMU will have a capacity that is too high, because it technically is a four part EMU with one part hidden. We need to give this hidden part 0 capacity.

This is done by the <code>cargo_capacity</code> callback. If the <code>cargo_subtype</code> is 0 and the <code>position_in_consist</code> is the third part, we give it 0 capacity. Else it will get 36 capacity. Also this can be done directly from the graphics block, using a slightly more advanced conditional assignment. Of course you could again have used a switch block here, but there's no need for that in this case.

Add to the graphics block:

<pre style="color:darkblue; white-space: pre-wrap">
cargo_capacity: return (cargo_subtype == 0) && ((position_in_consist % 4) == 2) ? 0 : 36;
</pre>

=== Power ===
The power of the four part vehicle will be higher. Let's use a switch block this time. Of course a conditional assignment could be used here, but compare this example with the running cost factor yourself. The callback used here is called <code>power</code>.

Reference the switch block from the graphics block:

<pre style="color:darkblue; white-space: pre-wrap">
power: sw_icm_power;
</pre>

The switch block itself will again make a decision based on the <code>cargo_subtype</code> variable. The callback must return the vehicle power in horsepower (imperial) and this must be an integer value. Because we know the power in kW, a little calculation is needed which NML can do for you. Returning the integer is done by the <code>int()</code> function that turns a (decimal) number into an integer.

<pre style="color:darkblue; white-space: pre-wrap">
switch(FEAT_TRAINS, SELF, sw_icm_power, cargo_subtype) {
0: return int(1260 / 0.7457); // kW -> hp
return int(1890 / 0.7457); // kW -> hp
}
</pre>

=== Weight ===
Of course you could have done the calculation yourself and put the rounded values in the switch block. That we'll do for the weight of the vehicle. The callback used here is called <code>weight</code>.

Again, reference the switch block from the graphics block:

<pre style="color:darkblue; white-space: pre-wrap">
weight: sw_icm_weight;
</pre>

The switch block itself will again make a decision based on the <code>cargo_subtype</code> variable. The weight here must be specified in tons:

<pre style="color:darkblue; white-space: pre-wrap">
switch(FEAT_TRAINS, SELF, sw_icm_weight, cargo_subtype) {
0: return 144; //ton, 3 part train
return 192; //ton, 4 part train
}
</pre>

=== Tractive effort coefficient===
The last property to sort out is the tractive effort. The callback used here is called <code>tractive_effort_coefficient</code>.

Again, reference the switch block from the graphics block:

<pre style="color:darkblue; white-space: pre-wrap">
tractive_effort_coefficient: sw_icm_te;
</pre>

In the switch block we'll actually calculate the tractive effort coefficient:

<pre style="color:darkblue; white-space: pre-wrap">
switch(FEAT_TRAINS, SELF, sw_icm_te, cargo_subtype) {
/* Base TE coefficient = 0.3
* 3 parts: 4/12 of weight on driving wheels
* 4 parts: 6/16 of weight on driving wheels */
0: return int(0.3 * 255 / 3);
return int(0.3 * 255 * 3 / 8);
}
</pre>

''The technical background of the tractive effort coefficient is that it must be supplied as value between 0 and 255, with 255 equal to 100%. The tractive effort coefficient itself is calculated by multiplying the friction coefficient (see [http://en.wikipedia.org/wiki/Rail_adhesion Wikipedia] for it's meaning) with the percentage of weight that is on driven wheels. I this case we use a friction of 30%. In real life the three part vehicle has 12 axles of which 4 powered. The four part vehicle has 16 axles of which 6 powered. Assuming an equal distribution of weight along the length of the vehicle, the three part vehicle has 33.3% of it's weight on powered wheels. The four part vehicle has 37.5% of it's weight on powered wheels. Multiply both by the friction coefficient and the factor of 255 and you have the tractive effort coefficient.''

''If you don't provide a tractive effort coefficient, the game will assume a friction coefficient of 0.3 and all axles powered. A tractive effort coefficient of 100% you'll only get with 100% friction and and all axles powered. This is unrealistic for railroads but can be used for maglev when there actually is no contact between vehicle and guideway.''

== Purchase menu ==
With all these callbacks we've sort of broken the display of properties in the purchase menu. This is because the <code>position_in_consist</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_variables variable] is not available in the purchase menu and <code>cargo_subtype</code> variable is always 0 in the purchase menu. The latter can be to our advantage if we want to display the properties of the shorter refit, but the other needs some fixing.

=== Running cost factor ===
This callback was only based on <code>cargo_subtype</code>, so no fixing needed here.

=== Cargo capacity ===
The capacity used both variables, so some fixing is in order here. We want to display 36*3 as capacity. Because capacity is defined per unit and our vehicle is technically four units, we need to divide this over four units: 36*3/4. Add the <code>purchase_cargo_capacity</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_callbacks callback] to the graphics block and return this value:

<pre style="color:darkblue; white-space: pre-wrap">
purchase_cargo_capacity: return 36 * 3 / 4;
</pre>

=== Power, weight and tractive effort coefficient ===
Luckily, these are also only based on the cargo subtype variable, so no fixing needed. If you wanted a different value to be displayed in the purchase menu, you'd use the <code>purchase_power</code>, <code>purchase_weight</code> and <code>purchase_tractive_effort_coefficient</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_callbacks callbacks] to do this. And if you want to know, the running cost factor would logically use the <code>purchase_running_cost_factor</code> callback.

=== Additional text ===
We want to inform the user that this train has an option to refit it into a four part version and that the properties shown are for the three part version. For this we'll use the <code>additional_text</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_callbacks callback] which we also used in the tram example. It can directly return a string from the graphics block:

<pre style="color:darkblue; white-space: pre-wrap">
additional_text: return string(STR_ICM_ADDITIONAL_TEXT);
</pre>

Also don't forget to add this string to the language file:

<pre style="color:darkblue; white-space: pre-wrap">
STR_ICM_ADDITIONAL_TEXT :Choose between 3- and 4-part EMU via refit{}Stated values are for the 3-part variant, the 4-part version has 33% more capacity and 50% more power and running cost.
</pre>

This means our vehicle now works like it should with the two refits. Encode it into a NewGRF if you like.

== Total code so far ==
When put in the correct order, this should now encode as a working NewGRF. The total code so far:

<pre style="color:darkblue; white-space: pre-wrap; max-height: 200px; overflow:scroll">
/* Define grf */
grf {
grfid: "NML\00";
/* GRF name and description strings are defined in the lang files */
name: string(STR_GRF_NAME);
desc: string(STR_GRF_DESC);
/* This is the first version, start numbering at 0. */
version: 0;
min_compatible_version: 0;
}

/* Define a rail type table,
* this allows referring to railtypes
* irrespective of the grfs loaded.
*/
railtypetable {
ELRL
}

/* Basic template for 4 vehicle views */
template tmpl_vehicle_basic(x, y) {
// arguments x, y: coordinates of top-left corner of first sprite
[x, y, 8, 24, -3, -12] //xpos ypos xsize ysize xrel yrel
[x + 9, y, 22, 20, -14, -12]
[x + 32, y, 32, 16, -16, -12]
[x + 65, y, 22, 20, -6, -12]
}

/* Template for a vehicle with only 4 views (symmetric) */
template tmpl_vehicle_4_views(num) {
// argument num: Index in the graphics file, assuming vertical ordering of vehicles
tmpl_vehicle_basic(1, 1 + 32 * num)
}

/* Template for a vehicle with 8 views (non-symmetric) */
template tmpl_vehicle_8_views(num, reversed) {
// argument num: Index in the graphics file, assuming vertical ordering of vehicles
// argument reversed: Reverse visible orientation of vehicle, if set to 1
tmpl_vehicle_basic(reversed ? 89 : 1, 1 + 32 * num)
tmpl_vehicle_basic(reversed ? 1 : 89, 1 + 32 * num)
}

/* Template for a single vehicle sprite */
template tmpl_vehicle_single(num, xsize, ysize, xoff, yoff) {
[1, 1 + 32 * num, xsize, ysize, xoff, yoff]
}

/* Define the spritesets, these allow referring to these sprites later on */
spriteset (set_icm_front_lighted, "gfx/icm.png") { tmpl_vehicle_8_views(0, 0) }
spriteset (set_icm_rear_lighted, "gfx/icm.png") { tmpl_vehicle_8_views(1, 1) }
spriteset (set_icm_front, "gfx/icm.png") { tmpl_vehicle_8_views(2, 0) }
spriteset (set_icm_rear, "gfx/icm.png") { tmpl_vehicle_8_views(3, 1) }
spriteset (set_icm_middle, "gfx/icm.png") { tmpl_vehicle_4_views(4) }
spriteset (set_icm_purchase, "gfx/icm.png") { tmpl_vehicle_single(5, 53, 14, -25, -10) }
spriteset (set_icm_invisible, "gfx/icm.png") { tmpl_vehicle_single(6, 1, 1, 0, 0) }

/* --- Graphics callback --- */

/* In the 3-part version, the 3rd car is invisible */
switch(FEAT_TRAINS, SELF, sw_icm_graphics_middle, ((position_in_consist % 4) == 2) && (cargo_subtype == 0)) {
1: set_icm_invisible;
set_icm_middle;
}

/* Choose between front, middle and back parts */
switch(FEAT_TRAINS, SELF, sw_icm_graphics, position_in_consist % 4) {
0: set_icm_front_lighted;
3: set_icm_rear_lighted;
set_icm_middle;
}

/* --- Cargo subtype text --- */
switch(FEAT_TRAINS, SELF, sw_icm_cargo_subtype_text, cargo_subtype) {
0: return string(STR_ICM_SUBTYPE_3_PART);
1: return string(STR_ICM_SUBTYPE_4_PART);
return CB_RESULT_NO_TEXT;
}

/* --- Articulated part callback --- */
switch(FEAT_TRAINS, SELF, sw_icm_articulated_part, extra_callback_info1) {
/* Add three articulated parts, for a total of four */
1 .. 3: return item_icm;
return CB_RESULT_NO_MORE_ARTICULATED_PARTS;
}

/* --- Start/stop callback --- */
switch(FEAT_TRAINS, SELF, sw_icm_start_stop, num_vehs_in_consist) {
/* Vehicles may be coupled to a maximum of 4 units (12-16 cars) */
1 .. 16: return CB_RESULT_NO_TEXT;
return string(STR_ICM_CANNOT_START);
}

/* --- Wagon attach callback --- */
switch(FEAT_TRAINS, SELF, sw_icm_can_attach_wagon, vehicle_type_id) {
/* SELF refers to the wagon here, check that it's an ICM */
item_icm: return CB_RESULT_ATTACH_ALLOW;
return string(STR_ICM_CANNOT_ATTACH_OTHER);
}

/* --- Shorten vehicle callback --- */
switch(FEAT_TRAINS, SELF, sw_icm_shorten_3_part_vehicle, position_in_consist % 4) {
/* In the three part version, shorten the 2nd vehicle to 7/8 and the 3rd to 1/8
* The rear (1/8) part is then made invisisble */
1: return 7;
2: return 1;
return 8;
}

switch(FEAT_TRAINS, SELF, sw_icm_shorten_vehicle, cargo_subtype) {
0: sw_icm_shorten_3_part_vehicle;
return 8; // 4-part vehicle needs no shortening
}

/* Power, weight and TE are all applied to the front vehicle only */
switch(FEAT_TRAINS, SELF, sw_icm_power, cargo_subtype) {
0: return int(1260 / 0.7457); // kW -> hp
return int(1890 / 0.7457); // kW -> hp
}

switch(FEAT_TRAINS, SELF, sw_icm_weight, cargo_subtype) {
0: return 144; //ton, 3 part train
return 192; //ton, 4 part train
}

switch(FEAT_TRAINS, SELF, sw_icm_te, cargo_subtype) {
/* Base TE coefficient = 0.3
* 3 parts: 4/12 of weight on driving wheels
* 4 parts: 6/16 of weight on driving wheels */
0: return int(0.3 * 255 / 3);
return int(0.3 * 255 * 3 / 8);
}

/* Define the actual train */
item(FEAT_TRAINS, item_icm) {
/* Define properties first, make sure to set all of them */
property {
name: string(STR_ICM_NAME);
// not available in toyland:
climates_available: bitmask(CLIMATE_TEMPERATE, CLIMATE_ARCTIC, CLIMATE_TROPICAL);
introduction_date: date(1983, 1, 1);
model_life: VEHICLE_NEVER_EXPIRES;
vehicle_life: 30;
reliability_decay: 20;
refittable_cargo_classes: bitmask(CC_PASSENGERS);
non_refittable_cargo_classes: bitmask();
// refitting is done via cargo classes only, no cargo types need explicit enabling/disabling
// It's an intercity train, loading is relatively slow:
loading_speed: 6;
cost_factor: 45;
running_cost_factor: 100; // Changed by callback
sprite_id: SPRITE_ID_NEW_TRAIN;
speed: 141 km/h; // actually 140, but there are rounding errors
misc_flags: bitmask(TRAIN_FLAG_2CC, TRAIN_FLAG_MU);
refit_cost: 0; //refit costs don't apply to subcargo display
// callback flags are not set manually
track_type: ELRL; // from rail type table
ai_special_flag: AI_FLAG_PASSENGER;
power: 1260 kW; // Changed by CB
running_cost_base: RUNNING_COST_ELECTRIC;
dual_headed: 0;
cargo_capacity: 36; // per part, changed by callback
weight: 144 ton; // Total, changed by callback
ai_engine_rank: 0; // not intended to be used by the ai
engine_class: ENGINE_CLASS_ELECTRIC;
extra_power_per_wagon: 0 kW;
// 4/12 of weight on driving wheels, with a default friction coefficient of 0.3:
tractive_effort_coefficient: 0.3 / 3; // changed by callback
air_drag_coefficient: 0.06;
shorten_vehicle: SHORTEN_TO_8_8;
// Overridden by callback to disable for non-powered wagons:
visual_effect_and_powered: visual_effect_and_powered(VISUAL_EFFECT_ELECTRIC, 2, DISABLE_WAGON_POWER);
extra_weight_per_wagon: 0 ton;
bitmask_vehicle_info: 0;
}
/* Define graphics and callbacks
* Setting all callbacks is not needed, only define what is used */
graphics {
default: sw_icm_graphics;
purchase: set_icm_purchase;
cargo_subtype_text: sw_icm_cargo_subtype_text;
additional_text: return string(STR_ICM_ADDITIONAL_TEXT);
start_stop: sw_icm_start_stop;
articulated_part: sw_icm_articulated_part;
can_attach_wagon: sw_icm_can_attach_wagon;
running_cost_factor: return (cargo_subtype == 1) ? 150 : 100;
/* Capacity is per part */
cargo_capacity: return (cargo_subtype == 0) && ((position_in_consist % 4) == 2) ? 0 : 36;
/* In the purchase menu, we want to show the capacity for the three-part version,
* i.e. divide the capacity of three cars across four */
purchase_cargo_capacity: return 36 * 3 / 4;
length: sw_icm_shorten_vehicle;
/* Only the front vehicle has power */
power: sw_icm_power;
/* Only the front vehicle has weight */
weight: sw_icm_weight;
/* Only the front vehicle has TE */
tractive_effort_coefficient: sw_icm_te;
/* Only 1/3 of the weight is on the driving weels. */
}
}
</pre>

=== Language file so far ===
english.lng now contains this:

<pre style="color:darkblue; white-space: pre-wrap; max-height: 200px; overflow:scroll">
##grflangid 0x01

STR_GRF_NAME :NML Example NewGRF: Train
STR_GRF_DESC :{ORANGE}NML Example NewGRF: Train{}{BLACK}This NewGRF is intended to provide a coding example for the high-level NewGRF-coding language NML.{}Original graphics by {SILVER}Purno, {BLACK}coding by {SILVER}DJNekkid.{}{BLACK}This NewGRF defines a Dutch EMU, the ICM 'Koploper'.

STR_ICM_NAME :ICM 'Koploper' (Electric)
STR_ICM_ADDITIONAL_TEXT :Choose between 3- and 4-part EMU via refit{}Stated values are for the 3-part variant, the 4-part version has 33% more capacity and 50% more power and running cost.
STR_ICM_SUBTYPE_3_PART : (3 parts)
STR_ICM_SUBTYPE_4_PART : (4 parts)
STR_ICM_CANNOT_START :... train too long (max. 4 coupled EMUs).
STR_ICM_CANNOT_ATTACH_OTHER :... only other ICMs can be attached to ICM.
</pre>

If you like, this train is done. If you like to continue, you can learn about GRF parameters and then we'll add a parameter setting to display this train in either 1cc, 2cc or real life colours.

{{NMLTutorialNavbar|Train three part articulated|Parameters}}

Callbacks Tutorial

2009-06-21T15:04:44Z

Frosch:

'''''Tutorial on using callbacks'''''

=Callbacks in Graphics Files=

Since TTDPatch 2.0.1 alpha 11, it is possible to use callbacks, in which the graphics files can influence how TTDPatch features work. This is a lot more sophisticated than simply using action 0 to choose various settings, in that callbacks can use the full capabilities of variational and random action 2 entries.

-=How it works=-

When the patch wants to use the value of certain properties, it can ask the graphics file what value to use, instead of simply looking it up in the table set by action 0. It does this if the corresponding callback bit has been set in the vehicle's action 0 properties. Then, the following happens:
* The patch sets the current callback ID, variable 0C, according to what callback it is
* Then, the patch starts at the vehicle's action 3 entry and finds the initial action 2 number to use
* The patch then follows the chain of variational/random action 2 entries
* The set-id of the final action 2 is used as result for the callback

Because callbacks are different from regular vehicle graphics, the last action 2 in the chain must have a set-id with bit 15 set (e.g. XX 80 to return XX), which is invalid for regular graphics.  Therefore, at least one action 2 in the chain must check the variable 0C, to decide whether this is a callback or the determination of graphics.

-=How to define callbacks=-

There are several things you have to do to get callbacks to work.
# If necessary, enable the callback. For vehicles, set the callback bit in the [[Action0|action 0]] property for the vehicle which should use callbacks (props 1E, 17, 12 or 14 depending on vehicle type)
# Set a default for the value that the callback modifies, e.g. set prop 07 when using the load amount callback
# Define an [[Action3|action 3]] for the vehicle if it doesn't have one already
# Add a [[VariationalAction2|variational action 2]] that checks the callback variable 0C for the value of the callback. See the description of a variational action 2 to find what values those are.
# Variable 0C should be accessed as a word. Even when the callbacks IDs you want to test are below 0xFF.
# This variational action 2 has to return a callback result (set-id with bit 15 set) when in a callback, or a regular set-id when not in a callback
# Make sure that the "default" of the var. 0C check (corresponding to unknown callbacks) points to a regular action 2 instead of one that returns callback results, ideally using the same action 2 as in the non-callback case. This way, unknown callbacks will fail instead of returning valid, but wrong, results.

As explained above, a callback result is something like -+06 80+- (with 06 being used as value of the callback), instead of a regular set-id that would be for example -+04 00+-.

-=Examples=-

Be aware that following examples don't result into 100% complete newgrfs, but instead concentrate on the most important code features. E.g., in the given [[Action0Trains|action0s]] you'd have to add even more properties to get a well-working newgrf, or, in case an example describes only one vehicle in detail, references to other vehicles, e.g. a locomotive, are given in a symbolic form ("xx", "nn") rather than implementing it in detail and giving correct veh-IDs or c-IDs.

-=Example1: using Callback 33 (new sounds)=-

The first example is a simple application. It will set new sounds for a locomotive by using [[Callbacks#Sound_effect_callback_33_|callback 33]]. The new sounds will be supplied by two .wav files using [[Action11|action 11]]. Newly defined sounds will start from slot 73 (49h), numbers 0 - 48h being original TTD sounds. The type of event (under which circumstances a particular sound should be played) is read from variable 10.

<pre>~pp~

0 * 4    0F 00 00 00

// add an action 08

1 * 8    08 02 xx xx xx xx 00 00

// set engine (00) to use new sprites, enable for callback 33

2 * 9    00 00 02 01 00

       12 FD    // use new sprites

       1E 80    // enable CB 33

// define sound files, first available slot being 49h

3 * 3    11 02 00

4 ** C:\ttdlx\newgrf\sprites\start.wav    // 49: whistle (departure)

5 ** C:\ttdlx\newgrf\sprites\tunnel.wav    // 4A: whistle (in tunnel)

// engine sprites go here

6 * 4    01 00 01 04

[...]    // 4 sprites for engine

// c-ID 0 use above set of sprites

11 * 9    02 00 00 01 01 00 00 00 00    // engine

// sound events are read from var10:

12 * 18    02 00 01 81 10 00 FF 02

       49 80 01 01    // whistle: departure

       4A 80 02 02    // whistle: in tunnel

       00 00        // else CB fail

// switch between callback and graphics branch

13 * 14    02 00 02 85 0C 00 FF FF 01

       01 00 33 00 33 00    // is CB 33, set sound

       00 00            // graphics

14 * 7    03 00 01 00 00 02 00    // engine

~/pp~</pre>

-=Example2: using Callbacks 12, 15, and 19=-

Suppose you want to build passenger coaches with both first and second class, having different livery and capacity, loading amount, and additional text suffixes. For this to work we'll need callbacks [[Callbacks#Load_amount_callback_12_|12 (load amount]]), [[Callbacks#Refitted_capacity_callback_15_|15 (refitted capacity]]) and [[Callbacks#Cargo_Subtype_Display_19_|19 (cargo subtype display]]):

In addition, we'll use the feature [[VarAction2Vehicles|"refit to same cargo type"]] to be able to change livery, loading amount and capacity deliberately, even if coaches carry only one type of cargo, namely "passengers".

In the .nfo, the actual "refitting" is done by referencing variable F2, which holds how many times a vehicle was refitted to the same cargo type. In game, there will be two entries generated in the refit menu containing these text suffixes generated by an [[Action4|action 4]]. Namely "passengers (1st class)" and "passengers (2nd class)" from which to choose the desired type of coach. Likewise, load amount and capacity are linked to variable F2 as well and will be changed accordingly.

<pre>~pp~

0 * 4    15 00 00 00

// add an action 08

1 * 8    08 02 xx xx xx xx 00 00

// define additional text suffixes

2 * 0    04 00 1F 02 00 D0

       " (1st class)" 00    // D000 = "1st class"

                  " (2nd class)" 00    // D001 = "2nd class"

// set coach (1B) to use new sprites,

// enable for callbacks 12, 15 and 19

3 * 9    00 00 02 01 1B

       12 FD    // use new sprites

       1E 2C    // enable CB 12, 15 and 19

// coach sprites go here

4 * 4    01 00 02 04

[...]    // 4 sprites for 1st class coach

[...]    // 4 sprites for 2nd class coach

// c-IDs 0..1 use above set of sprites

13 * 9    02 00 00 01 01 00 00 00 00    // 1st class

14 * 9    02 00 01 01 01 01 00 01 00    // 2nd class

// next 4 pseudo sprites are checking var F2,

// thus constituting the two refitting possibilities:

// [1st class, 48 passengers, load amount = 6]  and

// [2nd class, 56 passengers, load amount = 8]

// set load amount

15 * 14    02 00 02 81 F2 00 FF 01

       06 80 00 00    // 1st class = 6/tick

       08 80        // 2nd class = 8/tick

// set refitted capacity

16 * 14    02 00 03 81 F2 00 FF 01

       30 80 00 00    // 1st class = 48 pass

       38 80        // 2nd class = 56 pass

// set text suffixes

17 * 18    02 00 04 81 F2 00 FF 02

       00 80 00 00    // "1st class"

       01 80 01 01    // "2nd class"

       FF 80

// set livery

18 * 14    02 00 05 81 F2 00 FF 01

       00 00 00 00    // 1st class

       01 00        // 2nd class

// switch between callbacks and graphics branch

19 * 22    02 00 06 85 0C 00 FF FF 03

       02 00 12 00 12 00    // is CB12, set load amount

       03 00 15 00 15 00    // is CB15, set refit capacity

       04 00 19 00 19 00    // is CB19, set text suffix

       05 00            // graphics

20 * 7    03 00 01 1B 00 06 00    // coach

~/pp~</pre>

-=Example3:  using callbacks 11 (wagon length) and 16 (articulated engine)=-

This example will demonstrate how to use [[Callbacks#Articulated_engine_callback_16_|callback 16]] for designing "articulated vehicles", e.g. locomotives with tenders. We'll set up two locomotives using two different tenders: <engine1> will use a standard short <tender1> and <engine2> will use the even shorter <tender2> by applying  [[Callbacks#Wagon_length_callback_11_|callback 11]].

<pre>~pp~

0 * 4    34 00 00 00

// add an action 08

1 * 8    08 02 xx xx xx xx 00 00

// set the generic tender (2D) to use new sprites,

// enable for callback 11

2 * 13    00 00 04 01 2D

       06 00    // don't show up in menu

       12 FD    // use new sprites

       1E 02    // enable CB 11

       21 02    // make shorter by 25%

// tender sprites go here

3 * 4    01 00 02 08

[...]    // 8 sprites for tender1

[...]    // 8 sprites for tender2

// Cargo-ids 0..1 use above set of sprites

20 * 9    02 00 F0 01 01 00 00 00 00    // tender1 (F0)

21 * 9    02 00 00 01 01 01 00 01 00    // tender2

// tender2 (F1) is shorter

22 * 18    02 00 F1 85 0C 00 FF FF 01

       03 80 11 00 11 00    // is CB11: make shorter by 37.5%

       00 00            // graphics

23 * 7    03 00 01 2D 00 F0 00    // standard tender

// set two engines (00 and 01) to use new sprites,

// enable for callback 16

24 * 11    00 00 02 02 00

       12 FD FD    // use new sprites

       1E 10 10    // enable CB 16

// engine sprites go here

25 * 4    01 00 02 08

[...]    // 8 sprites for engine1

[...]    // 8 sprites for engine2

// Cargo-ids 0..1 use above set of sprites

42 * 9    02 00 00 01 01 00 00 00 00    // engine1

43 * 9    02 00 01 01 01 01 00 01 00    // engine2

// <engine1> uses standard <tender1>

// engine is articulated, so show either engine (00) or tender (F0)

44 * 14    02 00 02 81 41 00 01 01

       00 00 00 00    // engine1

       F0 00        // tender1

// set articulated CB

45 * 14    02 00 03 81 10 00 FF 01

       2D 80 01 01    // add tender (2D)

       FF 80        // end of articulated vehicle

// Switch between callback and graphics branch

46 * 14    02 00 04 85 0C 00 FF FF 01

       03 00 16 00 16 00    // is CB16, handle it

       02 00            // graphics

47 * 7    03 00 01 00 00 04 00    // engine1 with tender1

// <engine2> uses shorter <tender2>

// engine is articulated, so show either engine (01) or tender (F1)

48 * 14    02 00 02 81 41 00 01 01

       01 00 00 00    // engine2

       F1 00        // tender2

// switch between callback and graphics branch

49 * 14    02 00 04 85 0C 00 FF FF 01

       03 00 16 00 16 00    // is CB 16, handle it

                       // (same as for <engine1>)

       02 00            // graphics

50 * 7    03 00 01 01 00 04 00    // engine2

51 * 7  03 00 81 2D 00 F1 00    // override with tender2

~/pp~</pre>

-=Example4: using Callbacks 10, 16, 1D and 23=-

This example explains how to use [[Callbacks#Articulated_engine_callback_10_|callbacks 10 (power]]), [[Callbacks#Articulated_engine_callback_16_|16 (articulated]]),

[[Callbacks#Articulated_engine_callback_1D_|1D (engine attach]]), and [[Callbacks#Articulated_engine_callback_23_|23 (additional text in menu]]) to construct a four-part EMU.

The EMU is composed from the same building block, an electric rail car (veh-ID = 62). In addition, it should be allowed to link three of these four-part EMUs, i.e. a full consist may contain 12 rail cars in total.

For sake of realism, no "foreign" vehicles should be allowed to be attached to the EMU. This is achieved by checking the veh-ID from [[VarAction2Vehicles|variable C6]]. Appropriate error messages will be generated if there's something wrong, either with number or with type of added vehicles.

Please notice that CBs 1D and 23 do not need a bit set in action0's property 1E.

Furthermore, it is shown how to make an explicit menu entry for such an EMU. For this to work, we need an extra sprite depicting not the single rail car but the complete four-part EMU. Because this sprite will be used only inside the buying menu, the corresponding sprite block needs only this single sprite for the horizontal direction. All other directions are not needed and hence we don't have to include sprites for them.

Also, the variable action2 chain for the menu entry need references for callbacks 16 and 23. The latter is used to place the text of additional information into the menu entry, and CB 16 is needed to get the capacity of the four-part EMU to show up correctly in the buying menu.

<pre>~pp~

0 * 4    39 00 00 00

// add an action 08

1 * 8    08 02 xx xx xx xx 00 00

// CB 1D error messages

2 * 0    04 00 81 02 20 D0

       " (wrong number of cars)" 00    // D020

       " (wrong type of car)" 00    // D021

// CB 23 additional text for menu

3 * 0    04 00 81 01 22 D0

       0d 91 "4-part EMU for commuter service."

               " (Links max 12 parts)" 00

// set rail car (62) to use new sprites,

// enable for callbacks 10 and 16

4 * 11    00 00 03 01 62

       12 FD    // use new sprites

       19 30    // electric traction

       1E 11    // enable CBs 10 and 16

//----------------------------------------------------------

// the "train"

//----------------------------------------------------------

// all rail car sprites go here

5 * 4    01 00 04 08

[...]    // sprites for 1st car

[...]    // sprites for 2nd car

[...]    // sprites for 3rd car

[...]    // sprites for 4th car

// c-IDs 0..3 use above set of sprites

38 * 9    02 00 00 01 01 00 00 00 00    // 1st car

39 * 9    02 00 01 01 01 01 00 01 00    // 2nd car

40 * 9    02 00 02 01 01 02 00 02 00    // 3rd car

41 * 9    02 00 03 01 01 03 00 03 00    // 4th car

// determine which car we are at. AND-ing the number of vehicles

// in consist is more efficient as a "modulo-4" operation would be.

42 * 22    02 00 04 81 40 00 03 03

       03 00 03 03    // 4th car

       02 00 02 02    // 3rd car

       01 00 01 01    // 2nd car

       00 00        // 1st car

// set CB 16 (articulated vehicle)

43 * 14    02 00 05 81 10 00 FF 01

       62 80 01 03    // 3 additional parts of veh-ID 62

       FF 80        // end articulated vehicle

// set CB 1D (engine attach)

// allow only 3 * EMU (= 12 cars) in total

44 * 14    02 00 06 82 40 10 FF 01

       FE 80 00 09    // allow adding of max 8 cars

       20 80        // error: "wrong number of cars"

// allow only EMU to attach itself, nothing else

45 * 14    02 00 07 81 C6 00 FF 01

       06 00 62 62    // allow

       21 80        // error: "wrong type of car"

// only car1 and, if exist, 5 and 9 should be sparking

// we're using a modulo-4 operation -> 80-FF-00-04

46 * 16      02 00 08 81 40 80 FF 00 04 01

       33 80 01 01    // sparks

       40 80        // no sparks

// switch between callback and graphics branch

47 * 22    02 00 09 85 0C 00 FF FF 03

       05 00 16 00 16 00    // is CB16, handle it

       07 00 1D 00 1D 00    // is CB 1D, handle it

       08 00 10 00 10 00    // is CB 10, handle it

       04 00            // graphics

//----------------------------------------------------------

// menu entry

//----------------------------------------------------------

48 * 4    01 00 01 04

49 * 1    00

50 * 1    00

51 C:\ttdlx\newgrf\sprites\emu.pcx 226 120 01 15 91 -27 -11

52 * 1    00

53 * 9    02 00 00 01 01 00 00 00 00

// switch between callback and graphics branch

54 * 18    02 00 01 85 0C 00 FF FF 02

       05 00 16 00 16 00    // CB 16 (for capacity calculation)

       22 80 23 00 23 00    // CB 23, show additional text

       00 00            // graphics

55 * 10    03 00 01 62 01 FF 01 00 09 00

~/pp~</pre>