TTWiki - User contributions [en-gb]

NMLTutorial/Train four part refit

2012-09-15T19:35:12Z

Supercheese: /* What's going to happen */ There is a way to charge for refits, but it has some issues

{{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_MORE_ARTICULATED_PARTS</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_MORE_ARTICULATED_PARTS;
}
</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}}

NMLTutorial/Train four part refit

2012-09-10T01:37:11Z

Supercheese: /* What's going to happen */ Fixing typo

{{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 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_MORE_ARTICULATED_PARTS</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_MORE_ARTICULATED_PARTS;
}
</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}}

NMLTutorial/Road vehicle 32 bit sprites

2012-06-26T18:19:57Z

Supercheese: /* Spritesets */ Add missing slash in </code> tag

{{NMLTutorial}}

Now that you've seen that you can add 32 bit sprites, let's do that with an example. In fact we're going to pick up halfway down the road vehicle example from the beginning of this tutorial. We'll continue with what we had at the end of [[NMLTutorial/Road vehicle graphics|this page]].

== Example graphics ==
We'll be adding 32 bit graphics for the normal zoom level, including a recolour mask. From there we'll give you some pointers on how to add sprites for other zoom levels and you can easily fill in the rest yourself. So let's look at the graphics, shall we?

First, let's have a look again at the 8 bit sprites we already have for our road vehicle.
[[Image:Flatbed truck 1 goods.png|frame|none|Empty flatbed truck sprites and flatbed trucks sprites loaded with a container]]

The 32 bit sprites are similar to the 8 bit sprites. The main difference is that to indicate transparancy you must use the real transparency of PNG files. If you use the blue background for transparency in 32 bit sprites, you'll get just that: a blue background. You may also use the alpha channel for semi-transparent pixels.
[[Image:Flatbed truck 1 goods 32.png|frame|none|Empty flatbed truck sprites and flatbed trucks sprites loaded with a container in 32 bit.]]
Note that the sprite background is actually transparent. We've made the borders around the sprites blue, so that we can actually see where the indivual sprites are. This is not mandatory; as it doesn't end up in the game, you could have made it any other colour, even transparent if you like. We'll put this file in the ''gfx'' folder with the regular 8 bit sprites and name it ''flatbed_truck_1_goods_32.png‎''.

Now even if you use the exact colours from the palette, this won't enable company colours in 32 bit sprites. For this you have to provide an additional 8 bit mask sprite, which does use the exact palette colours. Ingame, this mask is overlayed on top of the regular 32 bit sprites, which will give you a company-coloured vehicle. Note that the mask sprites need to be in exactly the same position as the regular 32 bit sprites, as they will use the same offsets!
[[Image:Flatbed_truck_1_goods_mask.png|frame|none|The mask file to go with the previous 32 bit graphics]]
As we're now drawing in 8 bit again, we also have to use the magic blue to incidate transparent backgrounds! Also this file goes in the ''gfx'' directory and we'll name it ''flatbed_truck_1_goods_mask.png''.

== Spritesets ==
For the regular 8 bit sprites we have two spritesets in our NML code. Let's have a look at those again:

<pre style="color:darkblue; white-space: pre-wrap">
//graphics definition
spriteset(spriteset_flatbed_truck_1_goods_empty, "gfx/flatbed_truck_1_goods.png") {
//left_x, upper_y, width, height, offset_x, offset_y
[ 0, 0, 8, 18, -3, -10]
[ 16, 0, 20, 16, -14, -7]
[ 48, 0, 28, 12, -14, -6]
[ 96, 0, 20, 16, -6, -7]
[ 128, 0, 8, 18, -3, -10]
[ 144, 0, 20, 16, -14, -7]
[ 176, 0, 28, 12, -14, -6]
[ 224, 0, 20, 16, -6, -7]
}

