TTWiki - User contributions [en-gb]

NMLTutorial/Train three part articulated

2011-12-13T22:33:04Z

Yexo: /* Start/stop callback */

NMLTutorial/Train four part refit

2011-12-13T22:32:42Z

Yexo:

{{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>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>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 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 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-12-13T22:30:44Z

Yexo:

NMLTutorial/Tram purchase menu

2011-12-13T22:28:02Z

Yexo: /* The complete code */

{{NMLTutorial}}
''The example used here is the HTM 4001 from the [http://dev.openttdcoop.org/projects/dutchtramset/repository Dutch Tram Set]. The original code and graphics for this are by FooBar. 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/Tram graphics|third part]] of the tram example. We'll look into some things dealing with the purchase menu.

== Purchase menu text ==
There is a callback that allows adding text to the purchase menu. In the Dutch Tram Set this is used to give you some information on how the vehicles were/are used in real life. For the tram in this example, we already defined such a text in the language files. Let's add it to the purchase menu.

The callback needed for this you must again [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_callbacks look up] in the NML Documentation and is named <code>additional_text</code>. And it's an easy one at that, because we can just return the string that must be displayed straight from the graphics block:

<pre style="color:darkblue; white-space: pre-wrap;">
graphics {
additional_text: return string(STR_DESC_HTM_4001); //Additional text shown in purchase list
articulated_part: switch_articulated_htm_4001;
shorten_vehicle: switch_length_htm_4001;
cargo_capacity: switch_capacity_htm_4001;
default: switch_spriteset_htm_4001;
}
</pre>

Callback done. Easy!

== Purchase menu sprite ==
You may remember a separate sprite and template for the purchase menu. In order to use this, you need a spriteset block and reference this from the graphics block. The spriteset is again pretty straightforward:

<pre style="color:darkblue; white-space: pre-wrap;">
spriteset(spriteset_purchase_htm_4001, "gfx/htm_4001.png") {
template_purchase(0, 140)
}
</pre>

Referencing that from the graphics block isn't too difficult either, as you've done that before:

<pre style="color:darkblue; white-space: pre-wrap;">
graphics {
purchase: spriteset_purchase_htm_4001; //Purchase menu sprite
additional_text: return string(STR_DESC_HTM_4001); //Additional text shown in purchase list
articulated_part: switch_articulated_htm_4001;
shorten_vehicle: switch_length_htm_4001;
cargo_capacity: switch_capacity_htm_4001;
default: switch_spriteset_htm_4001;
}
</pre>

The identifiers are of course the same in the graphics block and in the spriteset block. The spriteset block must be defined before the item block.

== Fixing the purchase menu capacity display ==
Using the cargo capacity callback comes with a side-effect: the capacity display in the purchase menu is broken. The reason for this is that the <code>position_in_consist</code> variable is [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_variables not available] in the purchase menu. As a result, the game can't calculate the capacity for each vehicle part in the purchase menu, you'll get some unknown behaviour and as a result an incorrect capacity in the purchase menu.

The solution to this is to tell the game not to use the capacity from the callback in the purchase menu, but instead to use the capacity from the capacity property (form the property block) in the purchase menu.

The way this solution works is to define a separate cargo capacity callback for the purchase menu, but instead of returning a capacity value linking this callback directly to the purchase menu spriteset. Sounds a bit of a trick solution, and it is. The result is that the cargo capacity callback for the purchase menu will fail and that the cargo capacity property is used instead. And above all it's not a hack, but completely legal NML code.

The callback name for the graphics block to do this is called <code>purchase_cargo_capacity</code> and can be found in the [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_callbacks usual place]. Your final graphics block will now look like this:

<pre style="color:darkblue; white-space: pre-wrap;">
graphics {
purchase: spriteset_purchase_htm_4001; //Purchase menu sprite
additional_text: return string(STR_DESC_HTM_4001); //Additional text shown in purchase list
articulated_part: switch_articulated_htm_4001;
shorten_vehicle: switch_length_htm_4001;
cargo_capacity: switch_capacity_htm_4001;
purchase_cargo_capacity: spriteset_purchase_htm_4001; //<-- linked to the purchase menu spriteset
default: switch_spriteset_htm_4001;
}
</pre>

The cargo capacity property will now be applied to each part of the vehicle for display in the purchase menu. In this case, three times the cargo capacity property will be displayed as total capacity in the purchase menu. And this completes the tram example.

== The complete code ==
The complete NML code for the tram vehicle:

<pre style="color:darkblue; white-space: pre-wrap; max-height: 200px; overflow:scroll">
// define the newgrf
grf {
grfid: "\FB\FB\01\02";
name: string(STR_GRF_NAME);
desc: string(STR_GRF_DESCRIPTION);
version: REPO_REVISION;
min_compatible_version: 87;
}

////////////////////////
//Purchase menu sprite//
////////////////////////

spriteset(spriteset_purchase_htm_4001, "gfx/htm_4001.png") {
template_purchase(0, 140)
}

///////////////////
//Vehicle sprites//
///////////////////

spriteset(spriteset_real_htm_4001, "gfx/htm_4001.png") {
template_tram_28(0, 20)
}
spriteset(spriteset_real_htm_4001_1, "gfx/htm_4001.png") {
template_tram_24(0, 60)
}
spriteset(spriteset_real_htm_4001_2, "gfx/htm_4001.png") {
template_tram_28(0, 100)
}

switch (FEAT_ROADVEHS, SELF, switch_spriteset_htm_4001, position_in_consist ) {
1: spriteset_real_htm_4001_1;
2: spriteset_real_htm_4001_2;
spriteset_real_htm_4001; //default
}

/////////////////////
//vehicle callbacks//
/////////////////////

//set number of articulated parts
switch (FEAT_ROADVEHS, SELF, switch_articulated_htm_4001, extra_callback_info1) {
1..2: return item_tram_htm_4001; //use same vehicle for all parts
return CB_RESULT_NO_MORE_ARTICULATED_PARTS; //stop adding vehicle parts
}

//set length of each part
switch (FEAT_ROADVEHS, SELF, switch_length_htm_4001, position_in_consist ) {
1: return 2;
return 1;
}

//set capacity of each part
switch (FEAT_ROADVEHS, SELF, switch_capacity_htm_4001, position_in_consist ) {
1: return 26;
return 38; //default
}

//////////////////////
//vehicle properties//
//////////////////////

item (FEAT_ROADVEHS, item_tram_htm_4001) {
property {
name: string(STR_NAME_HTM_4001);
introduction_date: date(2006,1,1);
model_life: VEHICLE_NEVER_EXPIRES;
retire_early: 0;
vehicle_life: 25;
loading_speed: 25;
cost_factor: 224;
running_cost_factor: 112;
speed: 81 km/h;
power: 966 hp;
weight: 58 ton;
cargo_capacity: (38*2+26)/3;
tractive_effort_coefficient: 0.5;
air_drag_coefficient: 0;
//sound_effect: no sound
//visual_effect: use default (none)

//callback_flags: no need to set this
reliability_decay: 20;
climates_available: ALL_CLIMATES;
refittable_cargo_classes: bitmask(CC_PASSENGERS);
sprite_id: SPRITE_ID_NEW_ROADVEH; //use custom sprites
misc_flags: bitmask(ROADVEH_FLAG_TRAM); //make this a tram
refit_cost: 0; //refits are free
running_cost_base: RUNNING_COST_ROADVEH;
}

graphics {
purchase: spriteset_purchase_htm_4001; //Purchase menu sprite
additional_text: return string(STR_DESC_HTM_4001); //Additional text shown in purchase list
articulated_part: switch_articulated_htm_4001;
shorten_vehicle: switch_length_htm_4001;
cargo_capacity: switch_capacity_htm_4001;
purchase_cargo_capacity: spriteset_purchase_htm_4001;
default: switch_spriteset_htm_4001;
}
}
</pre>

That concludes the articulated tram example. The next part of this tutorial will a train example with some fancy features.

{{NMLTutorialNavbar|Tram graphics|Train}}

NMLTutorial/Tram graphics

2011-12-13T22:27:41Z

Yexo: /* Total code so far */

{{NMLTutorial}}
''The example used here is the HTM 4001 from the [http://dev.openttdcoop.org/projects/dutchtramset/repository Dutch Tram Set]. The original code and graphics for this are by FooBar. 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/Tram articulation|second part]] of the tram example. Now graphics will be added to the tram.

== The graphics ==
As this tutorial is about coding NML and not about drawing graphics, we'll give you the graphics for free:

[[Image:Htm 4001.png|frame|none|Graphics for each part of the HTM 4001. Drawn by FooBar.]]

=== Templates ===
The graphics in this file are templated (and actually use the templates used as example for the template chapter of this tutorial). That means we'll be using templates here as well. Check [[NMLTutorial/Template|back]] if you don't remember how to do that. These are the templates you should end up with:

<pre style="color:darkblue; white-space: pre-wrap;">
template template_tram_28(x, y) {
//[left_x, upper_y, width, height, offset_x, offset_y]
[x, y, 10, 28, -4, -11]
[x+ 20, y, 26, 28, -17, -14]
[x+ 50, y, 36, 28, -20, -20]
[x+ 90, y, 26, 28, -9, -15]
[x+120, y, 10, 28, -4, -13]
[x+140, y, 26, 28, -16, -16]
[x+170, y, 36, 28, -16, -20]
[x+210, y, 26, 28, -8, -16]
}

template template_tram_24(x, y) {
//[left_x, upper_y, width, height, offset_x, offset_y]
[x, y, 10, 28, -4, -11]
[x+ 20, y, 26, 28, -17, -14]
[x+ 50, y, 36, 28, -22, -20]
[x+ 90, y, 26, 28, -9, -15]
[x+120, y, 10, 28, -4, -15]
[x+140, y, 26, 28, -16, -16]
[x+170, y, 36, 28, -14, -20]
[x+210, y, 26, 28, -8, -16]
}

template template_purchase(x, y) {
//[left_x, upper_y, width, height, offset_x, offset_y]
[x, y, 50, 12, -25, -6]
}
</pre>

The purchase menu sprite will be added on the next page, but it doesn't hurt to have the template defined now. Every template has arguments for the position of the top left sprite corner.

=== Spritesets ===
With these templates, we can make three spritesets for the three vehicle parts. We give the spritesets proper names and include a reference to the image file:

<pre style="color:darkblue; white-space: pre-wrap;">
spriteset(spriteset_real_htm_4001, "gfx/htm_4001.png") {
template_tram_28(0, 20)
}
spriteset(spriteset_real_htm_4001_1, "gfx/htm_4001.png") {
template_tram_24(0, 60)
}
spriteset(spriteset_real_htm_4001_2, "gfx/htm_4001.png") {
template_tram_28(0, 100)
}
</pre>

Notice that the first and last vehicle part are 28 px long and use the 28 px template. The middle part is only 24 px long and uses the 24 px template.

Because there are no different sprites for "empty", "full", "loaded" and "loading", we don't have to define a spritegroup in this case. If you had different sprites for these different states, you would need to combine them in a spritegroup first.

== Attaching the graphics with a switch block ==
From the graphics block we will use the ''default'' callback to reference the spritesets. However, because we can reference only one spriteset (or -group) from the graphics block, we need an intermediate switch block to decide the graphics depending on the position in the vehicle.

So from the graphics block we reference a switch block for the default graphics:

<pre style="color:darkblue; white-space: pre-wrap;">
graphics {
articulated_part: switch_articulated_htm_4001;
cargo_capacity: switch_capacity_htm_4001;
default: switch_spriteset_htm_4001;
}
</pre>

This then links to a switch block. The workings of this switch block will be similar to that of the cargo capacity callback, making a decicion based on the <code>position_in_consist</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_variables variable]. However, this time we need three separate ranges (because three different spritesets) and we mustn't return a value but now reference these spritesets:

<pre style="color:darkblue; white-space: pre-wrap;">
switch (FEAT_ROADVEHS, SELF, switch_spriteset_htm_4001, position_in_consist ) {
1: spriteset_real_htm_4001_1;
2: spriteset_real_htm_4001_2;
spriteset_real_htm_4001; //default
}
</pre>

So for the second vehicle part (with index 1 in <code>position_in_consist</code>) we use the graphics of the 'spriteset_real_htm_4001_1' spriteset block. For the last part (index 2) we use the ''spriteset_real_htm_4001_2'' spriteset. For all other parts (in this case only the first) we'll default to the ''spriteset_real_htm_4001'' spriteset.

This has the graphics sorted and you can encode the NewGRF to see the result ingame.

== Shorten vehicle callback ==
If you did encode the previous results, you'll notice that the individual vehicle parts are very far apart. This is because we used shorter sprites than the 32px default length. We'll need to tell the game that our vehicle parts are shorter!

This is done by means of the shorten vehicle callback, incidentally named <code>shorten_vehicle</code> for use in the graphics block, look it up [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_callbacks here]. Because different parts have different lengths, we once more can't just return a value from the graphics block but need an intermediate switch block:

<pre style="color:darkblue; white-space: pre-wrap;">
graphics {
articulated_part: switch_articulated_htm_4001;
shorten_vehicle: switch_length_htm_4001; //<-- this one is added now
cargo_capacity: switch_capacity_htm_4001;
default: switch_spriteset_htm_4001;
}
</pre>

The switch block itself will once more make a decision based on the <code>position_in_consist</code> variable. The value to return for the callback is how many times 12,5% (1/8) to reduce the vehicle length with. The first and last part of the vehicle are 28px, which is (1/8) shorter than 32px, so the return value here is 1. The middle part is 24px, which is (2/8) shorter so the return value for this part is 2. The switch block:

<pre style="color:darkblue; white-space: pre-wrap;">
switch (FEAT_ROADVEHS, SELF, switch_length_htm_4001, position_in_consist ) {
1: return 2;
return 1;
}
</pre>

The second vehicle part (with index 1 in <code>position_in_consist</code>) returns value 2 and value 1 is returned for all other positions (the first and last part of the vehicle). Once more notice that the identifier of the switch block is the same as that used in the graphics block.

This should fix our vehicle and now the parts actually appear connected.

== Total code so far ==
If you put everything in the correct order, you should have this:

<pre style="color:darkblue; white-space: pre-wrap; max-height: 200px; overflow:scroll">
// define the newgrf
grf {
grfid: "\FB\FB\01\02";
name: string(STR_GRF_NAME);
desc: string(STR_GRF_DESCRIPTION);
version: REPO_REVISION;
min_compatible_version: 87;
}

///////////////////
//Vehicle sprites//
///////////////////

spriteset(spriteset_real_htm_4001, "gfx/htm_4001.png") {
template_tram_28(0, 20)
}
spriteset(spriteset_real_htm_4001_1, "gfx/htm_4001.png") {
template_tram_24(0, 60)
}
spriteset(spriteset_real_htm_4001_2, "gfx/htm_4001.png") {
template_tram_28(0, 100)
}

switch (FEAT_ROADVEHS, SELF, switch_spriteset_htm_4001, position_in_consist ) {
1: spriteset_real_htm_4001_1;
2: spriteset_real_htm_4001_2;
spriteset_real_htm_4001; //default
}

/////////////////////
//vehicle callbacks//
/////////////////////

//set number of articulated parts
switch (FEAT_ROADVEHS, SELF, switch_articulated_htm_4001, extra_callback_info1) {
1..2: return item_tram_htm_4001; //use same vehicle for all parts
return CB_RESULT_NO_MORE_ARTICULATED_PARTS; //stop adding vehicle parts
}

//set length of each part
switch (FEAT_ROADVEHS, SELF, switch_length_htm_4001, position_in_consist ) {
1: return 2;
return 1;
}

//set capacity of each part
switch (FEAT_ROADVEHS, SELF, switch_capacity_htm_4001, position_in_consist ) {
1: return 26;
return 38; //default
}

//////////////////////
//vehicle properties//
//////////////////////

item (FEAT_ROADVEHS, item_tram_htm_4001) {
property {
name: string(STR_NAME_HTM_4001);
introduction_date: date(2006,1,1);
model_life: VEHICLE_NEVER_EXPIRES;
retire_early: 0;
vehicle_life: 25;
loading_speed: 25;
cost_factor: 224;
running_cost_factor: 112;
speed: 81 km/h;
power: 966 hp;
weight: 58 ton;
cargo_capacity: (38*2+26)/3;
tractive_effort_coefficient: 0.5;
air_drag_coefficient: 0;
//sound_effect: no sound
//visual_effect: use default (none)

//callback_flags: no need to set this
reliability_decay: 20;
climates_available: ALL_CLIMATES;
refittable_cargo_classes: bitmask(CC_PASSENGERS);
sprite_id: SPRITE_ID_NEW_ROADVEH; //use custom sprites
misc_flags: bitmask(ROADVEH_FLAG_TRAM); //make this a tram
refit_cost: 0; //refits are free
running_cost_base: RUNNING_COST_ROADVEH;
}

graphics {
articulated_part: switch_articulated_htm_4001;
shorten_vehicle: switch_length_htm_4001; //<-- this one is added now
cargo_capacity: switch_capacity_htm_4001;
default: switch_spriteset_htm_4001;
}
}
</pre>

The graphics are there, the tram seems complete. Or is it? There still is a sprite for the purchase menu left and if you'll look closely you'll notice that the capacity displayed in the purchase menu isn't correct. And remember the text we added to the language file to be displayed in the purchase menu? That's all next, in the last part of this tram example.

{{NMLTutorialNavbar|Tram articulation|Tram purchase menu}}

NMLTutorial/Tram articulation

2011-12-13T22:27:12Z

Yexo: Use CB_RESULT_NO_MORE_ARTICULATED_PARTS instead of hardcodec 0xFF

{{NMLTutorial}}
''The example used here is the HTM 4001 from the [http://dev.openttdcoop.org/projects/dutchtramset/repository Dutch Tram Set]. The original code and graphics for this are by FooBar. 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/Tram|first part]] of the tram example. Here we'll define the tram's item block and make it articulated.

== Item block ==
The item block is not that different from that of a regular road vehicle. A tram is still a road vehicle, so the [http://newgrf-specs.tt-wiki.net/wiki/NML:Features feature] will again be <code>FEAT_ROADVEHS</code>. Give the item an identifier (here ''item_tram_htm_4001''), add a property sub-block and fill it like you did with the road vehicle.

One important thing to know is that the <code>cargo_capacity</code> property applies to a single part of the articulated vehicle. So the total capacity will be that what you have set for <code>cargo_capacity</code> multiplied by the number of vehicle parts. This means that the capacity can only be a multiple of the number of vehicle parts. The other properties apply to the vehicle as a whole.

Again you need to look all the available properties up in the [http://newgrf-specs.tt-wiki.net/wiki/NML:Properties_and_variables_and_callbacks NML Documentation] and whey you do you may arrive at an item block something like this:

<pre style="color:darkblue; white-space: pre-wrap">
item (FEAT_ROADVEHS, item_tram_htm_4001) {
property {
name: string(STR_NAME_HTM_4001);
introduction_date: date(2006,1,1);
model_life: VEHICLE_NEVER_EXPIRES;
retire_early: 0;
vehicle_life: 25;
loading_speed: 25;
cost_factor: 224;
running_cost_factor: 112;
speed: 81 km/h;
power: 966 hp;
weight: 58 ton;
cargo_capacity: (38*2+26)/3;
tractive_effort_coefficient: 0.5;
air_drag_coefficient: 0;
//sound_effect: no sound
//visual_effect: use default (none)

//callback_flags: no need to set this
reliability_decay: 20;
climates_available: ALL_CLIMATES;
refittable_cargo_classes: bitmask(CC_PASSENGERS);
sprite_id: SPRITE_ID_NEW_ROADVEH; //use custom sprites
misc_flags: bitmask(ROADVEH_FLAG_TRAM); //make this a tram
refit_cost: 0; //refits are free
running_cost_base: RUNNING_COST_ROADVEH;
}

graphics {
//this will be added next
}
}
</pre>

== Adding callbacks ==
As you may have guessed, making the vehicle articulated has something to do with callbacks. These will be referenced from the graphics block within the item block. We'll also be adding a second callback that makes the capacity different for each vehicle part. The middle part of the vehicle (as you will see on the next page) is somewhat shorter and thus can carry less passengers. We can show this in the vehicle details window using a callback.

=== Articulated vehicle callback ===
The name of the acticulated vehicle callback that must be used in the graphics block is <code>articulated_part</code>, which you can find in [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_callbacks this table]. There you'll also find information on how to use this callback.

Because this callback is a little more advanced than just telling how many vehicle parts you want, you need a switch with this callback to be able to use it. This means that from the graphics block you need to reference a switch block:

<pre style="color:darkblue; white-space: pre-wrap">
graphics {
articulated_part: switch_articulated_htm_4001;
}
</pre>

How this callback works is that the game runs the switch referenced in the graphics block multiple times. Every time the switch is run, it will increase the variable <code>extra_callback_info1</code> with 1, starting at 1. And every time the switch must return the identifier of a vehicle item that must be added. This can be the identifier of the item you define the callback for, or a different vehicle item. Because you can change the looks and properties of the attached vehicle parts by means of other switches/callbacks, it is fine to return the identifier of the same vehicle. If you want the game to stop adding more parts to the vehicle, you have the switch return a value of CB_RESULT_NO_MORE_ARTICULATED_PARTS.

This is a lot in words, but not so much in code. The switch you need is this:

<pre style="color:darkblue; white-space: pre-wrap">
switch (FEAT_ROADVEHS, SELF, switch_articulated_htm_4001, extra_callback_info1) {
1..2: return item_tram_htm_4001; //use same vehicle for all parts
return CB_RESULT_NO_MORE_ARTICULATED_PARTS; //stop adding vehicle parts
}
</pre>

Note that the identifier used here is the same as the one in the graphics block. So the first time the switch is run, the value of <code>extra_callback_info1</code> will be one. For value 1, <code>item_tram_htm_4001</code> is returned as vehicle identifier for the part to add to this vehicle. Then the switch is run again, now with <code>extra_callback_info1</code> set to 2. Again vehicle identifier <code>item_tram_htm_4001</code> is returned and another vehicle part added. Then the switch is run again with <code>extra_callback_info1</code> set to 3. This time the switch will return 0xFF, the game will add no new part and will stop running this switch.

Of course, this switch block goes above the item block, as it needs to be defined before you can use it. This particular code will now build a three part articulated vehicle.

=== Cargo capacity callback ===
A different callback can set the capacity of each of these three parts. This is useful if you want different capacities for each part (if each part must have the same capacity, the cargo_capacity property is enough and you don't need this callback).

The name of this callback for the graphics block is <code>cargo_capacity</code> and you can look that up in the [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_callbacks same place] as where you found the articulated vehicle callback. You can directly return a value for this callback from the graphics block, but then this would be the same for each part and that kinda defeats the purpose of this callback. So we'll have to use a switch block here as well, referred to from the graphics block:

<pre style="color:darkblue; white-space: pre-wrap">
graphics {
articulated_part: switch_articulated_htm_4001;
cargo_capacity: switch_capacity_htm_4001;
}
</pre>

In order to return a different value for each vehicle part, we somehow need to use the switch block to make a decision based on the position in the vehicle. Luckily, there's a variable that does just that: it is called <code>position_in_consist</code> and you can find it [http://newgrf-specs.tt-wiki.net/wiki/NML:Vehicles#Vehicle_variables here] in the NML Documentation.

For each vehicle part the game will tell the switch of what vehicle part number it wants to know the capacity. The switch must then return this value. In code:

<pre style="color:darkblue; white-space: pre-wrap">
switch (FEAT_ROADVEHS, SELF, switch_capacity_htm_4001, position_in_consist ) {
1: return 26;
return 38; //default
}
</pre>

Also here the identifier of the switch is the same as the one used in the graphics block. For <code>position_in_consist</code> 1 (the second vehicle part) this switch will return a capacity of 26. For all other vehicle parts (in this case only the first and the last, as we have a three part vehicle) it will return the default value of 38.

Also this switch block goes above the item block.

== Total code so far ==
If you put everything in the correct order, you should now have this:

<pre style="color:darkblue; white-space: pre-wrap; max-height: 200px; overflow:scroll">
// define the newgrf
grf {
grfid: "\FB\FB\01\02";
name: string(STR_GRF_NAME);
desc: string(STR_GRF_DESCRIPTION);
version: REPO_REVISION;
min_compatible_version: 87;
}

/////////////////////
//vehicle callbacks//
/////////////////////

//set number of articulated parts
switch (FEAT_ROADVEHS, SELF, switch_articulated_htm_4001, extra_callback_info1) {
1..2: return item_tram_htm_4001; //use same vehicle for all parts
return CB_RESULT_NO_MORE_ARTICULATED_PARTS; //stop adding vehicle parts
}

//set capacity of each part
switch (FEAT_ROADVEHS, SELF, switch_capacity_htm_4001, position_in_consist ) {
1: return 26;
return 38; //default
}

//////////////////////
//vehicle properties//
//////////////////////

item (FEAT_ROADVEHS, item_tram_htm_4001) {
property {
name: string(STR_NAME_HTM_4001);
introduction_date: date(2006,1,1);
model_life: VEHICLE_NEVER_EXPIRES;
retire_early: 0;
vehicle_life: 25;
loading_speed: 25;
cost_factor: 224;
running_cost_factor: 112;
speed: 81 km/h;
power: 966 hp;
weight: 58 ton;
cargo_capacity: (38*2+26)/3;
tractive_effort_coefficient: 0.5;
air_drag_coefficient: 0;
//sound_effect: no sound
//visual_effect: use default (none)

//callback_flags: no need to set this
reliability_decay: 20;
climates_available: ALL_CLIMATES;
refittable_cargo_classes: bitmask(CC_PASSENGERS);
sprite_id: SPRITE_ID_NEW_ROADVEH; //use custom sprites
misc_flags: bitmask(ROADVEH_FLAG_TRAM); //make this a tram
refit_cost: 0; //refits are free
running_cost_base: RUNNING_COST_ROADVEH;
}

graphics {
articulated_part: switch_articulated_htm_4001;
cargo_capacity: switch_capacity_htm_4001;
}
}
</pre>

Because we haven't added graphics, you cannot compile this into a NewGRF just yet. So we'll look into the graphics next.

{{NMLTutorialNavbar|Tram|Tram graphics}}

NMLTutorial/Object

2011-08-27T22:05:16Z

Yexo: use consistent naming throughout tutorial

{{NMLTutorial}}
''The example used here is from the [http://dev.openttdcoop.org/projects/dutchroadfurniture/repository Dutch Road Furniture]. The original graphics for this are by FooBar. The code is by FooBar, based on code for the object example from the [http://dev.openttdcoop.org/projects/nml/repository/show/examples NML source] by planetmaker and Hirundu. Code and graphics are both licensed according to the GPL v2 or later. The code has been modified for the purpose of this tutorial.''

== Introduction ==
Objects, as well as stations, houses, industry tiles and airport tiles are coded slightly differently than vehicles. This difference mainly has to do with how sprites are defined. Item blocks and callbacks with switch blocks are still used as before, so our focus will be mainly on the graphics part. Stations are currently not yet possible in NML.

In this example we will make an object with four views to be used on flat ground tiles. After that we'll also make this object work on slopes, using some advanced features available in OpenTTD.

== Folder structure ==
For this example we'll assume the following folder structure. There will be one language file in the ''lang'' folder, one graphics file in the ''gfx'' folder. These two folders sit together with the main NML file in one project folder:

object_example
|- lang
| |- english.lng
|- gfx
| |- dutch_fingerpost.png
|- custom_tags.txt
|- example_object.nml

== NML file ==
Start the NML file by adding a grf block.

<pre style="color:darkblue; white-space: pre-wrap">
grf {
grfid: "\FB\FB\05\01";
name: string(STR_GRF_NAME);
desc: string(STR_GRF_DESCRIPTION);
version: 0;
min_compatible_version: 0;
}
</pre>

Nothing fancy there, just like we used to do and starting at version 0.

== Item definition and property block ==
The item block for an object looks very similar to that of a vehicle. Of course now you use <code>FEAT_OBJECTS</code> as [http://newgrf-specs.tt-wiki.net/wiki/NML:Features feature] and give it an identifier of your choice. In the item block you add a property block listing the [http://newgrf-specs.tt-wiki.net/wiki/NML:Objects#Object_properties properties for the object] and a graphics block:

<pre style="color:darkblue; white-space: pre-wrap">
item (FEAT_OBJECTS, item_fingerpost_3) {
property {
class: "NLRF";
classname: string(STR_NLRF);
name: string(STR_FINGERPOST_3);
climates_available: ALL_CLIMATES;
size: [1,1];
build_cost_multiplier: 2;
remove_cost_multiplier: 8;
introduction_date: date(1961,1,1);
end_of_life_date: 0xFFFFFFFF;
object_flags: bitmask(OBJ_FLAG_REMOVE_IS_INCOME, OBJ_FLAG_NO_FOUNDATIONS, OBJ_FLAG_ALLOW_BRIDGE);
height: 2;
num_views: 4;
}
graphics {
additional_text: string(STR_FINGERPOST_3_PURCHASE);
}
}
</pre>

=== property block ===
Some properties may need a little explaining; others should be self-explanatory or check the [http://newgrf-specs.tt-wiki.net/wiki/NML:Objects#Object_properties NML Documentation] for details.

; class
: A four character string using only capital letters and numbers. This defines in what "group" this object is added in the object construction window. If you only have a few objects in your set, try to use a [http://newgrf-specs.tt-wiki.net/wiki/NML:Objects#Default_object_classes default object class]. If you have a comprehensive set with a lot of objects, it might make sense to define a [http://newgrf-specs.tt-wiki.net/wiki/NML:Objects#Default_object_classes custom class] (register it on the page linked).
; classname
: At least one object in each class needs to define the name of the class as string to be displayed in the object construction window.
; size
: Define the size in the format <code>[x,y]</code>. Objects are rectangular up to 15x15 tiles.
; end_of_life_date
: At which date the object becomes unavailable for purchase. Can be a <code>date()</code> or set to <code>0xFFFFFFFF</code> to use the maximum value possible.
; height
: In multiples of 16 pixels. Use 0 for flat objects, 1 for objects up to 16 pixels high, 2 for objects up to 32 pixels high etc.
; num_views
: Each object may have 1, 2 or 4 views. This can be used for rotations of the object or alternatively up to four different variations of the same object.

=== graphics block ===
We'll add the graphics later, so for now we only define a [http://newgrf-specs.tt-wiki.net/wiki/NML:Objects#Object_callbacks callback] here to show a description of the object in the purchase menu. The callback used for this is <code>additional_text</code> and can directly return a string from the graphics block.

== Language file ==
Only English as default language with NewGRF name and description. Also the strings from the item block for the object class name, the own name of the object and a purchase menu description are added

<pre style="color:darkblue; white-space: pre-wrap">
##grflangid 0x01

#Main grf title and description
STR_GRF_NAME :{TITLE}
STR_GRF_DESCRIPTION :Description: {SILVER}Dutch Road Furniture is an eyecandy object NewGRF that features road furniture that can be found alongside Dutch roads. {}(c)2011 FooBar. {}{BLACK}License: {SILVER}GPLv2 or higher.

#object classes
STR_NLRF :Dutch Road Furniture

#object name and description
STR_FINGERPOST_3 :Dutch Fingerpost three-way
STR_FINGERPOST_3_PURCHASE :The three-way fingerpost is centered at one side of the tile and facing outward. Intended to be placed directly opposite of the secondary road at a three-way junction.
</pre>

custom_tags.txt this time contains the <code>{TITLE}</code> of the NewGRF, see the introduction to [[NMLTutorial/Language_files#Custom_string_codes|language files]] for more details about the usage of custom_tags.txt.

That should have you started nicely. Next we'll look into spritelayout blocks which are used for the graphics of objects.

{{NMLTutorialNavbar|Train recolour|Spritelayout}}

NMLTutorial/Callback and switch

2011-08-24T11:37:03Z

Yexo: /* Switch blocks */

{{NMLTutorial}}

Callbacks allow to do some fancy things on the fly. Where properties are defined static, callbacks allow to change (some) properties depending on the game state (for instance the game year or what cargo a vehicle is refitted to). Apart from that, some callbacks allow things that are not possible from the usual item definition (such as graphic animations or articulated vehicles).

Callbacks are often used in combination with switches. Switches are things that allow to make a decision based on variables. These variables depend on the game state (so if you for instance want to change vehicle properties depending on the game year, you need a switch attached to the callback). Furthermore, switches can be used to "switch graphics" based on the same variables (e.g. pointing to different spritegroups/sets for each part of an articulated vehicle).

== Callbacks ==
What callbacks are available depend on the [[NMLTutorial/NML Syntax#Features|feature]] you're working on. Then you can [http://newgrf-specs.tt-wiki.net/wiki/NML:Properties_and_variables_and_callbacks look up] the available callbacks in the NML Documentation. These tables list the names of the callbacks, what they do and what value they want to see returned. Some callbacks need to be pointed to spritegroups, while others want a string or number returned.

Callbacks are defined in the [[NMLTutorial/Item#Graphics block|graphics block]] of the item block and from there they can either directly return a value or point to a switch or spritegroup. Let's look at the graphics block once more:

<pre white-space: pre-wrap">
item {
graphics {
callback: <identifier>|<return_value>;
[<callback2>: <identifier2>|<return_value2>;]
[...;]
}
}
</pre>

If you want to point the callback to a different block (a switch block or a spritegroup block), you just put the identifier of that block behind the name of the callback. If you want the callback to return a value (string or number) directly, you need to first write the keyword <code>return</code> and then the numeric value or <code>string()</code>.

So for example (using fictional callback names):

<pre style="color:darkblue; white-space: pre-wrap">
graphics {
callback_to_spritegroup: spritegroup_identifier;
callback_to_switch: switch_identifier;
callback_return_string: return string(STR_STRINGNAME);
callback_return_number: return 20;
default: spritegroup_default_graphics;
}
</pre>

Please note that all callbacks need to be defined in a '''single''' graphics block.

== Switch blocks ==
As written in the introduction, switch blocks can be used to make decisions on certain variables. A switch block can be used to decide a callback return value depending on a variable, or to decide what spritegroup to use for the graphics depending on a variable. You need to [http://newgrf-specs.tt-wiki.net/wiki/NML:Properties_and_variables_and_callbacks look up] what variables are available for the feature you're using. Don't forget the [http://newgrf-specs.tt-wiki.net/wiki/NML:General#General_variables general variables] that are available for all features.

If you think you can make these decisions using if/else statements, you're wrong. Most variables are only available in a switch block of the feature you're working on. So when working with callbacks and graphics, use switches to make decisions based on variables.

The switch block syntax looks like this:

<pre white-space: pre-wrap">
switch (<feature>, <relation>, <identifier>, <variable>) {
<range>: <return_value>;
<range2>: <return_value2>;
<default_return_value>;
}
</pre>

* <code><feature></code>: the [[NMLTutorial/NML Syntax#Features|feature]] you're working on.
* <code><relation></code>: either <code>SELF</code> or <code>PARENT</code>. This indicates if you want to use the variable of the item itself or that of it's related item. See the NML Documentation on [http://newgrf-specs.tt-wiki.net/wiki/NML:Switch switch blocks] for a table of what these relations are for each feature.
* <code><identifier></code>: a self-chosen identifier (name) for this switch. It's useful to start with ''switch_''.
* <code><variable></code>: the [http://newgrf-specs.tt-wiki.net/wiki/NML:Properties_and_variables_and_callbacks variable] you want to base this decision on<ref>To make things even more complicated, you can use expressions as a variable or even an array of multiple expressions. The last expression from the array is used to make the decision. To make things not even more complicated than they already are, we'll ignore this possibility for now.</ref>.
* <code><range></code>: Either a single value or a subrange from the value range available to this variable. If you want to specify a subrange, use <code><range_start>..<range_end></code>
* <code><return_value></code>: An identifier to a different switch or spritegroup block, or (when switching a callback) the <code>return</code> keyword followed by a number or string reference.
* <code><default_return_value></code>: Like a <code><return_value></code>, but this one is only used if none of the ranges specified above matches the value of the variable.

Now this may sound rather complicated and I agree that it may be a bit overwhelming when presented like this. Switches are one of the most complicated blocks in NML and they represent the VarAction2 in NFO. In case you're familiar with that: VarAction2 is one of the most complicated things in NFO as well.

Let's look at a little example showing some of the possibilities of a switch. Note that doesn't have an actual meaning other than showing some of the options. In reality it will be very uncommon that a single switch blocks needs to have a string returned for one range, a number for another range, point to an other switch for yet another range.

<pre style="color:darkblue; white-space: pre-wrap">
switch (FEAT_TRAINS, PARENT, some_vehicle_switch, (position_in_consist) {
0..2: return string(STRING_FOO_BAR); //return a text message
3..4: return; //returns 3 in case position_in_consist == 3 or 4 in case position_in_consist == 4
5..300: return 42; //42 is always a good answer
400: switch_other_identifier; //chain to some other switch block
401: return num_vehs_in_consist + 1; //return a value with a variable access
CB_FAILED; //return a failure result as default
}
</pre>

Because this particular example returns numbers and strings, it can only be a switch for a callback. Switches used for graphics will (only) return identifiers to spritegroups, for example (this is an actual realistic example for a change):

<pre style="color:darkblue; white-space: pre-wrap">
switch (FEAT_TRAINS, PARENT, some_other_vehicle_switch, (position_in_consist) {
1..2: spritegroup_vehicle_1; //use this for second and third part of articulated vehicle
3..4: spritegroup_vehicle_2; //use this for fourth and fifth part of articulated vehicle
5: spritegroup_vehicle_3; //use this for sixth part of articulated vehicle
spritegroup_vehicle_0; //use this for first and other parts of articulated vehicle (i.e. default)
}
</pre>

There's much more to say about callbacks and switch blocks, but this is probably intimidating enough already. Next we'll make an articulated tram vehicle to show you where these callbacks and switches go in your NML code.

{{NMLTutorialNavbar|Road vehicle cargo graphics|Tram}}

<references />

NMLTutorial/Template

2011-08-24T10:51:15Z

Yexo: /* Template parameter magic */

{{NMLTutorial}}

If you've ever coded a NewGRF before, you'll know that figuring out the position of sprites and size in a graphics file and aligning them ingame by changing the offsets is a b****. Using templates for the sprite definitions inside spriteset blocks will save you a lot of trouble.

== Templatable graphics files ==
First you need to make sure that your graphics file(s) are actually templatable. This means that every group of sprites for e.g. a vehicle needs to have the same sprite sizes and the same distances between those sprites. Futhermore each vehicle needs to be aligned consistently within their sprite boxes, otherwise you still end up having to specify custom offsets for each sprite.

If you have vehicles (or buildings or whatever) of different sizes, and still want to use a single template for that, you can make your sprite boxes as big as the largest vehicle (or whatever) and use these big boxes also for smaller sprites.

An example of how to template graphics for trams and road vehicles has been included below. As long as you stick your vehicle sprites in one of these predefined sprite boxes and aligned correctly like the example 'blocks', you can use the same template for the NML sprite code for multiple vehicles. This particular sprite template actually has eight different sprite templates for the eight (default, not counting overhangs) vehicle lengths available in OpenTTD (only use the first four in TTDPatch) and one for the purchase menu sprite. Each of these come with exactly one NML template with the sprite sizes and offsets. So if you have a full length (32px) vehicle, you use the 32px sprite template and the 32px NML templates that belongs to this.

[[Image:FooBarTramVehicleTemplates.png|frame|none|Sprite templates for trams/road vehicles in eight different vehicle lengths. Licensed GPLv2 or higher.]]

We'll look at the NML template code that belongs to these sprite templates later. The tram vehicle example which will follow later in this tutorial actually uses some of these sprite templates and code. For other premade templates, you can consider looking into the [http://dev.openttdcoop.org/projects/ogfx-rv/repository OpenGFX+ Road Vehicles] or [http://dev.openttdcoop.org/projects/ogfx-trains/repository OpenGFX+ Trains] source.

The actual position of each block of sprites within your graphics file doesn't matter. This part will be parameterized in the template code. So you can align them nicely in a grid, or just ploink them somewhere randomly, as long as you keep the block of sprites together.

== Template block ==
Let's now focus on the NML code that should go with a sprite template. The general syntax of the template block is as follows:

<pre>
template <templatename>([<param1> [, <param2> [, <param3>...]]]) {
<list_of_realsprites>
}
</pre>

The <code><templatename></code> is again a name that you choose, although you're encouraged to start it with ''template_''. Behind the name, between brackets and separated by commas, you can supply a list of template parameter names that you will use as variables in your template. You can provide any number of template parameters, including none at all. Inside the template block you supply a list of realsprites, just like you would in a normal [[NMLTutorial/Spriteset and spritegroup#<list_of_realsprites>|spriteset]].

=== Template parameter magic ===
The beauty of the templates are the template parameters. You can vary their values every time you call a template in your NML code, so the template parameter values can be different for every road vehicle. This means that you for instance can make the <code>left_x</code> in a template a variable.

Combine this with the fact that you can do any mathematical calculation with template parameters on the values, you can make a template as complex as you want.

Now you might find this very theoretical, so let's look at an example right quick. This will surely help you understand the template concept.

=== Example NML templates ===
The template examples below belong to the sprite templates from the image above. From the name of the template you can see which one you need for a specific sprite template. So if you used the ''6/8 (24px)'' sprite template, the <code>template_tram_24</code> is the one that goes with this.

<pre style="color:darkblue; white-space: pre-wrap; max-height: 400px; overflow:scroll">
template template_tram_32(x, y) {
//[left_x, upper_y, width, height, offset_x, offset_y]
[x, y, 10, 28, -4, -11]
[x+ 20, y, 26, 28, -17, -14]
[x+ 50, y, 36, 28, -18, -20]
[x+ 90, y, 26, 28, -9, -15]
[x+120, y, 10, 28, -4, -11]
[x+140, y, 26, 28, -16, -16]
[x+170, y, 36, 28, -18, -20]
[x+210, y, 26, 28, -8, -16]
}

template template_tram_28(x, y) {
//[left_x, upper_y, width, height, offset_x, offset_y]
[x, y, 10, 28, -4, -11]
[x+ 20, y, 26, 28, -17, -14]
[x+ 50, y, 36, 28, -20, -20]
[x+ 90, y, 26, 28, -9, -15]
[x+120, y, 10, 28, -4, -13]
[x+140, y, 26, 28, -16, -16]
[x+170, y, 36, 28, -16, -20]
[x+210, y, 26, 28, -8, -16]
}

template template_tram_24(x, y) {
//[left_x, upper_y, width, height, offset_x, offset_y]
[x, y, 10, 28, -4, -11]
[x+ 20, y, 26, 28, -17, -14]
[x+ 50, y, 36, 28, -22, -20]
[x+ 90, y, 26, 28, -9, -15]
[x+120, y, 10, 28, -4, -15]
[x+140, y, 26, 28, -16, -16]
[x+170, y, 36, 28, -14, -20]
[x+210, y, 26, 28, -8, -16]
}

template template_tram_20(x, y) {
//[left_x, upper_y, width, height, offset_x, offset_y]
[x, y, 10, 28, -4, -10]
[x+ 20, y, 26, 28, -17, -14]
[x+ 50, y, 36, 28, -24, -20]
[x+ 90, y, 26, 28, -9, -15]
[x+120, y, 10, 28, -4, -16]
[x+140, y, 26, 28, -16, -16]
[x+170, y, 36, 28, -12, -20]
[x+210, y, 26, 28, -8, -16]
}

template template_tram_16(x, y) {
//[left_x, upper_y, width, height, offset_x, offset_y]
[x, y, 10, 28, -4, -9]
[x+ 20, y, 26, 28, -17, -14]
[x+ 50, y, 36, 28, -26, -20]
[x+ 90, y, 26, 28, -9, -15]
[x+120, y, 10, 28, -4, -17]
[x+140, y, 26, 28, -16, -16]
[x+170, y, 36, 28, -10, -20]
[x+210, y, 26, 28, -8, -16]
}

template template_tram_12(x, y) {
//[left_x, upper_y, width, height, offset_x, offset_y]
[x, y, 10, 28, -4, -8]
[x+ 20, y, 26, 28, -17, -14]
[x+ 50, y, 36, 28, -28, -20]
[x+ 90, y, 26, 28, -9, -15]
[x+120, y, 10, 28, -4, -18]
[x+140, y, 26, 28, -16, -16]
[x+170, y, 36, 28, -8, -20]
[x+210, y, 26, 28, -8, -16]
}

template template_tram_8(x, y) {
//[left_x, upper_y, width, height, offset_x, offset_y]
[x, y, 10, 28, -4, -7]
[x+ 20, y, 26, 28, -17, -14]
[x+ 50, y, 36, 28, -30, -20]
[x+ 90, y, 26, 28, -9, -15]
[x+120, y, 10, 28, -4, -19]
[x+140, y, 26, 28, -16, -16]
[x+170, y, 36, 28, -6, -20]
[x+210, y, 26, 28, -8, -16]
}

template template_tram_4(x, y) {
//[left_x, upper_y, width, height, offset_x, offset_y]
[x, y, 10, 28, -4, -6]
[x+ 20, y, 26, 28, -17, -14]
[x+ 50, y, 36, 28, -32, -20]
[x+ 90, y, 26, 28, -9, -15]
[x+120, y, 10, 28, -4, -20]
[x+140, y, 26, 28, -16, -16]
[x+170, y, 36, 28, -4, -20]
[x+210, y, 26, 28, -8, -16]
}

template template_purchase(x, y) {
//[left_x, upper_y, width, height, offset_x, offset_y]
[x, y, 50, 12, -25, -6]
}
</pre>

In these templates, there are two template parameters <code>x</code> and <code>y</code>. Whenever you call one of these templates, you specify the horizontal distance between the top left of the graphics file and the top left of the block of sprites as value for <code>x</code> and the vertical distance as value for <code>y</code>. NML will then calculate the ''left_x'' for each sprite for you and will insert the ''upper_y'' as well.

With some rearranging of the position of the vehicles in their sprite boxes, you could probably come up with a single template that can be used for vehicles of any length, but that is a challenge for you to be accepted.

== Calling a template ==
As with everything, a template can only be called if it's defined. So templates are best placed shortly after the grf block.

Because a template is an alternative for a sprite definition, you call a template inside a spriteset block (or inside replace or replacenew blocks as those also define sprites). You can use multiple templates in a spriteset block or use one template multiple times consecutively.

So for example if you want to use the ''6/8 (24px)'' sprite template from above, you would define the spriteset for that using a template like this:

<pre style="color:darkblue; white-space: pre-wrap;">
spriteset(spriteset_tram_example, "gfx/FooBarTramVehicleTemplates.png") {
template_tram_24(0, 100)
}
</pre>

This will use 0 for the value of <code>x</code> and 100 for the value of <code>y</code> for the template parameters. Also note that you don't get a semicolon after the call to the template.

With template parameter values 0 and 100, NML will silently substitute <code>template_tram_24(0, 100)</code> with the recalculated contents from that particular template. The substituted content in this case would be:

<pre>
//[left_x, upper_y, width, height, offset_x, offset_y]
[ 0, 100, 10, 28, -4, -11]
[ 20, 100, 26, 28, -17, -14]
[ 50, 100, 36, 28, -22, -20]
[ 90, 100, 26, 28, -9, -15]
[120, 100, 10, 28, -4, -15]
[140, 100, 26, 28, -16, -16]
[170, 100, 36, 28, -14, -20]
[210, 100, 26, 28, -8, -16]
</pre>

Remember our road vehicle had two spritesets? These are templatable, so let's do that next!

{{NMLTutorialNavbar|Road vehicle graphics|Road vehicle graphics template}}

<references />

NMLTutorial/Starting an NML file

2011-08-22T22:12:37Z

Yexo: /* Summarizing */ don't advocate -u, -c is good, but not necesary for a basic tutorial

{{NMLTutorial}}

It's time to create your first NML file! All this reading must have made you hungry by now, so let's continue right quick.

== Where to put the NML file ==

From the [[NMLTutorial/Language files|Language files]] section you may remember this folder structure:

mygrf
|- lang
| |- english.lng
| |- other_language.lng
|- custom_tags.txt
|- mygrf.nml

This is exactly where the NML file should go: one folder above the language files, and in the same folder as custom_tags.txt. You can name the file any way you want, but try to avoid spaces. Create it either from the file explorer or from your text editor.

== The grf block ==
Nearly all NML files will start with a grf block. The grf block takes no parameters and is one of the simplest blocks there is. Your NML file also has no more than one grf block. NML files without a grf block are only useful for ''base graphic'' files such as the grf files from OpenGFX. So chances are that you need a grf block.

The general syntax of the grf block is:

<pre>
grf {
grfid: <literal-string>;
name: <string>;
desc: <string>;
version: <expression>;
min_compatible_version: <expression>;
}
</pre>

We'll be looking at every line of this grf block and give you an example how to fill it in.

=== Line 1: grf { ===
This indicates the start of the grf block and the ''opening curly bracket'' defines the start of it's contents. Just type it in your editor:

<pre style="color:darkblue">
grf {
</pre>

=== Line 2: grfid: <literal-string>; ===
This defines the GRFID of your NewGRF. A GRFID is a four-byte string that should be unique. If two NewGRFs have the same GRFID, only one can be used at a time and in OpenTTD chances are only one shows up in the NewGRF list. It's a convention to use the first two bytes for the creator's initials. The last two bytes should be numbers, typically the first number identifying which of the author's sets this is, and the second number being a version number.

The GRFID must be written as a quoted string, but now comes the complicated part: one character is one byte, but one byte is two hexadecimal characters. The first two bytes are best written as a normal quoted string. The last two are best written as escaped bytes, as this allows for 256 sets/versions rather than just 10.

So if your name is Simon Foster and you're starting the first version of your first set, your GRFID can be <code>"SF\01\01"</code>. This way, your GRFID is exactly four bytes: two normal characters S and F, and two escaped bytes 01. The backslash indicates that the next two characters together make one byte. When using escaped bytes, remember that they are in hex and as such can only consist the numbers 0-9 and letters A-F. See [http://en.wikipedia.org/wiki/Hexadecimal Wikipedia] for more details on the hexadecimal numeral system.

Now your second line of the nml file will be (but then with your own GRFID):

<pre style="color:darkblue">
grfid: "SF\01\01";
</pre>

=== Line 3: name: <string>; ===
This is the name of your NewGRF, as displayed ingame. NML expects a reference to a string in your language file here. Luckily, we [[NMLTutorial/Language files|already]] put a name for our NewGRF in there. Open the language file and check what name you attached to the string. In our example that would be <code>STR_GRF_NAME</code>.

To tell NML to use a string from the language file, you have to use the function <code>string(<string-name>)</code>, replacing <code><string-name></code> with the actual name of the string. This gives us <code>string(STR_GRF_NAME)</code>.

Put this in the third line:

<pre style="color:darkblue">
name: string(STR_GRF_NAME);
</pre>

=== Line 4: desc: <string>; ===
The description is similar to the name of the NewGRF. Again look up the name of the string in the language file and use the <code>string()</code> function to put it in the grf block. Line four:

<pre style="color:darkblue">
desc: string(STR_GRF_DESCRIPTION);
</pre>

=== Line 5: version: <expression>; ===
Another version? Yes. If your NewGRF is aimed at (but not limited to) OpenTTD you should use this to indicate the actual version and leave the GRFID constant. If your NewGRF is aimed at (but not limited to) TTDPatch you still should provide this version number, but ''bump the GRFID'' whenever a new release is not compatible with the previous release. More on this at the end of this page.

The first release of your NewGRF will start with version 0 and every subsequent release you will increase this value. In case you use a version control system, set this to the revision number.

This gives line five:

<pre style="color:darkblue">
version: 0;
</pre>

=== Line 6: min_compatible_version: <expression>; ===
For the first release, the minimal compatible version is also 0. Leave it at 0 for as long as subsequent releases are compatible with all previous releases. Whenever you need to break compatibility, you set this to the version number (from above) in which you have broken the compatibility.

Line six:

<pre style="color:darkblue">
min_compatible_version: 0;
</pre>

=== Line 7: } ===
The ''closing curly bracket'' defines the end of the grf block; it closes it if you will.

Just type a curly bracket on line seven:

<pre style="color:darkblue">
}
</pre>

== Summarizing ==
Already? You haven't told us about the semicolons at the end of each line in the grf block!

I haven't? Well, let's do that now then...

=== Semicolons ===
Like in a lot of other programming languages, a semicolon defines the end of an instruction. You must use these at the end of every instruction inside and outside a block, but not on lines that open or close a block (with a curly bracket).

The usage of semicolons in NML is identical (with the exception of templates) to that in Java or C-family (or PHP) languages. It allows to have multiple instructions on one line, which is useful in some cases.

=== Summarizing ===
This completes our grf block. All lines together, the example looks like this:

<pre style="color:darkblue">
grf {
grfid: "SF\01\01";
name: string(STR_GRF_NAME);
desc: string(STR_GRF_DESCRIPTION);
version: 0;
min_compatible_version: 0;
}
</pre>

If you like, you can encode this into a grf to see if it works. The grf will not do anything, but it should show up in the game if you add it.

You still remember how to use ''nmlc' on the command line, right? If not, check the [[NMLTutorial/Installation|Installation page]] with the details for your operating system, or maybe the following pointer is enough to get you going:

nmlc --grf mygrf.grf mygrf.nml

{{NMLTutorialNavbar|NML Syntax|Road vehicle}} 

== Breaking compatibility ==
Sometimes it happens that you have to break compatibility between different releases of your NewGRF. The NML Documentation has a separate chapter on [http://newgrf-specs.tt-wiki.net/wiki/NML:NewGRF_compatibility NewGRF compatibility] and what actions break compatibility and how to avoid breaking it in the first place.

However, if you must break compatibility, here's how to handle the version information in your NML file.

=== OpenTTD targeted NewGRFs ===
* Keep the GRFID you have;
* Don't forget to update <code>grf { version }</code>;
* Set <code>grf { min_compatible_version }</code> to the value of <code>grf { version }</code>.

This way, OpenTTD will hide the old release from the NewGRF window while keeping it available for older savegames to use (provided the user doesn't delete the old release). Old releases can still be downloaded from BaNaNaS for old savegames.

=== TTDPatch targeted NewGRFs ===
TTDPatch doesn't have a concept for <code>grf { min_compatible_version }</code> (or <code>grf { version }</code> for that matter). The only way to indicate broken compatibility in TTDPatch is to bump the GRFID. This means that you increase the last byte of the GRFID by one. So if your initial GRFID is <code>"SF\01\01"</code>, change it to <code>"SF\01\02"</code> for the next release.

As a consequence, both NewGRFs can be used separate from each other and in OpenTTD both will show up in the NewGRF window.

In order to avoid loading both the old version and the new version in the same game, you have to add a [[NMLTutorial/Version check|version check]] to the NewGRF in order to disable itself (or the older version).

{{NMLTutorialNavbar|NML Syntax|Road vehicle}}

NMLTutorial/Installation

2011-08-22T21:48:26Z

Yexo: /* Using NML */ -u is not the same as -c

{{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 commandline 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 Pyton, the Python Image Library and Ply. 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 commandline 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 commandline options available to NML are available via <code>nmlc -h</code> and are also listed at the end of 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 prebuilt (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, which 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 we'll be explaining the long route here. 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 commandline 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 follow commands, one at a time, confirm with Enter after each line:

D:
cd D:\grfs\nml
nmlc -u --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 -u 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 of file name, you need to enclose the complete path in double quotes, e.g.: <code>nmlc -u --grf "D:\grfs\my grf\mygrf.grf" "D:\grfs\mgrf\mygrf.nml"</code>. It is therefore recommended not to have any spaces.

All commandline options available to NML are available via the <code>nmlc -h</code> command and are also listed at the end of 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 Commandline 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++]

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

NMLTutorial

2011-06-21T20:11:40Z

Yexo: /* Example */

__TOC__

==Introduction==
Since june 2010 a new coding language for creating TTDpatch/OpenTTD GRF's exists: Newgrf Meta Language or NML. It differs significantly from the old way of GRF editing and although [http://hg.openttdcoop.org/nml/raw-file/tip/docs/index.html documentation] is available it may still be a challenge for people interested in using NML code.

There will be detailed examples of how coding in NML works on this new TT-wiki. Make sure to check the progress of this NML tutorial regularly.

==NML vs. NFO==
===Background===
NML is a high-level NewGRF language compiler which compiles NML and LNG files into newgrf files (and NFO files, if asked to do so). Coding a NewGRF in NML is similar to writing in any other programming language except that there are no real sub-routines; you can use the usual definition and condition statements.

===Language support===
NML provides easy support for different languages in one GRF. This is achieved by creating language files (LNG). These language files follow the convention used for OpenTTD translation files. When compiling NML files a search for language files will automatically be performed. Even without providing additional translations at least one language file must be specified, called default.lng.

===Image format support===
One of the conveniences of NML is the possibility to read other image formats, most notably [http://en.wikipedia.org/wiki/Portable_Network_Graphics PNG]. Remember though that those images still need to supply the proper 8bpp palette and are supported by the python image library.

===Example===
Does the above sound impressive, maybe even threatening to you? One illustration often says more than a thousand words so let's show the difference with two illustrations:

{| cellspacing="0" class="mainpagetable" text-align="left" style="background-color: #F8EABA; border: 1px solid #C0C090;"
|- valign="top"

|width="50%"|
'''NFO code snippet'''
:// Automatically generated by GRFCODEC. Do not modify!
:// (Info version 7)
:// Escapes: 2+ = 71 = D= = DR 2- = 70 = D+ = DF 2< = 7= = D- = DC 2> = 7! = Du* = DM 2u< = 7< = D* = DnF 2u> = 7> = Du<< = DnC
:2/ = 7G = D<< = DO 2% = 7g = D& 2u/ = 7gG = D| 2u% = 7GG = Du/ 2* = 7gg = D/ 2& = 7c = Du% 2| = 7C = D% 2^ 2sto = 2s 2rst = 2r 2+ 2ror = 2rot
:// Format: spritenum pcxfile xpos ypos compression ysize xsize xrel yrel

:0 * 4 \d416
:1 * 92 08 07 "SER0" "ÞSwedish Rails nightly-r52M" 00 "ÞSwedish rails are a replacement for the default rails" 00
|width="50%"|
'''NML code snippet'''
:grf {
::grfid : "SER0";
::name : string(STR_GRF_NAME);
::desc : string(STR_GRF_DESCRIPTION);
:}
'''NML laguage file snippet'''
:<nowiki>##</nowiki>grflangid 0x01
:STR_GRF_NAME :Swedish Rails {VERSION}
:STR_GRF_DESCRIPTION :Swedish rails are a replacement for the default rails
|}
[[Category:NML]][[Category:Tutorials]]

NMLTutorial

2011-06-19T16:26:51Z

Yexo: fix link to docs

==Introduction to Newgrf Meta Language (NML)==

Since june 2010 a new coding language for creating TTDpatch/OpenTTD GRF's exists: Newgrf Meta Language or NML. It differs significantly from the old way of GRF editing and although [http://hg.openttdcoop.org/nml/raw-file/tip/docs/index.html documentation] is available it may still be a challenge for people interested in using NML code.

There will be detailed examples of how coding in NML works on this new TT-wiki. Make sure to check the progress of this NML tutorial regularly.