TTWiki - User contributions [en-gb]

NMLTutorial/Train recolour

2011-09-04T14:33:01Z

Hirundo: /* Total code so far */ Again icm->item_icm

{{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 so far ==
When put in the correct order, this should now encode as a working NewGRF. The total code so far:

<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 0xFF;
}

/* --- 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 0xFF;
}

/* --- 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 0xFF;
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 SHORTEN_TO_7_8;
2: return SHORTEN_TO_1_8;
return SHORTEN_TO_8_8;
}

switch(FEAT_TRAINS, SELF, sw_icm_shorten_vehicle, cargo_subtype) {
0: sw_icm_shorten_3_part_vehicle;
return SHORTEN_TO_8_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 cargoes need explicit enabling/disabling:
refittable_cargo_types: bitmask();
// 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);
shorten_vehicle: 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

2011-09-04T14:31:06Z

Hirundo: Some more icm->item_icm fixes

{{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's no way to charge the user for puchasing the extra vehicle part. Also autoreplacing will be difficult, as there's now 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>0xFF</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 0xFF;
}
</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 0xFF;
}
</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 0xFF;
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>shorten_vehicle</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">
shorten_vehicle: 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 SHORTEN_TO_7_8;
2: return SHORTEN_TO_1_8;
return SHORTEN_TO_8_8;
}

switch(FEAT_TRAINS, SELF, sw_icm_shorten_vehicle, cargo_subtype) {
0: sw_icm_shorten_3_part_vehicle;
return SHORTEN_TO_8_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 0xFF;
}

/* --- 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 0xFF;
}

/* --- 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 0xFF;
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 SHORTEN_TO_7_8;
2: return SHORTEN_TO_1_8;
return SHORTEN_TO_8_8;
}

switch(FEAT_TRAINS, SELF, sw_icm_shorten_vehicle, cargo_subtype) {
0: sw_icm_shorten_3_part_vehicle;
return SHORTEN_TO_8_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 cargoes need explicit enabling/disabling:
refittable_cargo_types: bitmask();
// 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;
/* Only the front vehicle has a visual effect */
shorten_vehicle: 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}}

NMLTutorial/Train three part articulated

2011-09-04T14:27:37Z

Hirundo: Fix callbacks (icm->item_icm) and final comment

NMLTutorial/Train four part refit

2011-09-04T14:13:58Z

Hirundo: /* Total code so far */ Some fixes to the code; needs more review.

{{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's no way to charge the user for puchasing the extra vehicle part. Also autoreplacing will be difficult, as there's now 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>0xFF</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 0xFF;
}
</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 icm;
return 0xFF;
}
</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 0xFF;
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>shorten_vehicle</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">
shorten_vehicle: 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 SHORTEN_TO_7_8;
2: return SHORTEN_TO_1_8;
return SHORTEN_TO_8_8;
}

switch(FEAT_TRAINS, SELF, sw_icm_shorten_vehicle, cargo_subtype) {
0: sw_icm_shorten_3_part_vehicle;
return SHORTEN_TO_8_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 0xFF;
}

/* --- 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 0xFF;
}

/* --- 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 0xFF;
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 */
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 SHORTEN_TO_7_8;
2: return SHORTEN_TO_1_8;
return SHORTEN_TO_8_8;
}

switch(FEAT_TRAINS, SELF, sw_icm_shorten_vehicle, cargo_subtype) {
0: sw_icm_shorten_3_part_vehicle;
return SHORTEN_TO_8_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 cargoes need explicit enabling/disabling:
refittable_cargo_types: bitmask();
// 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;
/* Only the front vehicle has a visual effect */
shorten_vehicle: 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}}

NMLTutorial/Train

2011-08-30T20:28:50Z

Hirundo: spelling

NMLTutorial/Installation

2011-08-25T14:42:33Z

Hirundo: Some minor spelling fixes

{{NMLTutorial}}