spriteset(spriteset_flatbed_truck_1_goods_full, "gfx/flatbed_truck_1_goods.png") {
//left_x, upper_y, width, height, offset_x, offset_y
[ 260, 0, 8, 18, -3, -10]
[ 276, 0, 20, 16, -14, -7]
[ 308, 0, 28, 12, -14, -6]
[ 356, 0, 20, 16, -6, -7]
[ 388, 0, 8, 18, -3, -10]
[ 404, 0, 20, 16, -14, -7]
[ 436, 0, 28, 12, -14, -6]
[ 484, 0, 20, 16, -6, -7]
}
</pre>

To define our 32 bit sprites, we have to define an <code>alternative_sprites</code> block to go with each of the spriteset blocks. The identifiers will be the same, we'll indicate that we have normal zoom sprites via <code>ZOOM_LEVEL_NORMAL</code> and that the sprites are 32 bit via <code>BIT_DEPTH_32BPP</code>.

We'll also reference the new graphics files. As the 32 bit sprites and the mask sprites belong together, they go together in in the same <code>alternative_sprites</code> block. Let's look at the first line of that block:

<pre style="color:darkblue; white-space: pre-wrap">
alternative_sprites(spriteset_flatbed_truck_1_goods_empty, ZOOM_LEVEL_NORMAL, BIT_DEPTH_32BPP, "flatbed_truck_1_goods_32.png", "flatbed_truck_1_goods_mask.png") {
</pre>

The positions, sizes and offsets of 32 bit sprites are incidentally the same as for the 8 bit sprites. Coincidence? Of course not, this will just save us a lot of trouble, as now we can simply copy these from the 8 bit sprites. This will give us the following <code>alternative_sprites</code> block for the first set of sprites:
<pre style="color:darkblue; white-space: pre-wrap">
alternative_sprites(spriteset_flatbed_truck_1_goods_empty, ZOOM_LEVEL_NORMAL, BIT_DEPTH_32BPP, "flatbed_truck_1_goods_32.png", "flatbed_truck_1_goods_mask.png") {
//left_x, upper_y, width, height, offset_x, offset_y
[ 0, 0, 8, 18, -3, -10]
[ 16, 0, 20, 16, -14, -7]
[ 48, 0, 28, 12, -14, -6]
[ 96, 0, 20, 16, -6, -7]
[ 128, 0, 8, 18, -3, -10]
[ 144, 0, 20, 16, -14, -7]
[ 176, 0, 28, 12, -14, -6]
[ 224, 0, 20, 16, -6, -7]
}
</pre>

It is good practice to place the <code>alternative_sprites</code> block right after the <code>spriteset</code> block it belongs to. Let's do that and at the same time fill in the other <code>alternative_sprites</code> block.

<pre style="color:darkblue; white-space: pre-wrap">
//graphics definition
spriteset(spriteset_flatbed_truck_1_goods_empty, "gfx/flatbed_truck_1_goods.png") {
//left_x, upper_y, width, height, offset_x, offset_y
[ 0, 0, 8, 18, -3, -10]
[ 16, 0, 20, 16, -14, -7]
[ 48, 0, 28, 12, -14, -6]
[ 96, 0, 20, 16, -6, -7]
[ 128, 0, 8, 18, -3, -10]
[ 144, 0, 20, 16, -14, -7]
[ 176, 0, 28, 12, -14, -6]
[ 224, 0, 20, 16, -6, -7]
}
alternative_sprites(spriteset_flatbed_truck_1_goods_empty, ZOOM_LEVEL_NORMAL, BIT_DEPTH_32BPP, "flatbed_truck_1_goods_32.png", "flatbed_truck_1_goods_mask.png") {
//left_x, upper_y, width, height, offset_x, offset_y
[ 0, 0, 8, 18, -3, -10]
[ 16, 0, 20, 16, -14, -7]
[ 48, 0, 28, 12, -14, -6]
[ 96, 0, 20, 16, -6, -7]
[ 128, 0, 8, 18, -3, -10]
[ 144, 0, 20, 16, -14, -7]
[ 176, 0, 28, 12, -14, -6]
[ 224, 0, 20, 16, -6, -7]
}

spriteset(spriteset_flatbed_truck_1_goods_full, "gfx/flatbed_truck_1_goods.png") {
//left_x, upper_y, width, height, offset_x, offset_y
[ 260, 0, 8, 18, -3, -10]
[ 276, 0, 20, 16, -14, -7]
[ 308, 0, 28, 12, -14, -6]
[ 356, 0, 20, 16, -6, -7]
[ 388, 0, 8, 18, -3, -10]
[ 404, 0, 20, 16, -14, -7]
[ 436, 0, 28, 12, -14, -6]
[ 484, 0, 20, 16, -6, -7]
}
alternative_sprites(spriteset_flatbed_truck_1_goods_full, ZOOM_LEVEL_NORMAL, BIT_DEPTH_32BPP, "flatbed_truck_1_goods_32.png", "flatbed_truck_1_goods_mask.png") {
//left_x, upper_y, width, height, offset_x, offset_y
[ 260, 0, 8, 18, -3, -10]
[ 276, 0, 20, 16, -14, -7]
[ 308, 0, 28, 12, -14, -6]
[ 356, 0, 20, 16, -6, -7]
[ 388, 0, 8, 18, -3, -10]
[ 404, 0, 20, 16, -14, -7]
[ 436, 0, 28, 12, -14, -6]
[ 484, 0, 20, 16, -6, -7]
}
</pre>

And that's really all there is to defining 32 bit sprites!

== Templates ==
Can we also template 32 bit graphics, I hear you ask? Well certainly, they're no different than 8 bit sprites in that respect. Let's go back to where we've [[NMLTutorial/Road_vehicle_graphics_template|templated our example road vehicle]]. Because we were smart enough to keep the same positions, sizes and offsets for both our 8 bit and 32 bit sprites, we can simply use the same template we made earlier. This template was called <code>tmpl_truck</code> and has template parameters for the top left position of the first of eight sprites.

When first using this template, we simply replaced all the numbers inside the spriteset blocks with a call to the template, and ended up with this:
<pre style="color:darkblue; white-space: pre-wrap">
//graphics definition
spriteset(spriteset_flatbed_truck_1_goods_empty, "gfx/flatbed_truck_1_goods.png") {
tmpl_truck(0, 0)
}

spriteset(spriteset_flatbed_truck_1_goods_full, "gfx/flatbed_truck_1_goods.png") {
tmpl_truck(260, 0)
}
</pre>

For our <code>alternative_sprites</code> blocks we can do the same, there's really nothing to it:
<pre style="color:darkblue; white-space: pre-wrap">
//graphics definition
spriteset(spriteset_flatbed_truck_1_goods_empty, "gfx/flatbed_truck_1_goods.png") {
tmpl_truck(0, 0)
}
alternative_sprites(spriteset_flatbed_truck_1_goods_empty, ZOOM_LEVEL_NORMAL, BIT_DEPTH_32BPP, "flatbed_truck_1_goods_32.png", "flatbed_truck_1_goods_mask.png") {
tmpl_truck(0, 0)
}

spriteset(spriteset_flatbed_truck_1_goods_full, "gfx/flatbed_truck_1_goods.png") {
tmpl_truck(260, 0)
}
alternative_sprites(spriteset_flatbed_truck_1_goods_full, ZOOM_LEVEL_NORMAL, BIT_DEPTH_32BPP, "flatbed_truck_1_goods_32.png", "flatbed_truck_1_goods_mask.png") {
tmpl_truck(260, 0)
}
</pre>

So the first line of the blocks remains the same, we just replace the content with the template call.

== Other zoom levels ==
For each additional zoom level, you simply add additional <code>alternative_sprites</code> blocks. Because of the different sprite sizes and offsets, you do have to create an additional template for each additional zoom level. If you order the sprites in a standardized way in your png files, you can keep reusing templates as we've done before.

Let's assume we have 32 bit graphics for the 4x zoom in level. The <code>alternative_sprites</code> for these sprites will be similar, but you specify the different zoom level (in this case) via <code>ZOOM_LEVEL_IN_4X</code> and reference the template you have made for sprites of this zoom level. For the first set of sprites you then get this additional <code>alternative_sprites</code> block:
<pre style="color:darkblue; white-space: pre-wrap">
alternative_sprites(spriteset_flatbed_truck_1_goods_empty, ZOOM_LEVEL_IN_4X, BIT_DEPTH_32BPP, "flatbed_truck_1_goods_32.png", "flatbed_truck_1_goods_mask.png") {
tmpl_truck_zi4(0, 0)
}
</pre>

And the total set of blocks:
<pre style="color:darkblue; white-space: pre-wrap">
//graphics definition
spriteset(spriteset_flatbed_truck_1_goods_empty, "gfx/flatbed_truck_1_goods.png") {
tmpl_truck(0, 0)
}
alternative_sprites(spriteset_flatbed_truck_1_goods_empty, ZOOM_LEVEL_NORMAL, BIT_DEPTH_32BPP, "flatbed_truck_1_goods_32.png", "flatbed_truck_1_goods_mask.png") {
tmpl_truck(0, 0)
}
alternative_sprites(spriteset_flatbed_truck_1_goods_empty, ZOOM_LEVEL_IN_4X, BIT_DEPTH_32BPP, "flatbed_truck_1_goods_32.png", "flatbed_truck_1_goods_mask.png") {
tmpl_truck_zi4(0, 0)
}

spriteset(spriteset_flatbed_truck_1_goods_full, "gfx/flatbed_truck_1_goods.png") {
tmpl_truck(260, 0)
}
alternative_sprites(spriteset_flatbed_truck_1_goods_full, ZOOM_LEVEL_NORMAL, BIT_DEPTH_32BPP, "flatbed_truck_1_goods_32.png", "flatbed_truck_1_goods_mask.png") {
tmpl_truck(260, 0)
}
alternative_sprites(spriteset_flatbed_truck_1_goods_full, ZOOM_LEVEL_IN_4X, BIT_DEPTH_32BPP, "flatbed_truck_1_goods_32.png", "flatbed_truck_1_goods_mask.png") {
tmpl_truck_zi4(260, 0)
}
</pre>

And with that we end this example of adding 32 bit sprites to your road vehicle NewGRF. Of course, the same method as used here also applies to providing 32 bit alternatives for any other <code>spriteset</code> you may have. Only thing left for you to skip is a useless conclusion :)

{{NMLTutorialNavbar|32 bit sprites|Conclusion}}

User:FooBar/Generic NewGRF Readme

2012-01-22T22:17:14Z

Supercheese: Fixing numbering issues; hope you don't mind!

This is an attempt at a generic layout for NewGRF readmes. It provides you with a layout to use, has several sections pre-filled and suggestions on what to put in the other. It is aimed to serve as:
* a template that you can modify for your own NewGRF;
* an optimized order of sections for used with the OpenTTD readme viewer (i.e. gameplay related stuff first);
* a checklist to see if you have all important bits covered in your readme;
* inspiration in case you want to write your own readme.

Feel free to use this as basis for the readme of your NewGRF. The only thing I ask is that your NewGRF is released under the GNU General Public Licence 2.0 or 3.0 or higher (your choice which one/combination exactly). This example itself is licensed GNU GPL v2+.

What you have to do yourself is of course fill in the missing pieces. Don't forget to set the correct game version requirements and update the urls in the contact information section. Many predefined bits are aimed at hosting your NewGRF at the [http://dev.openttdcoop.org/ #openttdcoop DevZone], but you can just modify that if you're not hosting your grf there.

==Readme.txt==
<pre>
{{GRF_TITLE}}
===================================
<one-line description of what the grf does>

----------
0 Contents
----------