NML is written in Python and therefore can be made to run on every operating system that can run Python. This includes the popular operating sytems Linux, MacOS and Windows. Below you'll find a description on how to install NML and how to use the command-line NML program on your operating system (MacOS description currently missing, as I don't have that, but please add it).

{{Note|The NML Documentation reflects the latest state of the NML program. Make sure to update your NML regularly, especially if you find something not working that should work according to the documentation.}}

== Linux ==
NML requires Python, the Python Image Library and PLY (Python Lex-Yacc). These three things are best installed from your package manager. If you're looking to compiling NML yourself, you also need the Python Setuptools. Note that NML currently only runs on Python 2.5 through 2.7, but not 3.x. Look for the following in your package manager:
* python (you might already have this)
* python-imaging (pil)
* python-ply
* python-setuptools

=== Installing NML as precompiled binary (recommended) ===
The latest version of NML is available as RPM package from the #openttdcoop DevZone. You can find it here: http://bundles.openttdcoop.org/nml/nightlies/LATEST/rpms/. This package is known to work on openSUSE and Red Hat (including Fedora and CentOS) distributions.

You can use the terminal to install this package through your package manager (make sure to run it as superuser). For example on Fedora:

sudo bash
yum install <nowiki>http://bundles.openttdcoop.org/nml/nightlies/LATEST/rpms/nml-rXXXX-suseYYYY.noarch.rpm</nowiki>

Make sure to replace XXXX and YYYY in the url with the actual version numbers you found via the link above. Enter "y" when asked and when done don't forget to <code>exit</code> sudo again, preventing yourself from doing stupid things from this point.

=== Compiling NML yourself ===
The other option to get NML is to compile it yourself. First you need to get the source from http://bundles.openttdcoop.org/nml/nightlies/LATEST/ or via Mercurial checkout from http://hg.openttdcoop.org/nml (<code>hg clone <nowiki>http://hg.openttdcoop.org/nml</nowiki></code>).

Also this time you need the terminal as superuser. Then change directory to the (extracted) NML source and run <code>python setup.py install</code>. For example:

sudo bash
cd ~/Downloads/nml-rXXXX
python setup.py install
exit

=== Using NML ===
As said before, NML is a command-line program and therefore doesn't have a GUI; much like GRFCodec in fact. That means you need to run it from a terminal window. The NML program itself is called <code>nmlc</code> and the general usage is <code>nmlc [options] <filename></code>. First change directory to the directory which has your nml file. Then run the nmlc program to compile your grf. For example:

cd ~/grfs/mygrf
nmlc -c --grf mygrf.grf mygrf.nml

This will encode the nml file ~/grfs/mygrf/mygrf.nml into the grf file ~/grfs/mygrf/mygrf.grf. The -c option is not mandatory, but crops extraneous blue from sprites, reducing the filesize of the grf file.