1 About
2 General information
2.1 Requirements
2.2 Installation
2.3 Parameter settings
2.4 Usage
3 Known issues
4 Background information
5 Frequently Asked Questions
6 Credits
7 Contact information
7.1 Bug reports
7.2 Other problems
7.3 General enquiries
8 License
9 Obtaining the source

-------
1 About
-------

<one or two paragraphs what this grf is about, what it contains and what it does>

{{GRF_TITLE}}
MD5Hash: {{GRF_MD5}}
Version: {{REPO_REVISION}}
GRF ID: {{GRF_ID}}

---------------------
2 General information
---------------------

2.1 Requirements
----------------
- OpenTTD <1.2.0> or nightly r<22723>
- TTDPatch nightly r<2200>

2.2 Installation
----------------
OpenTTD:
see http://wiki.openttd.org/NewGRF
This NewGRF is available from the ingame Online Content

TTDPatch:
see http://www.tt-wiki.net/wiki/NewGraphicsInstallation

2.3 Parameter settings
----------------------
<some notes on what settings are available>

Set the parameters before starting a new game. Once started they
cannot be changed any longer.

Useful details if you need to set the parameters manually in the
configuration file:

1st parameter: <description>
0: <what this value does>
1: <what this value does>
2: <what this value does>

2nd parameter: <description>
0: <what this value does>
1: <what this value does>