All command-line options available to NML are available via the <code>nmlc -h</code> command and are also [[#NML Command-line Options|listed]] on this page. Now that you have NML and know how to use it, you can continue this tutorial to learn how to create an actual grf file using NML.

== Windows ==
NML is available as pre-built (32 bit) Windows executable from the #openttdcoop DevZone, so there is no need to compile it yourself.

=== Installing NML ===
Go to http://bundles.openttdcoop.org/nml/nightlies/LATEST/ and download nml-rXXXX-windows-win32.zip, replacing XXXX with the actual version number of the package. The zip file contains a number of files that all need to stay together, so extract the zip file entirely into a single folder, for example D:\grfs\nml.

If you leave it at this, you can already start to use NML, but only from that folder. This makes compiling grfs a bit more difficult as you have to write full paths when encoding a grf file. If you want to run NML from any directory, you need to add the directory containing the nmlc.exe executable to your PATH environment variable. As this can break Windows if you don't do this properly, we'll not be explaining this here and go for the long route instead. You're of course free to change your PATH yourself; if you do, you're probably also smart enough to know how to change the commands as explained in the section below.

=== Using NML ===
As said before, NML is a command-line program and therefore doesn't have a GUI; much like GRFCodec in fact. That means you need to run it from a command prompt window. You can start the command prompt from Start > Programs > Accessories > Command Prompt. Or by entering <code>cmd</code> into the Run dialog or the Start menu search bar.

Next, you need to change directory to the folder where you have nmlc.exe in. Then you can run NML from there. For the example below we'll be assuming the following:
* nmlc.exe and related files are in D:\grfs\nml
* The nml file you want to encode is D:\grfs\mygrf\mygrf.nml
* The grf file to be created needs to go into D:\grfs\mygrf\mygrf.grf

From the command prompt you can now run the following commands, one at a time, confirm with Enter after each line:

D:
cd D:\grfs\nml
nmlc -c --grf D:\grfs\mygrf\mygrf.grf D:\grfs\mygrf\mygrf.nml

This will encode the nml file D:\grfs\mygrf\mygrf.nml into the grf file D:\grfs\mygrf\mygrf.grf. The -c option is not mandatory, but crops extraneous blue from sprites, reducing the filesize of the grf file. Note that if you have any spaces in a folder or file name, you need to enclose the complete path in double quotes, e.g.: <code>nmlc -c --grf "D:\grfs\my grf\mygrf.grf" "D:\grfs\mgrf\mygrf.nml"</code>. It is therefore recommended not to have any spaces.

All command-line options available to NML are available via the <code>nmlc -h</code> command and are also [[#NML Command-line Options|listed]] on this page. Now that you have NML and know how to use it, you can continue this tutorial to learn how to create an actual grf file using NML.

== NML Command-line Options ==
''From the NML readme''

Usage: nmlc [options] <filename>
Where <filename> is the nml file to parse

Options:
--version show program's version number and exit
-h, --help show this help message and exit
-d, --debug write the AST to stdout
-s, --stack Dump stack when an error occurs
--grf=<file> write the resulting grf to <file>
--nfo=<file> write nfo output to <file>
-c crop extraneous transparent blue from real sprites
-u save uncompressed data in the grf file
--nml=<file> write optimized nml to <file>
-o <file>, --output=<file>
write output(nfo/grf) to <file>
-t <file>, --custom-tags=<file>
Load custom tags from <file> [default:
custom_tags.txt]
-l <dir>, --lang-dir=<dir>
Load language files from directory <dir> [default:
lang]
-a <dir>, --sprites-dir=<dir>
Store 32bpp sprites in directory <dir> [default:
sprites]
--default-lang=<file>
The default language is stored in <file> [default:
english.lng]
--start-sprite=<num> Set the first sprite number to write (do not use
except when you output nfo that you want to include in
other files)
-p <palette>, --palette=<palette>
Force nml to use the palette <pal> [default: ANY].
Valid values are 'DOS', 'WIN', 'ANY'

== Text editor ==
NML files and its language files are plain text files and should be edited in a plain text editor. Your operating system most likely comes with a text editor with limited functionality. As such it is recommended to choose an editor with more functionality:
; Cross-platform
* [http://www.geany.org/ Geany]
; Linux
*
; MacOS
*
; Windows
* [http://notepad-plus-plus.org/ Notepad++]

If you use an editor which you think is quite good and not listed here, you're welcome to add it.

=== Syntax highlighting ===
Syntax highlighting adds some colour to NML code, which makes it easier to read.

At the #openttdcoop DevZone there are syntax highlighter extensions available for [http://dev.openttdcoop.org/documents/24 Notepad++] and [http://dev.openttdcoop.org/documents/26 Geany]. If you want to create your own syntax highlighter, there's a [http://dev.openttdcoop.org/documents/25 script] available as well that will help you create the keyword lists.

{{NMLTutorialNavbar||Graphic files}}