2.4 Usage
---------
<some notes on how to use this NewGRF>

--------------
3 Known issues
--------------

<list of known issues in this release>

------------------------
4 Background information
------------------------

<in this section you can give some background information on the
contents of this NewGRF>

----------------------------
5 Frequently Asked Questions
----------------------------

Q: Why is it that...?
A: No reason.

---------
6 Credits
---------

Graphics:
- <artist 1>
- <artist 2>
- <artist 3>

Code:
- <coder 1>
- <coder 2>

Translations:
- <translator 1>
- <translator 2>

Makefile system:
- <usually planetmaker>

---------------------
7 Contact information
---------------------

7.1 Bug reports
---------------
Please report any bugs you find at
bug tracker: http://dev.openttdcoop.org/projects/<projectname>/issues
or forum topic: http://www.tt-forums.net/viewtopic.php?t=<00000>

Always included a detailed description of the bug, preferrably with
screenshot and savegame. Also state the exact game version you're using,
as well as the version of this NewGRF.

If you have a savegame that includes NewGRFs not available on OpenTTD's
Online Content, then please try to reproduce the bug in a new game
which has all NewGRFs easily accessible.

If you're using a patched version of the game, please try to reproduce
the bug on an official game build. If you can't reproduce the bug, then
don't report it here but in the forum topic of the patch(pack) instead.

7.2 Other problems
------------------
If you have any problems using this NewGRF that are not covered in the
Frequently Asked Questions above, then you can ask your questions in the
forum topic: http://www.tt-forums.net/viewtopic.php?t=<00000>

7.3 General enquiries
---------------------

If you have any queries that cannot be asked in the forum topic, then
contact <username> via Private Message at www.tt-forums.net or send
an email to <name> at <email address>.

---------
8 License
---------

<name of the NewGRF> - <short description>
Copyright (C) <year> <list of authors or team name>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

----------------------
9 Obtaining the source
----------------------

The source code can be obtained from the #openttdcoop DevZone
via source browser:
http://dev.openttdcoop.org/projects/<projectname>/repository
or via mercurial checkout:
hg clone http://hg.openttdcoop.org/<projectname>
or via a source bundle download (releases only):
http://bundles.openttdcoop.org/<projectname>/

How to build from source and the requirements for that are included
with the source in the file /docs/building_from_source.txt.
</pre>