TTWiki - User contributions [en-gb]

Dutch Trainset 2

2015-09-19T11:59:41Z

FooBar: remove alpha1 info due to outdated

__NOTOC__
{{DutchSets}}

[[Image:DTSnew3.PNG|center|link=Dutch Trainset 2]]

'''Dutch Trainset 2''' is a fully reworked version of the original [[Dutch Trainset]] for OpenTTD. A lot of trains were added and the graphics of many existing trains were improved and expanded with different liveries. Furthermore we built in native support for new cargoes provided by industry sets and fixed a number of bugs that were present in the first version of the trainset. We went way back to the dawn of Dutch railroads in 1839 and brought back Arend. We went ahead in time and give you the V250 Albatross. And most of everything in between, including the metros of Amsterdam and Rotterdam.

If you're looking for some details on [[Dutch Trainset 2/Handbook|how to play]] with the set or want to know what [[Dutch Trainset 2/Vehicles|vehicles]] are available, please find separate pages about that in the menu at the right.

== Downloads ==
Dutch Trainset 2 is available from the OpenTTD Online Content. If for some reason you want a manual download or older release, you can get that from the [http://bundles.openttdcoop.org/dutchtrains/releases/LATEST/ DevZone].

The DevZone also provides [http://bundles.openttdcoop.org/dutchtrains/push/LATEST/ nightly builds], in case you want to test out the latest and cannot wait for the next release.

Finally, the [http://dev.openttdcoop.org/projects/dutchtrains/repository source code] (licensed GPLv2+) is available from the DevZone as well.

[[Image:Dutchtrains.png|frame|center|All trains and wagons in 2.0.0-alpha1]]

== Reporting bugs ==
If you have any issue with this trainset, please report it to the [http://dev.openttdcoop.org/projects/dutchtrains/issues issue tracker] or the [http://www.tt-forums.net/viewtopic.php?t=59353 forum topic].

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

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

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

== See also ==
* [[Dutch Trainset 2/Handbook|Handbook]]
* [[Dutch Trainset 2/Vehicles|List of vehicles]]
* [[Dutch Trainset|First Dutch Trainset]]

== Links ==
; Forum
* [http://www.tt-forums.net/viewtopic.php?t=59353 Release topic]
* [http://www.tt-forums.net/viewtopic.php?f=26&t=5033 Development topic]
; Downloads
* [http://bundles.openttdcoop.org/dutchtrains/releases/LATEST/ Releases] (also on the Online Content)
* [http://bundles.openttdcoop.org/dutchtrains/push/LATEST/ Nightlies]
* [http://dev.openttdcoop.org/projects/dutchtrains/repository Source]
; Other
* [http://dev.openttdcoop.org/projects/dutchtrains/issues Issue tracker]
* [https://docs.google.com/spreadsheet/ccc?key=0Anuwxjk8DGu8dFZ2NlVocDh1TnVGaER6UWp4NzJ2enc Infosheet]

NMLTutorial/Parameters

2014-08-02T19:48:14Z

FooBar: /* Enumeration parameter */ example was missing type

{{NMLTutorial}}

== Introduction ==
NewGRF Parameters in NML are part of the grf block
<pre>grf {
grfid: "NML\FF";
name: string(STR_GRF_NAME);
desc: string(STR_GRF_DESC);
version: 1;
min_compatible_version: 0;
param <num> {
<name> {
name: string(STR_PARAM_NAME_ECONOMIES);
desc: string(STR_PARAM_DESC_ECONOMIES);
<specifics>
}
}
}
</pre>

Where <code>name</code> is the name the parameter is referenced further within the grf to read this parameter. <num> is the number of this parameter. The <num> parameter is optional and not needed when parameters are not re-ordered throughout versions. It can be used to keep the meaning of a specific NewGRF parameter while re-ordering the code. The meaning of a NewGRF parameter should should remain constant throughout versions of the same NewGRF or the NewGRF might become incompatible with previous versions of the same NewGRF (thus you'd need to change min_compatible_version if you change the meaning of the parameters at <num>.

== Parameter types ==
NML knows three different types of parameters, boolean, numeric ones and enumerations:

=== Boolean parameter ===
The boolean parameter is the easiest as it requires no further definitions besides the name and description. Optionally a single parameter can contain several boolean parameter values, each using a single bit, thus saving in the number of externally visible NewGRF parameters.
<pre>
param 3 { // 3rd parameter of the NewGRF
param_bool_1 { // 1st boolean value
name: string(STR_PARAM_NAME_DEBUG);
desc: string(STR_PARAM_DESC_DEBUG);
type: bool;
bit: 1; // uses 1st bit
}
param_bool_2 { // 2nd boolean value
name: string(STR_PARAM_NAME_DEBUG);
desc: string(STR_PARAM_DESC_DEBUG);
type: bool;
bit: 2; // uses 2nd bit
}
}
</pre>

=== Numeric parameter ===

The numeric parameter allows to directly input an (integer) number. It needs to have a minimum and maximum value given and optionally - and usually a good idea - a default value for the parameter:
<pre>
param 1 {
param_depot_year {
type: int;
name: string(STR_PARAM_DEPOTYEAR);
desc: string(STR_PARAM_DEPOTYEAR_DESC);
min_value: 0;
max_value: 5000000;
def_value: 1975;
}
}
</pre>

=== Enumeration parameter ===

The enumeration parameter basically is a numeric parameter where the single values have (additionally) a string attached to describe their meaning. Not all values need a string description, but it usually is a good idea to do this consistently
<pre>
param 0 {
economy {
type: int;
name: string(STR_PARAM_NAME_ECONOMIES);
desc: string(STR_PARAM_DESC_ECONOMIES);
min_value: 0;
max_value: 1;
def_value: 0;
names: {
0: string(STR_PARAM_VALUE_ECONOMIES_TEST_ECONOMY);
1: string(STR_PARAM_VALUE_ECONOMIES_HARD_ECONOMY);
};
}
}
</pre>

{{NMLTutorialNavbar|Train four part refit|Train recolour}}

NMLTutorial/Version check

2014-08-02T19:45:49Z

FooBar: /* If block */ is possible inside item block

{{NMLTutorial}}

Version checks are useful if you use certain features in your NewGRF that are not available in older versions of the game (or only available in one game and not the other, both TTDPatch and OpenTTD have some features that are not available in the other). If your NewGRF relies on a certain feature, you must have your NewGRF disable itself and issue an error message. If your NewGRF can work without a certain feature, you can use a version check to disable that part of your NewGRF while keeping the rest.

== If block ==
The basis of every version check is an if block<ref>Actually ''if'' is not a block but a language construct, but for the purpose of understanding it you can consider it a block.</ref>. The if blocks allows to check if a certain condition (for instance based on a [http://newgrf-specs.tt-wiki.net/wiki/NML:General#General_variables general variable] or a GRF parameter) is true. If the condition is true, the contents inside the switch block is executed, otherwise it's skipped.

An if block looks like this:

<pre class="pseudo">
if (<condition>) {
<code_executed_when_condition_true>
}
</pre>

The <code><condition></code> usually is a [http://newgrf-specs.tt-wiki.net/wiki/NML:General#General_variables general variable] or GRF parameter compared against a static value, a different variable or a different parameter. The <code><code_executed_when_condition_true></code> can be anything you would normally write in an NML file, so you can have one or more blocks inside an if block. However, you cannot have if blocks inside other blocks (except other if or else blocks and item blocks). The code inside the if block is only executed when the <code><condition></code> is true.

=== <condition> ===

The comparison itself is made using a ''comparison operator'' which you may already know from different programming languages. Here's a table with the comparison operators available in NML:


<table>
<tr><th> Symbol </th><th> Description</th></tr>
<tr><td><code> == </code></td><td> Is equal to </td></tr>
<tr><td> <code>!= </code></td><td> Is not equal to </td></tr>
<tr><td><code> < </code></td><td> Is less than </td></tr>
<tr><td><code> <= </code></td><td> Is less than or equal to </td></tr>
<tr><td><code> > </code></td><td> Is bigger than </td></tr>
<tr><td><code> >= </code></td><td> Is bigger than or equal to </td></tr>
</table>

So for example if you want to check if A is bigger than or equal to B:

<pre class="example">
if (A >= B) {
//whatever happens when A is bigger than or equal to B goes here
}
</pre>

In case you make multiple comparisons, you can either nest multiple if blocks or combine those comparisons in a single <code><condition></code> using the so-called logical operators. The logical operators can work with boolean values (true or false) to combine multiple comparisons. Here's a table with the logical operators available in NML:


<table>
<tr><th> Symbol </th><th> Description</th></tr>
<tr><td><code> && </code></td><td> Logical AND. True if both sides are true. </td></tr>
<tr><td><code> || </code></td><td> Logical OR. True if either side (or both) are true. </td></tr>
</table>

So for instance if you want to check if A is bigger than or equal to B while at the same time C is not equal to D:

<pre class="example">
if ((A >= B) && (C != D)) {
//whatever happens when A is bigger than or equal to B and C is not equal to D goes here
}
</pre>

Things between brackets is evaluated first before combining it with things outside these brackets this makes sure that a certain sub-condition is evaluated to true/false before logically combining it (the comparison operators can compare just about anything, but the logical operators can only combine boolean values). In some cases you do not need all brackets, which has something to do with ''operator precedence''; we will not bother you with that right now. When in doubt, it doesn't hurt to use more brackets than actually needed (as long as they are in the correct places of course!) and they work very similar to brackets in mathematics.

=== else ===
If besides something you want to do when the condition is true, you also want to do something else when the condition is ''not'' true, you can add an else block behind the if block:

<pre class="pseudo">
if (<condition>) {
<code_executed_when_condition_true>
}
else {
<code_executed_when_condition_false>
}
</pre>

The code in the if block will only be executed when the condition is true. The code in the else block is only executed when the condition (for the if block) is not true. An else block must be written directly behind the closing curly bracket of the if block, with no other code inbetween.

You can also combine an else and if block:

<pre class="pseudo">
if (<condition>) {
<code_executed_when_condition_true>
}
else if (<other_condition>) {
<code_executed_when_other_condition_true>
}
else {
<code_executed_when_both_conditions_false>
}
</pre>

With this, if the first comparison is false, you make a different comparison and when even that is false you get the ''else''. You can have as many else if blocks between an if block and an else block as you want. Again no other code may appear inbetween those blocks (but of course you can have any code you like inside these blocks).

== Error function ==
The error function allows to issue notices, warnings, errors and fatal error messages. The fatal type also disables the NewGRF immediately. The general syntax of an error block is:

<pre class="pseudo">
error(<level>, <message> [, <extra_text> [, <parameter1> [, <parameter2> ]]])
</pre>

The error function may appear outside blocks, inside if or else blocks, but not inside other blocks.

The error <code><level></code> can be any of:

<table>
<tr><th> Constant </th><th> Description </th></tr>
<tr><td><code> NOTICE </code></td><td> Add a notice in the NewGRF status window, continue loading the grf. </td></tr>
<tr><td><code> WARNING </code></td><td> Add a warning in the NewGRF status window, prefixed with "Warning: ", continue loading the grf. </td></tr>
<tr><td><code> ERROR </code></td><td> Add a error message in the NewGRF status window, prefixed with "Error: ", continue loading the grf. </td></tr>
<tr><td><code> FATAL </code></td><td> Add a error message in the NewGRF status window, prefixed with "Error: ", abort loading the grf, also give the error message in a red popup box ingame. </td></tr>
</table>

<code><message></code> can be one of seven predefined messages (see the [http://newgrf-specs.tt-wiki.net/wiki/NML:Error NML Documentation]) or a custom string (using the <code>string()</code> function). <code><extra_text></code>, <code><parameter1></code> and <code><parameter2></code> are optional. <code><extra_text></code> must be used when one of the predefined messages is used and can either be a string from the language file or a literal quoted string in the NML code. <code><parameter1></code> and <code><parameter2></code> can be used in custom strings and when defined must be the identifier of a GRF parameter.

So if you want to disable your NewGRF with an error message, you use the <code>FATAL</code> error level combined with either a predefined string or a error message of your own. If you just want a message without disabling your NewGRF, use one of the other error levels.

== Examples ==
Version checks in NML are actually pretty straight forward.

NML provides the [http://newgrf-specs.tt-wiki.net/wiki/NML:General#General_variables general variables] <code>openttd_version</code>, <code>ttdpatch_version</code> and <code>ttd_platform</code> to do version and game platform checks. Concerning <code>openttd_version</code> checks the built-in [http://newgrf-specs.tt-wiki.net/wiki/NML:Builtin_functions function] <code>version_openttd()</code> comes in very handy as it provides an easy means to specify the version instead of manually constructing the version number corresponding to a specific version.

=== Check game platform ===
Checking for the OpenTTD platform is simply done by an if block:

<pre class="example">
if (ttd_platform != PLATFORM_OPENTTD) {
error(FATAL, string(STR_REQUIRES_OPENTTD));
}
</pre>

The string <code>STR_REQUIRES_OPENTTD</code> will hold an error message telling the (TTDPatch) user that OpenTTD is needed for this NewGRF. Note that you cannot use the predefined <code>REQUIRES_OPENTTD</code> as this string doesn't exist in TTDPatch!

Similarly, if you want to check for the TTDPatch platform:

<pre class="example">
if (ttd_platform != PLATFORM_TTDPATCH) {
error(FATAL, REQUIRES_TTDPATCH, string(STR_VERSION_TTDPATCH));
}
</pre>

This time you ''can'' use the predefined <code>REQUIRES_TTDPATCH</code> string, as this string does exist in OpenTTD.

=== Check game version and die ===
If you NewGRF requires a specific feature to work, disable it if a game version is used that doesn't have that version.

This is a check to disable the NewGRF if a certain OpenTTD feature is not found:

<pre class="example">
//parameterized spritelayout is only supported since OpenTTD 1.2.0 r22723
if (version_openttd(1,2,0,22723) > openttd_version) {
error(FATAL, REQUIRES_OPENTTD, "1.2.0 (r22723)");
}
</pre>

=== Check game version and conditionally use more advanced features ===
If your NewGRF doesn't need a specific feature to work, you can disable that version for older versions.

This is a check for a specific OpenTTD (and similarily TTDPatch) version:

<pre class="example">
/* Only define cargo_age_period when that property is available */
if (openttd_version > version_openttd(1, 2, 0, 22713)) {
item (FEAT_TRAINS, my_engine) {
property {
cargo_age_period: 200;
}
}
}
</pre>

=== Combining platform and version checks ===
You must not check the OpenTTD version in TTDPatch or the TTDPatch version in OpenTTD. TTDPatch doesn't have any useful information for the OpenTTD version and similarly OpenTTD doesn't have useful information for the TTDPatch version.

You can nest both checks above using multiple if blocks. It's also possible to combine these checks into a single block:

<pre class="example">
/* Long date string codes require OpenTTD > 1.2.0 or r22780 */
if (ttd_platform != PLATFORM_OPENTTD || openttd_version < version_openttd(1, 2, 0, 22780)) {
error(FATAL, REQUIRES_OPENTTD, string(STR_MIN_OPENTTD_VERSION));
}
</pre>

{{NMLTutorialNavbar|Object graphics|Object slopes}}

<references/>

NMLTutorial/Conclusion

2014-07-23T10:49:22Z

FooBar: Dutch Trainset is no longer planned

{{NMLTutorial}}

There you are, the very end of the NML tutorial. It's been a pleasure to write and I hope learned a thing or two. If you still think NML is not for you, maybe try your luck at [[GraphicsTutorial|drawing graphics]] instead. If you think NML is not too bad, then I hope to see a nice NewGRF from you any time soon!

If you have any further questions on how to make your NewGRF in NML that are not addressed in the tutorial, feel free to ask them on the [http://www.tt-forums.net/viewforum.php?f=68 forums] or on [irc://irc.oftc.net/openttdcoop.devzone irc]. There always will be people that can help you out. And don't forget the [http://newgrf-specs.tt-wiki.net/wiki/NML:Main NML Documentation] itself. From here on, you should refer to that instead of this tutorial. Try to use it as much as possible to get familiar with it. I can't write NML without the NML Documentation, so you surely can't either.

Below you'll find a list of NML project with a public (and open) source. Feel free to browse them for inspiration or not having to reinvent the wheel, but respect the licenses these sources come with. Good luck!

--[[User:FooBar|FooBar]] 11:30, 29 August 2011 (UTC)

== List of open source NML projects ==
Below is an alphabetical list of open source NML projects. If your NML project is open source and not listed here, feel free to add it.

* [http://dev.openttdcoop.org/projects/ce-tracks/ Central European Railway Track Set]
* [http://dev.openttdcoop.org/projects/cets Central European Train Set]
* [http://dev.openttdcoop.org/projects/dutchroadfurniture Dutch Road Furniture]
* [http://dev.openttdcoop.org/projects/dutchtrains Dutch Trains 2]
* [http://dev.openttdcoop.org/projects/dutchtramset Dutch Tram Set]
* [http://dev.openttdcoop.org/projects/firs FIRS Industry Replacement Set]
* [http://dev.openttdcoop.org/projects/foobarstramtracks FooBar's Tram Tracks]
* [http://dev.openttdcoop.org/projects/manindu Manual Industries]
* [http://dev.openttdcoop.org/projects/narvs North American Road Vehicle Set]
* [http://dev.openttdcoop.org/projects/airportsplus OpenGFX+ Airports]
* [http://dev.openttdcoop.org/projects/ogfx-industries OpenGFX+ Industries]
* [http://dev.openttdcoop.org/projects/ogfx-landscape OpenGFX+ Landscape]
* [http://dev.openttdcoop.org/projects/ogfx-rv OpenGFX+ Road Vehicles]
* [http://dev.openttdcoop.org/projects/ogfx-trains OpenGFX+ Trains]
* [http://dev.openttdcoop.org/projects/swedishrails Swedish Rails]

{{NMLTutorialNavbar|Object slopes||}}

Releasing a NewGRF

2012-08-27T09:16:23Z

FooBar: complete page

So you've made yourself a NewGRF and want to release it to the public. How do you go about doing that?

== Write a ReadMe ==
While most people will never read your readme, it's still useful to write one. If only to let people know who made the NewGRF, how they can be contacted, and if they're allowed to use bits of it for something else (i.e. a license, more on that later). Generally a readme also includes some information on what the NewGRF does and how it must be used.

It's useful to write your readme in plain text format. That way it can be opened in OpenTTD's ingame viewer, for easy access. There's a [[User:FooBar/Generic NewGRF Readme|readme template]] available that you can use as the basis for your own readme.

== Choose a license ==
If you don't choose a license, in most countries your work will be automatically protected by copyright law. This means that nobody may use parts of your work for something else without prior permission. By applying a license to your work, you can grant certain permissions so that people don't have to ask every time. That way others can use bits of your work in their own to for instance improve compatibility between both.

planetmaker's written an interesting [http://blog.openttdcoop.org/2011/07/16/copyright-and-licenses-permission-to-what-actually/ article on the subject of licensing]. It's a recommended read if you're not sure what license to apply to your work.

== Bundle your work ==
Once you have a NewGRF, a ReadMe and a License, you want to bundle those. It's useful to combine all three in a TAR file. OpenTTD can read TAR files without the need for extracting them. That way NewGRF, ReadMe and License will always stay together. Also BaNaNaS accepts TAR files. TTDPatch users can easily extract them, as the TAR format is widely supported by file compression tools. Note that the TAR format doesn't use compression, so if you want to reduce filesize you can furthermore zip the TAR file.

In case you used the [http://dev.openttdcoop.org/ #openttdcoop DevZone] you can tag a revision in your repository as a release. The DevZone will then automatically build a release bundle which you can retrieve from [http://bundles.openttdcoop.org/]. It's recommended to use this bundle for the next step instead of your own build, to make sure all downloads are the same.

== Uploading the bundle ==
To make your NewGRF easily accessible to everyone, you certainly would want to upload it to OpenTTD's Online Content service. For this you go to [http://bananas.openttd.org/] and click the Manager tab. You're asked to login with your OpenTTD account (which is the same as for the OpenTTD bug tracker and the OpenTTD wiki) or create one if you don't have one. Note that this is different from your TT-Forums (or TT-Wiki) account. Please read the Terms of Service carefully, which also state what files to upload exactly. From the Manager tab choose to Upload New and complete the fields.

In addition to the Online Content service you may also want to host your NewGRF bundle elsewhere. This will both serve as a backup and aid TTDPatch users as it's a bit weird for them to get their grfs from the OpenTTD service. The TT-Forums are suitable for hosting your NewGRF in an attachment. If you used an online collaboration platform like the [http://dev.openttdcoop.org/ #openttdcoop DevZone] you can use that as additional hosting for your NewGRF.

== Letting the world know ==
Certainly you will want to make a post in the TT-Forums [http://www.tt-forums.net/viewforum.php?f=67 Graphics Releases forum]. Write a few words about your NewGRF, add a screenshot and provide a pointer to the download location. You can very well use this post to host your NewGRF in an attachment.

Additinally, advertise your NewGRF on [http://grfcrawler.tt-forums.net/ GRFCrawler]. You're logged in there automatically if you're logged in to TT-Forums.

== Providing the source ==
This step is only required if you've chosen a license that requires you to provide the source, like the GPL. In case of the #openttdcoop DevZone or similar, your source repository will qualify as "providing the source". In other cases you have to make a source bundle. This then includes the "preferred files to make edits to the work". Upload the source bundle somewhere. Maybe use the TT-Forums topic for it if your source isn't too big, otherwise find reliable hosting elsewhere. Of course you can also hide behind the "three year written offer", but this will only provoke people requesting the source even if they don't need it, resulting you into having to make the source bundle and upload it somewhere anyways.

[[Category:Tutorials]]

Releasing a NewGRF

2012-08-27T08:54:37Z

FooBar: intermediate save

Tutorials

2012-08-27T08:27:02Z

FooBar: /* Coding NewGRFs for OpenTTD and TTDPatch */

== Playing OpenTTD and TTDPatch ==

* [[PreSignalsTutorial]]: How to use pre-signals

== Coding NewGRFs for OpenTTD and TTDPatch ==

* [[NFOTutorial|NFO Tutorial]]: How to make NewGRFs using NFO (incomplete)
* [[NMLTutorial|NML Tutorial]]: How to make NewGRFs using the NewGRF Meta Language (NML)
* [http://www.tt-forums.net/viewtopic.php?f=26&t=62069 Station Tutorial]: Complete tutorial on station coding from scratch in NFO.

* [[Releasing a NewGRF]]: How to release your NewGRF to the public once you made one.

== General sprite drawing ==

* [[GraphicsTutorial]]: How to draw new 8bpp graphics sprites
* [[Creating_new_Sprites_with_3dsMax|Using 3dsmax]]: Creating sprites using 3DSMax (aimed at Locomotion currently)

Tutorials

2012-08-05T20:05:32Z

FooBar: add link to Quast65's station tutorial

== Playing OpenTTD and TTDPatch ==

* [[PreSignalsTutorial]]: How to use pre-signals

== Coding NewGRFs for OpenTTD and TTDPatch ==

* [[NFOTutorial|NFO Tutorial]]: How to make NewGRFs using NFO (incomplete)
* [[NMLTutorial|NML Tutorial]]: How to make NewGRFs using the NewGRF Meta Language (NML)
* [http://www.tt-forums.net/viewtopic.php?f=26&t=62069 Station Tutorial]: Complete tutorial on station coding from scratch in NFO.

== General sprite drawing ==

* [[GraphicsTutorial]]: How to draw new 8bpp graphics sprites
* [[Creating_new_Sprites_with_3dsMax|Using 3dsmax]]: Creating sprites using 3DSMax (aimed at Locomotion currently)

NMLTutorial/32 bit base graphics

2012-06-27T12:07:15Z

FooBar: complete page

NMLTutorial/32 bit base graphics

2012-06-27T11:44:42Z

FooBar: intermediate save

{{NMLTutorial}}

In this example we'll look into a small base graphics replacement, for both 8 bit and 32 bit graphics. We'll be replacing some level crossings in temperate and actic climate.

== Example graphics ==
There will be three sets of graphics: regular 8 bit sprites, 32 bit sprites for the normal zoom level and an accompanying mask file. These graphics will be replacing sprites [[:File:Ogfx1_base.png|1370 to 1373]]. The sprites for the arctic climate will occupy the same slots.

Here are the 8 bit sprites. Note that they're neatly ordered, so that we can use a template later on.
[[File:Levelcrossings8.png|frame|none|levelcrossings8.png - Level crossing sprites in open and closed state, for two climates. 8 bit.]]

The 32 bit sprites are very similar, but with a transparent instead of blue background. The pink bits are just to indicate the sprite borders.
[[File:Levelcrossings32.png|frame|none|levelcrossings32.png - Level crossing sprites in open and closed state, for two climates. 32 bit.]]

In order to get animation for the crossing lights with the 32 bit version, we need an additional mask file. This mask just contains the crossing lights in the exact positions as in the 32 bit file. This is an 8 bit file, so we have to use the blue background to indicate transparency.
[[File:Levelcrossingsmask.png|frame|none|levelcrossingsmask.png - Mask file for 32 bit sprites. 8 bit.]]

== Replace ==
Let's start with the replace blocks for the 8 bit sprites. We'll add the 32 bit sprites later.

<pre style="color:darkblue; white-space: pre-wrap">
replace replace_levelcrossings_temperate(1370, "gfx/levelcrossings.png") {
//realsprites go here
}
</pre>

We've chosen the identifier <code>replace_levelcrossings_temperate</code>. It's not mandatory for 8 bit sprites alone, but we need it if we want to attach 32 bit sprites later. So why not add it straight away, right? The <code>1370</code> is the sprite number of the first sprite we want to replace.

=== Template ===
As stated before, we want to template these sprites. There are four sprites for each climate, all with the same offsets because all sprite boxes are the same size, so the template will be pretty straightforward:

<pre style="color:darkblue; white-space: pre-wrap">
template template_levelcrossing(x, y) {
//[left_x, upper_y, width, height, offset_x, offset_y]
[x , y, 64, 42, -31, -11]
[x+80 , y, 64, 42, -31, -11]
[x+160, y, 64, 42, -31, -11]
[x+240, y, 64, 42, -31, -11]
}
</pre>

The x and y position are variable in the template, because we have the sprites for both climates in one file. Now it's just a matter of referencing our template inside the <code>replace</code> block and filling in the correct position of the top left pixel of the first sprite:

<pre style="color:darkblue; white-space: pre-wrap">
replace replace_levelcrossings_temperate(1370, "gfx/levelcrossings.png") {
template_levelcrossing(0, 0)
}
</pre>

=== Other climate ===
The procedure for the actic climate will be identical, but we need to select the correct sprites depending on the selected climate. This means guarding the two <code>replace</code> blocks with <code>if</code>-statements. Let's look at those <code>if</code>-statements first:

<pre style="color:darkblue; white-space: pre-wrap">
if (climate == CLIMATE_TEMPERATE) {
replace replace_levelcrossings_temperate(1370, "gfx/levelcrossings.png") {
template_levelcrossing(0, 0)
}
}
if (climate == CLIMATE_ARCTIC) {
replace replace_levelcrossings_arctic(1370, "gfx/levelcrossings.png") {
template_levelcrossing(0, 320)
}
}
</pre>

You may use an <code>else</code> in front of the second if block, but that's not really necessary in this case. From here it's just a matter of adding the <code>replace</code> block for the temperate climate and writing a similar one for the arctic climate. The one for the arctic climate will of course get a different identifier and different template parameters:

<pre style="color:darkblue; white-space: pre-wrap">
if (climate == CLIMATE_TEMPERATE) {
//replace block for temperate to go here
}
if (climate == CLIMATE_ARCTIC) {
//replace block for temperate to go here
}
</pre>

And this is actually all there is to it, if you just want 8 bit sprites. We'll leave adding a <code>grf</code> block and the language file over to you. It's no different than for the [[NMLTutorial/Road vehicle|road vehicle]].

== 32 bit graphics ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

And with that we conclude this example and in fact the whole series! Feel free to read the conclusion. Or not.

{{NMLTutorialNavbar|Base graphics replacement|Conclusion}}

File:Levelcrossingsmask.png

2012-06-27T11:24:27Z

FooBar: Example for the NML tutorial. Graphics by Purno (level crossing lights) and Zephyris (road and terrain). Part of Dutch Rail Furniture, licensed GPLv2.

Example for the NML tutorial. Graphics by Purno (level crossing lights) and Zephyris (road and terrain). Part of Dutch Rail Furniture, licensed GPLv2.

File:Levelcrossings32.png

2012-06-27T11:22:57Z

FooBar: Example for the NML tutorial. Graphics by Purno (level crossing lights) and Zephyris (road and terrain). Part of Dutch Rail Furniture, licensed GPLv2.

Example for the NML tutorial. Graphics by Purno (level crossing lights) and Zephyris (road and terrain). Part of Dutch Rail Furniture, licensed GPLv2.

File:Levelcrossings8.png

2012-06-27T11:21:01Z

FooBar: Example for the NML tutorial. Graphics by Purno (level crossing lights) and Zephyris (road and terrain). Part of Dutch Rail Furniture, licensed GPLv2.

Example for the NML tutorial. Graphics by Purno (level crossing lights) and Zephyris (road and terrain). Part of Dutch Rail Furniture, licensed GPLv2.

NMLTutorial/Road vehicle 32 bit sprites

2012-06-26T20:47:32Z

FooBar: point to base graphics replacement as next page

{{NMLTutorial}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

And with that we end this example of adding 32 bit sprites to your road vehicle NewGRF. Of course, the same method as used here also applies to providing 32 bit alternatives for any other <code>spriteset</code> you may have. Now you can continue to learn how to replace base graphics.

{{NMLTutorialNavbar|32 bit sprites|Base graphics replacement}}

NMLTutorial/Base graphics replacement

2012-06-26T20:46:07Z

FooBar: finish page

{{NMLTutorial}}

A base graphics set provides the graphics you see when you have no NewGRFs loaded. If you don't want to add any new elements to the game, you can easily replace just these graphics via NewGRF.

There are to distinct types of base graphis: those originating from TTD and those that were added later to TTDPatch and OpenTTD. The first type is replaced by means of the <code>replace</code> block, the latter by means of the <code>replacenew</code> block. The way these blocks work are similar to the [[NMLTutorial/Spriteset and spritegroup|spriteset block]].

== Replace TTD sprites ==
And by this we mean the graphics that originally were in TTD. If you use OpenGFX, this will of course replace OpenGFX sprites and not TTD sprites. But in either case we mean replacements of the sprites in trg1(r).grf (TTD) or ogfx1_base.grf (OpenGFX). It's useful to have a decode (grfcodec) of either of those grfs available to look up the sprite numbers. If you don't have that, you can find one [[:File:Ogfx1 base.png|here]] (choose to view the full resolution version below the thumbnail).

Once you have the sprites you want to replace and know their sprite numbers, you can start writing your <code>replace</code>. The general syntax is as follows:

<pre class="pseudo">
replace [<identifier>] (<sprite-id> [, <image-file>] ) {
<list_of_realsprites>
}
</pre>

The <code><identifier></code> is something you choose yourself. It's useful to prefix it with ''replace_'' to avoid confusion with other identifiers in your code. It's optional if you only want to replace regular 8 bit sprites, but required if you also want to provide 32 bit sprites and/or sprites for different zoom levels. The <code><sprite-id></code> is the sprite number of the first sprite you want to replace. You can then place all consecutive replacement sprites in this block. As soon as there is a gap, you start a new <code>replace</code> block. The <code><image-file></code> is again optional. Like with a <code>spriteset</code> you can either provide a single filename for all sprites inside the block, or omit the filename here and specify the filename for each realsprite individually.

The <code><list_of_realsprites></code> is the same as for [[NMLTutorial/Spriteset and spritegroup|spriteset blocks]].

=== Climates other than temperate ===
The previous method will provide replacement sprites for all climates at the same time. If you want to provide different sprites for each climate, you'll have to write different <code>replace</code> blocks for each climate. Each of these climate specific blocks are guarded by <code>if</code>-statements as [[NMLTutorial/Version check|introduced earlier]]. In the <code>if</code>-statement you will test the active climate, using the <code>climate</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:General general variable]. Depending on the climate, this variable is equal to one of the following: <code>CLIMATE_TEMPERATE</code>, <code>CLIMATE_ARCTIC</code>, <code>CLIMATE_TROPICAL</code> or <code>CLIMATE_TOYLAND</code>.

This will allow you to write something like the following:
<pre class="example">
if (climate == CLIMATE_ARCTIC) {
replace replace_roads (1332) {
template_roads(0,0,"gfx/roads_arctic.png")
}
}
else if (climate == CLIMATE_TROPICAL) {
replace replace_roads (1332) {
template_roads(0,0,"gfx/roads_tropical.png")
}
}
else if (climate == CLIMATE_TOYLAND) {
replace replace_roads (1332) {
template_roads(0,0,"gfx/roads_toyland.png")
}
}
else { //in all other cases the climate will be temperate, so we need not test this
replace replace_roads (1332) {
template_roads(0,0,"gfx/roads_temperate.png")
}
}
</pre>

In case you want to replace sprites of the other trg*.grf or ogfx*.grf files, you have to do that in the same way as above. Furthermore you cannot use the sprite numbers of those files directly, but you need to look up the equivalent sprite numbers of trg1(r).grf or ogfx1_base.grf. In most cases you can easily find the equivalents just by comparing the type of sprites. There also used to be a calculator for this, but I cannot find that any more.

== Replace OpenTTD sprites ==
Replacing sprites that were not originally in TTD works in a similar way, but slightly different. A <code>replacenew</code> block replaces the sprites supplied by openttd.grf. The general syntax is as follows:

<pre class="pseudo">
replacenew [<identifier>] (<type> [, <image-file> [, <offset>] ] ) {
<list_of_realsprites>
}
</pre>

Instead of a sprite number you now have to specify the <code><type></code> type of sprites to replace. The available types can be looked up in the [http://newgrf-specs.tt-wiki.net/wiki/NML:Replace_new_sprites NML documentation]. There is a version of a decoded ogfxe_extra available [[:File:Ogfxe extra.png|here]] (choose to view the full resolution version below the thumbnail), with the types indicated.

For some types you need to provide exactly as much sprites as indicated in the documentation. If you don't want to provide all sprites of the type, then you're allowed to do that in most cases. This is where the <code><offset></code> comes in handy. Say you only want to replace the tenth and eleventh sprite of a certain type, then first of all you only provide two realsprites inside the block and second of all set the <code><offset></code> to in this case 9. Counting from 0, this will replace just the tenth and eleventh sprite. If there are gaps, simply use more than one <code>replacenew</code> block.

Also here you may make a climate distinction via <code>if</code>-statements, as explained above for the <code>replace</code> block. If you want to provide the filenames via the realsprites or template (like in the <code>replace</code> example above) and at the same time want to use an <code><offset></code>, then you have to specify <code><image-file></code>. As image files specified for individual realsprites or in templates take precedence, you can in this case point to a random graphics file, as long as it exists.

On the next page we'll look into an example base graphics replacement, providing both 8 bit and 32 bit sprites.

{{NMLTutorialNavbar|Road vehicle 32 bit sprites|32 bit base graphics}}

File:Ogfxe extra.png

2012-06-26T20:38:24Z

FooBar: OpenGFX extra file. Licensed GPLv2. Source: http://dev.openttdcoop.org/projects/opengfx/repository Added NML replacenew types.

OpenGFX extra file. Licensed GPLv2. Source: http://dev.openttdcoop.org/projects/opengfx/repository
Added NML replacenew types.

NMLTutorial/Base graphics replacement

2012-06-26T16:05:58Z

FooBar: intermediate save

{{NMLTutorial}}

A base graphics set provides the graphics you see when you have no NewGRFs loaded. If you don't want to add any new elements to the game, you can easily replace just these graphics via NewGRF.

There are to distinct types of base graphis: those originating from TTD and those that were added later to TTDPatch and OpenTTD. The first type is replaced by means of the <code>replace</code> block, the latter by means of the <code>replacenew</code> block. The way these blocks work are similar to the [[NMLTutorial/Spriteset and spritegroup|spriteset block]].

== Replace TTD sprites ==
And by this we mean the graphics that originally were in TTD. If you use OpenGFX, this will of course replace OpenGFX sprites and not TTD sprites. But in either case we mean replacements of the sprites in trg1(r).grf (TTD) or ogfx1_base.grf (OpenGFX). It's useful to have a decode (grfcodec) of either of those grfs available to look up the sprite numbers. If you don't have that, you can find one [[:File:Ogfx1 base.png|here]] (choose to view the full resolution version below the thumbnail).

Once you have the sprites you want to replace and know their sprite numbers, you can start writing your <code>replace</code>. The general syntax is as follows:

<pre class="pseudo">
replace [<identifier>] (<sprite-id> [, <image-file>] ) {
<list_of_realsprites>
}
</pre>

The <code><identifier></code> is something you choose yourself. It's useful to prefix it with ''replace_'' to avoid confusion with other identifiers in your code. It's optional if you only want to replace regular 8 bit sprites, but required if you also want to provide 32 bit sprites and/or sprites for different zoom levels. The <code><sprite-id></code> is the sprite number of the first sprite you want to replace. You can then place all consecutive replacement sprites in this block. As soon as there is a gap, you start a new <code>replace</code> block. The <code><image-file></code> is again optional. Like with a <code>spriteset</code> you can either provide a single filename for all sprites inside the block, or omit the filename here and specify the filename for each realsprite individually.

The <code><list_of_realsprites></code> is the same as for [[NMLTutorial/Spriteset and spritegroup|spriteset blocks]].

=== Climates other than temperate ===
The previous method will provide replacement sprites for all climates at the same time. If you want to provide different sprites for each climate, you'll have to write different <code>replace</code> blocks for each climate. Each of these climate specific blocks are guarded by <code>if</code>-statements as [[NMLTutorial/Version check|introduced earlier]]. In the <code>if</code>-statement you will test the active climate, using the <code>climate</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:General general variable]. Depending on the climate, this variable is equal to one of the following: <code>CLIMATE_TEMPERATE</code>, <code>CLIMATE_ARCTIC</code>, <code>CLIMATE_TROPICAL</code> or <code>CLIMATE_TOYLAND</code>.

This will allow you to write something like the following:
<pre class="example">
if (climate == CLIMATE_ARCTIC) {
replace replace_roads (1332 , "gfx/roads_arctic.png) {
template_roads(0,0)
}
}
else if (climate == CLIMATE_TROPICAL) {
replace replace_roads (1332 , "gfx/roads_tropical.png) {
template_roads(0,0)
}
}
else if (climate == CLIMATE_TOYLAND) {
replace replace_roads (1332 , "gfx/roads_toyland.png) {
template_roads(0,0)
}
}
else { //in all other cases the climate will be temperate, so we need not test this
replace replace_roads (1332 , "gfx/roads_temperate.png) {
template_roads(0,0)
}
}
</pre>

In case you want to replace sprites of the other trg*.grf or ogfx*.grf files, you have to do that in the same way as above. Furthermore you cannot use the sprite numbers of those files directly, but you need to look up the equivalent sprite numbers of trg1(r).grf or ogfx1_base.grf. In most cases you can easily find the equivalents just by comparing the type of sprites. There also used to be a calculator for this, but I cannot find that any more.

== Replace OpenTTD sprites ==
Replacing sprites that were not originally in TTD works in a similar way, but slightly different. A <code>replacenew</code> block replaces the sprites supplied by openttd.grf. The general syntax is as follows:

<pre class="pseudo">
replacenew [<identifier>] (<type> [, <image-file> [, <offset>] ] ) {
<list_of_realsprites>
}
</pre>

Instead of a sprite number you now have to specify the <code><type></code> type of sprites to replace. The available types can be looked up in the [http://newgrf-specs.tt-wiki.net/wiki/NML:Replace_new_sprites NML documentation].

For some types you need to provide exactly as much sprites as indicated in the documentation. If you don't want to provide all sprites of the type, then you're allowed to do that in most cases. This is where the <code><offset></code> comes in handy. Say you only want to replace the tenth and eleventh sprite of a certain type, then first of all you only provide two realsprites inside the block and second of all set the <code><offset></code> to in this case 9. Counting from 0, this will replace just the tenth and eleventh sprite. If there are gaps, simply use more than one <code>replacenew</code> block.

Also here you may make a climate distinction via <code>if</code>-statements, as explained above for the <code>replace</code> block.

{{NMLTutorialNavbar|Road vehicle 32 bit sprites|32 bit base graphics}}

NMLTutorial/Base graphics replacement

2012-06-26T15:48:52Z

FooBar: intermediate save

NMLTutorial/Base graphics replacement

2012-06-26T15:31:19Z

FooBar: intermediate save

File:Ogfx1 base.png

2012-06-26T15:09:23Z

FooBar: OpenGFX base file. Licensed GPLv2. Source: http://dev.openttdcoop.org/projects/opengfx/repository

OpenGFX base file. Licensed GPLv2.
Source: http://dev.openttdcoop.org/projects/opengfx/repository

Template:NMLTutorial

2012-06-26T14:47:14Z

FooBar: add entries for base graphics replacement

<noinclude>This is the main NML Tutorial navigation template, it is designed to be included in tutorial pages.</noinclude><div style="float:right; padding-left:12px; background:none;"><div style="width:180px; border:1px solid #2f6fab; background:#b1cff8; padding:5px; -moz-border-radius-topleft:5px; -moz-border-radius-topright:5px; font-size: 12pt;">
<center><strong><font size="3">[[NMLTutorial|NML Tutorial]]</font></strong></center>
</div>
<div style="width:180px; border:1px solid #2f6fab; border-top-width: 0px; background:#eaf6f8; padding:5px; font-size: 8pt; line-height: 12pt;">

;[[NMLTutorial/Installation|Installation]]
;[[NMLTutorial/Graphic files|Graphics files]]
;[[NMLTutorial/Language files|Language files]]
;[[NMLTutorial/NML Syntax|NML Syntax]]
;[[NMLTutorial/Starting an NML file|Starting an NML file (grf block)]]
*[[NMLTutorial/Road vehicle|Creating a road vehicle]]
;[[NMLTutorial/Item|Item blocks]]
**[[NMLTutorial/Road vehicle item definition|Item definition]]
;[[NMLTutorial/Spriteset and spritegroup|Spriteset & spritegroup blocks]]
**[[NMLTutorial/Road vehicle graphics|Adding the graphics]]
;[[NMLTutorial/Template|Template blocks]]
**[[NMLTutorial/Road vehicle graphics template|Templating the graphics]]
;[[NMLTutorial/Cargotable|Cargotable block]]
**[[NMLTutorial/Road vehicle cargo graphics|Cargo-dependent graphics]]
;[[NMLTutorial/Callback and switch|Callbacks and switch blocks]]
*[[NMLTutorial/Tram|Creating a tram]]

**[[NMLTutorial/Tram articulation|Make it articulated]]

**[[NMLTutorial/Tram graphics|Adding the graphics]]

**[[NMLTutorial/Tram purchase menu|Fix the purchase menu]]

*[[NMLTutorial/Train|Creating a train]]
;[[NMLTutorial/Railtypetable|Railtypetable block]]
**[[NMLTutorial/Train single engine|Single engine]]

**[[NMLTutorial/Train three part articulated|Three part articulated]]

**[[NMLTutorial/Train four part refit|Four part refit]]
;[[NMLTutorial/Parameters|GRF Parameters]]
**[[NMLTutorial/Train recolour|Real life recolour scheme]]

*[[NMLTutorial/Object|Creating an object]]
;[[NMLTutorial/Spritelayout|Spritelayout blocks]]
**[[NMLTutorial/Object graphics|Adding the graphics]]
;[[NMLTutorial/Version check|Version checks]]
**[[NMLTutorial/Object slopes|Objects on slopes]]
;[[NMLTutorial/32 bit sprites|32 bit sprites]]
*[[NMLTutorial/Road vehicle 32 bit sprites|Adding 32 bit sprites]]
;[[NMLTutorial/Base graphics replacement|Base graphics replacement]]
*[[NMLTutorial/32 bit base graphics|32 bit base graphics]]
;[[NMLTutorial/Conclusion|Conclusion]]
:[[NMLTutorial/Glossary|Glossary]]

</div>
<div style="width:180px; border:1px solid #2f6fab; border-top-width: 0px; background:#eaf6f8; padding:5px; font-size: 8pt; line-height: 12pt;">

;[http://newgrf-specs.tt-wiki.net/wiki/NML:Main NML Documentation]

</div>
</div>

NMLTutorial/Road vehicle cargo graphics

2012-06-26T11:25:22Z

FooBar: allow to skip ahead to 32 bit sprites section

{{NMLTutorial}}
''The example used here is from the NML source. The code for this was originally written by Terkhen and planetmaker. The graphics used in the example are by DanMack and Zephyris. 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/Road vehicle graphics template|fourth part]] of the road vehicle example. We'll add some different graphics for different cargos.

== More graphics ==
So far, our truck is rather boring, showing just a container when it's loaded regardless of the cargo it carries. NML makes it easy to supply different graphics depending the cargo the vehicle is refitted to.

Because the graphics are open source, I'll give them to you so you don't have to draw them first:

[[Image:Flatbed truck 1 copper.png|frame|none|Graphics for copper cargo (not to be confused with copper ore)]]

[[Image:Flatbed truck 1 paper.png|frame|none|Graphics for paper cargo]]

[[Image:Flatbed truck 1 steel.png|frame|none|Graphics for steel cargo]]

[[Image:Flatbed truck 1 wood.png|frame|none|Graphics for wood cargo]]

== More spritesets and spritegroups ==
Each block of sprites will need a spriteset and the empty and full states again need to be combined in a spriteset. Look [[NMLTutorial/Road vehicle graphics|back]] if you've forgotten how to do that.

The spritesets of course will use the template we made earlier. As there's nothing new to say about the spritesets and spritegroups, I'll just give them to you:

<pre style="color:darkblue; white-space: pre-wrap">
/* Define various cargo-specific graphics */

/* Paper */
spriteset(spriteset_flatbed_truck_1_paper_empty, "gfx/flatbed_truck_1_paper.png") {
tmpl_truck(0, 0)
}
spriteset(spriteset_flatbed_truck_1_paper_full, "gfx/flatbed_truck_1_paper.png") {
tmpl_truck(260, 0)
}
spritegroup spritegroup_flatbed_truck_1_paper {
loaded: [spriteset_flatbed_truck_1_paper_empty, spriteset_flatbed_truck_1_paper_full];
loading: [spriteset_flatbed_truck_1_paper_empty, spriteset_flatbed_truck_1_paper_full];
}

/* Steel */
spriteset(spriteset_flatbed_truck_1_steel_empty, "gfx/flatbed_truck_1_steel.png") {
tmpl_truck(0, 0)
}
spriteset(spriteset_flatbed_truck_1_steel_full, "gfx/flatbed_truck_1_steel.png") {
tmpl_truck(260, 0)
}
spritegroup spritegroup_flatbed_truck_1_steel {
loaded: [spriteset_flatbed_truck_1_steel_empty, spriteset_flatbed_truck_1_steel_full];
loading: [spriteset_flatbed_truck_1_steel_empty, spriteset_flatbed_truck_1_steel_full];
}

/* Wood */
spriteset(spriteset_flatbed_truck_1_wood_empty, "gfx/flatbed_truck_1_wood.png") {
tmpl_truck(0, 0)
}
spriteset(spriteset_flatbed_truck_1_wood_full, "gfx/flatbed_truck_1_wood.png") {
tmpl_truck(260, 0)
}
spritegroup spritegroup_flatbed_truck_1_wood {
loaded: [spriteset_flatbed_truck_1_wood_empty, spriteset_flatbed_truck_1_wood_full];
loading: [spriteset_flatbed_truck_1_wood_empty, spriteset_flatbed_truck_1_wood_full];
}

/* Copper */
spriteset(spriteset_flatbed_truck_1_copper_empty, "gfx/flatbed_truck_1_copper.png") {
tmpl_truck(0, 0)
}
spriteset(spriteset_flatbed_truck_1_copper_full, "gfx/flatbed_truck_1_copper.png") {
tmpl_truck(260, 0)
}
spritegroup spritegroup_flatbed_truck_1_copper {
loaded: [spriteset_flatbed_truck_1_copper_empty, spriteset_flatbed_truck_1_copper_full];
loading: [spriteset_flatbed_truck_1_copper_empty, spriteset_flatbed_truck_1_copper_full];
}
</pre>

These new spriteset and spritegroup definitions can be added to the one you already have.

You may have noticed that some of the empty vehicle graphics are the same. To reduce the filesize of the NewGRF and to limit the number of sprites ingame, it is better not to duplicate sprites if you don't have to. In this case that can be solved by removing the spritesets that define duplicate sprites. From the spritegroups, you need to change the references to removed spritesets to point to the one remaining spriteset instead. Because spritesets need to be defined before they can be referenced, this will involve some reordering of the spritesets and spritegroups. Once you have the road vehicle working with different graphics, it will be a nice challenge for you to try and remove the duplicates yourself.

== Cargotable ==
Before you can link the graphics to the vehicle and the different cargos, you need to tell NML which cargos you'll be using in your NML file. This means adding a cargotable.

First, you need to [http://newgrf-specs.tt-wiki.net/wiki/CargoTypes#Cargo_Labels look up] the labels of the cargos we have custom graphics for. For paper, steel, copper and wood these labels are <code>PAPR</code>, <code>STEL</code>, <code>COPR</code> and <code>WOOD</code> respectively.

This will give us the following cargotable:

<pre style="color:darkblue; white-space: pre-wrap">
cargotable {
PAPR, // Paper
STEL, // Steel
COPR, // Copper
WOOD, // Wood
}
</pre>

The final comma (after WOOD) isn't needed, but doesn't hurt either. The cargotable itself should go somewhere near the top of your NML file, as it needs to be defined before you can use any of the cargo labels elsewhere. Below the template definition seems a good place for it.

== Linking the graphics ==

Linking the graphics to the vehicle and a specific cargo label is easy. It is done in the graphics block of the item block of the vehicle. There you just write the label of the cargo, followed by a colon and the identifier of the spritegroup (or spriteset if you don't have a spritegroup). Finish the line with a simicolon.

This will change our graphics block into the following:

<pre style="color:darkblue; white-space: pre-wrap">
graphics {
PAPR: spritegroup_flatbed_truck_1_paper;
STEL: spritegroup_flatbed_truck_1_steel;
COPR: spritegroup_flatbed_truck_1_copper;
WOOD: spritegroup_flatbed_truck_1_wood;
default: spritegroup_flatbed_truck_1_goods; // Default to Goods.
}
</pre>

Now this truck will show different sprites when refitted to paper, steel, copper or wood. When refitted to something else, it will show the container we already had.

== The complete code ==
The complete NML file that defines this road vehicle with it's different (templated) graphics will now look like this:

<pre style="color:darkblue; white-space: pre-wrap; max-height: 200px; overflow:scroll">
//define the grf
grf {
grfid: "NML\03";
name: string(STR_GRF_NAME);
desc: string(STR_GRF_DESC);
version: 0;
min_compatible_version: 0;
}

/* Sprite template for a truck */
template tmpl_truck(x, y) {
//left_x, upper_y, width, height, offset_x, offset_y
[ 0 + x, y, 8, 18, -3, -10]
[ 16 + x, y, 20, 16, -14, -7]
[ 48 + x, y, 28, 12, -14, -6]
[ 96 + x, y, 20, 16, -6, -7]
[128 + x, y, 8, 18, -3, -10]
[144 + x, y, 20, 16, -14, -7]
[176 + x, y, 28, 12, -14, -6]
[224 + x, y, 20, 16, -6, -7]
}

/* Define a cargo translation table
* All cargo types that need any special treatment must be included here */
cargotable {
PAPR, // Paper
STEL, // Steel
COPR, // Copper
WOOD, // Wood
}

/* Define various cargo-specific graphics */

/* Paper */
spriteset(spriteset_flatbed_truck_1_paper_empty, "gfx/flatbed_truck_1_paper.png") {
tmpl_truck(0, 0)
}
spriteset(spriteset_flatbed_truck_1_paper_full, "gfx/flatbed_truck_1_paper.png") {
tmpl_truck(260, 0)
}
spritegroup spritegroup_flatbed_truck_1_paper {
loaded: [spriteset_flatbed_truck_1_paper_empty, spriteset_flatbed_truck_1_paper_full];
loading: [spriteset_flatbed_truck_1_paper_empty, spriteset_flatbed_truck_1_paper_full];
}

/* Steel */
spriteset(spriteset_flatbed_truck_1_steel_empty, "gfx/flatbed_truck_1_steel.png") {
tmpl_truck(0, 0)
}
spriteset(spriteset_flatbed_truck_1_steel_full, "gfx/flatbed_truck_1_steel.png") {
tmpl_truck(260, 0)
}
spritegroup spritegroup_flatbed_truck_1_steel {
loaded: [spriteset_flatbed_truck_1_steel_empty, spriteset_flatbed_truck_1_steel_full];
loading: [spriteset_flatbed_truck_1_steel_empty, spriteset_flatbed_truck_1_steel_full];
}

/* Wood */
spriteset(spriteset_flatbed_truck_1_wood_empty, "gfx/flatbed_truck_1_wood.png") {
tmpl_truck(0, 0)
}
spriteset(spriteset_flatbed_truck_1_wood_full, "gfx/flatbed_truck_1_wood.png") {
tmpl_truck(260, 0)
}
spritegroup spritegroup_flatbed_truck_1_wood {
loaded: [spriteset_flatbed_truck_1_wood_empty, spriteset_flatbed_truck_1_wood_full];
loading: [spriteset_flatbed_truck_1_wood_empty, spriteset_flatbed_truck_1_wood_full];
}

/* Copper */
spriteset(spriteset_flatbed_truck_1_copper_empty, "gfx/flatbed_truck_1_copper.png") {
tmpl_truck(0, 0)
}
spriteset(spriteset_flatbed_truck_1_copper_full, "gfx/flatbed_truck_1_copper.png") {
tmpl_truck(260, 0)
}
spritegroup spritegroup_flatbed_truck_1_copper {
loaded: [spriteset_flatbed_truck_1_copper_empty, spriteset_flatbed_truck_1_copper_full];
loading: [spriteset_flatbed_truck_1_copper_empty, spriteset_flatbed_truck_1_copper_full];
}

/* Goods */
spriteset(spriteset_flatbed_truck_1_goods_empty, "gfx/flatbed_truck_1_goods.png") {
tmpl_truck(0, 0)
}
spriteset(spriteset_flatbed_truck_1_goods_full, "gfx/flatbed_truck_1_goods.png") {
tmpl_truck(260, 0)
}
spritegroup spritegroup_flatbed_truck_1_goods {
loaded: [spriteset_flatbed_truck_1_goods_empty, spriteset_flatbed_truck_1_goods_full];
loading: [spriteset_flatbed_truck_1_goods_empty, spriteset_flatbed_truck_1_goods_full];
}

/* Define the road vehicle */
item(FEAT_ROADVEHS, item_flatbed_truck_1) {
property {
/* Properties common to all vehicle types */
name: string(STR_NAME_FLATBED_TRUCK_1);
climates_available: bitmask(CLIMATE_TEMPERATE, CLIMATE_ARCTIC, CLIMATE_TROPICAL);
introduction_date: date(1926,01,01);
model_life: 65;
/* retire_early not set, use default retirement behaviour */
vehicle_life: 15;
reliability_decay: 20;
refittable_cargo_classes: bitmask(CC_PIECE_GOODS, CC_EXPRESS);
non_refittable_cargo_classes: bitmask(CC_PASSENGERS, CC_REFRIGERATED);
loading_speed: 5;
cost_factor: 108;
running_cost_factor: 90;
/* cargo_age_period is left at default */

/* RV-specific properties */
sprite_id: SPRITE_ID_NEW_ROADVEH; //enable new graphics
speed: 48 km/h;
misc_flags: bitmask(ROADVEH_FLAG_2CC);
refit_cost: 0; // Refitting is free
/* callback_flags are not set, no need to manually enable callbacks */
running_cost_base: RUNNING_COST_ROADVEH;
power: 120 hp;
weight: 9.5 ton;
/* TE and air drag coefficient is left at default */
cargo_capacity: 20;
sound_effect: SOUND_BUS_START_PULL_AWAY;
/* Visual effect is left at default (no effect) */
}

/* Define graphics */
graphics {
PAPR: spritegroup_flatbed_truck_1_paper;
STEL: spritegroup_flatbed_truck_1_steel;
COPR: spritegroup_flatbed_truck_1_copper;
WOOD: spritegroup_flatbed_truck_1_wood;
default: spritegroup_flatbed_truck_1_goods; // Default to a goods container.
}
}
</pre>

This concludes our road vehicle example. If you think this was easy or not too bad, with some more practice, you'll make a great NML coder. If you think this was really difficult, you'd better give up now that you haven't spent too much time; maybe you should concentrate on graphics and leave the code to others.

For the ones brave enough to continue, we have some really nice topics in store for you. You'll learn to do some funky stuff with callbacks and switches (amonst others) and we have three more fully featured examples for you, each a little more advanced than the previous.

If you don't care about all the other fancy things you can do, but do want to add 32 bit sprites, for this time we'll allow you to skip ahead to the [[NMLTutorial/32 bit sprites|part on 32 bit sprites]]. Adding 32 bit sprites does not require any more knowledge than what you have gained now.

{{NMLTutorialNavbar|Cargotable|Callback and switch}}
<div style="text-align:center">or</div>
{{NMLTutorialNavbar|Cargotable|32 bit sprites}}

NMLTutorial/Object slopes

2012-06-26T11:20:58Z

FooBar: next part is now 32 bit sprites

{{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 Hirundo. 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/Object graphics|second part]] of the object example. In this last part we'll make the object compatible with sloped terrain as well as snow and desert terrain. For this some recent features of OpenTTD will be used, which makes this last part of the example '''incompatible with anything other than OpenTTD 1.2.0 (r22723) or higher'''.

== Version check ==
As indicated, the particular code on this page only works on OpenTTD 1.2.0 (r22723) or higher. Therefore, we want to disable this NewGRF on older versions. This is done by comparing said version number with the <code>openttd_version</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:General#General_variables variable] in an ''if statement''. To avoid having to write the version number in hex, we can use the <code>version_openttd()</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Builtin_functions function] and have NML do that for us. If the current game version is older than said version number generate a fatal [http://newgrf-specs.tt-wiki.net/wiki/NML:Error error] message, otherwise skip the error message and continue with the rest of the NewGRF:

<pre class="example">
if (version_openttd(1,2,0,22723) > openttd_version) {
error(FATAL, REQUIRES_OPENTTD, string(STR_OPENTTD_VERSION));
}
</pre>

For the error message we set that it must be <code>FATAL</code>, which means that an error message is issued and loading the NewGRF is aborted. As message we use the builtin string <code>REQUIRES_OPENTTD</code> (automatically translated by the game). This default string must be supplied with the actual version number, provided via the custom string <code>string(STR_OPENTTD_VERSION)</code>.

Due to this custom string reference, we of course also must define it in the language file (it's sufficient to only have this in the default language file):

<pre class="example">
STR_OPENTTD_VERSION :1.2.0 (r22723)
</pre>

== Sloped ground sprites ==
So far our object can only show flat ground tiles. Now we could make a spritelayout for each different slope (19) and each different view of the object (4) which would give us 76 spritelayouts. Luckily, recent versions of OpenTTD allow us to use temporary variable storage to be used inside spritelayouts, which means we can write a small piece of NML code that makes the game calculate what ground sprite to use for a given slope.

This calculation is done in a switch block, so we need to reference a different switch block from the graphics block. This new switch block in turn will reference the switch block we already have:

<pre class="example">
default: switch_fingerpost_3_object;
</pre>

The new switch block will make the calculation based on the <code>tile_slope</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Objects#Object_variables object variable] using the <code>slope_to_sprite_offset()</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Builtin_functions function]. This calculates how many sprites (the offset) after the flat ground sprite the sprite for the slope is located at. This is then stored in temporary storage register 0 using the <code>STORE_TEMP()</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Builtin_functions function].

Because we don't actually need to make a decision in this switch (it's just used to store the slope sprite offset), we only have a default value inside this switch referencing the original switch block that selected the proper spritelayout block depending on the object view:

<pre class="example">
switch (FEAT_OBJECTS, SELF, switch_fingerpost_3_object, STORE_TEMP(slope_to_sprite_offset(tile_slope), 0)) {
switch_fingerpost_3_view;
}
</pre>

Now that we have the calculation, we must actually use it in the four spritelayout blocks for the ground sprite. This means that instead of only referencing the flat ground sprite, we must add the calculated slope sprite offset to this to actually get the sprite number for the slope we want:

<pre class="example">
//south east
spritelayout spritelayout_fingerpost_3_SE {
ground {
sprite: GROUNDSPRITE_NORMAL + LOAD_TEMP(0);
}
building {
sprite: spriteset_fingerpost_3(0);
xextent: 4;
yextent: 4;
zextent: 24;
xoffset: 6; //from NE edge
yoffset: 12; //from NW edge
zoffset: 0;
}
}
</pre>

Here we take the sprite number of the flat ground sprite (<code>GROUNDSPRITE_NORMAL</code>) and add the calculated offset to this. We get this offset from the temporary storage using the <code>LOAD_TEMP()</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Builtin_functions function]. The argument <code>0</code> defines what storage register we want to get a value from. Because we stored in 0, we need to load from 0 as well.

The ground sprite for the other spritelayouts is changed in the same way. We will not give you the other spritelayout blocks here, as they need to be changed once more.

=== Purchase menu ===
Now we have a small problem with the purchase menu. The <code>tile_slope</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Objects#Object_variables object variable] isn't available there, so we cannot use the calculation for the purchase menu! This can be solved easily by not doing the calculation for the purchase menu and always have a sprite offset of 0 there (always giving the flat ground sprite). So for the purchase menu we just set the temporary storage value to 0.

First reference the purchase callback from the graphics block and link to a switch block where we will set the temporary storage:

<pre class="example">
purchase: switch_fingerpost_3_purchase;
</pre>

The switch block itself will only set temporary storage register 0 to a value of 0 and then immediately reference the switch block that makes the decision based on the object views:

<pre class="example">
switch (FEAT_OBJECTS, SELF, switch_fingerpost_3_purchase, STORE_TEMP(0, 0)) {
switch_fingerpost_3_view;
}
</pre>

Now the purchase menu works again.

== Snow and desert tiles ==
Now our object works fine on slopes, but still shows a grass tile on snow and desert tiles. Not good! This is because we always use <code>GROUNDSPRITE_NORMAL</code> as a base for the ground sprite to draw, which is the grass tile in all climates.

The solution here is to use the <code>terrain_type</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Objects#Object_variables object variable] to check what terrain we're actually building on. Now you can again have a bunch of spritelayouts for each different terrain type, but also here we can use the temporary storage to save what terrain sprite to use and retrieve this again in the spritelayouts. Let's give that a go, shall we?
* For this we will use the second storage register (with index 1).
* The default case is the normal grounds sprite, so store that in the register: <code>STORE_TEMP(GROUNDSPRITE_NORMAL, 1)</code>.
* In case of the tropic climate, we need to choose between grass and desert depending on the <code>terrain_type</code> variable. If grass, use the storage we already had, otherwise change the storage: <code>STORE_TEMP(terrain_type == TILETYPE_DESERT ? GROUNDSPRITE_DESERT : LOAD_TEMP(1), 1)</code>. What this does is store in register 1: if the terrain is desert the sprite number of the desert flat ground sprite from <code>GROUNDSPRITE_DESERT</code> and if the terrain is not desert what we already had in register 1.
* In case of the arctic climate, we need to choose between grass and snow depending on the <code>terrain_type</code> variable. If grass, use the storage we already had, otherwise change the storage: <code>STORE_TEMP(terrain_type == TILETYPE_SNOW ? GROUNDSPRITE_SNOW : LOAD_TEMP(1), 1)</code>. What this does is store in register 1: if the terrain is snow the sprite number of the snow flat ground sprite from <code>GROUNDSPRITE_SNOW</code> and if the terrain is not snow what we already had in register 1.

These three expressions need to be put somewhere in our NML file. Each expression can go in a separate switch block all linked together, but luckily we may provide an array of expressions in a single switch block. This is done by separating each command by a comma and grouping them together between straight brackets. The decision of the switch block is based on the last expression in the chain (but that is in this case not important as we only have a default return for the switch block).

Change the switch block we made earlier on this page:

<pre class="example">
switch (FEAT_OBJECTS, SELF, switch_fingerpost_3_object, [
//tile slope offset in storage register 0
STORE_TEMP(slope_to_sprite_offset(tile_slope), 0),
//terrain type in storage register 1
STORE_TEMP(GROUNDSPRITE_NORMAL, 1),
STORE_TEMP(terrain_type == TILETYPE_DESERT ? GROUNDSPRITE_DESERT : LOAD_TEMP(1), 1),
STORE_TEMP(terrain_type == TILETYPE_SNOW ? GROUNDSPRITE_SNOW : LOAD_TEMP(1), 1)
]) {
switch_fingerpost_3_view;
}
</pre>

For this new calculation to work, we must also change the spritelayout blocks. The choice of the flat ground sprite number is now stored in temporary storage register 1, so we must use this instead of the hardcoded <code>GROUNDSPRITE_NORMAL</code>. Just replace <code>GROUNDSPRITE_NORMAL</code> for the ground sprite with <code>LOAD_TEMP(1)</code> in all spritelayout blocks. If you haven't made the first change to all four spritelayout blocks, do that now all in one go:

<pre class="example">
//south east
spritelayout spritelayout_fingerpost_3_SE {
ground {
sprite: LOAD_TEMP(0) + LOAD_TEMP(1);
}
building {
sprite: spriteset_fingerpost_3(0);
xextent: 4;
yextent: 4;
zextent: 24;
xoffset: 6; //from NE edge
yoffset: 12; //from NW edge
zoffset: 0;
}
}

//south west
spritelayout spritelayout_fingerpost_3_SW {
ground {
sprite: LOAD_TEMP(0) + LOAD_TEMP(1);
}
building {
sprite: spriteset_fingerpost_3(1);
xextent: 4;
yextent: 4;
zextent: 24;
xoffset: 12; //from NE edge
yoffset: 6; //from NW edge
zoffset: 0;
}
}

//north west
spritelayout spritelayout_fingerpost_3_NW {
ground {
sprite: LOAD_TEMP(0) + LOAD_TEMP(1);
}
building {
sprite: spriteset_fingerpost_3(2);
xextent: 4;
yextent: 4;
zextent: 24;
xoffset: 6; //from NE edge
yoffset: 0; //from NW edge
zoffset: 0;
}
}

//north east
spritelayout spritelayout_fingerpost_3_NE {
ground {
sprite: LOAD_TEMP(0) + LOAD_TEMP(1);
}
building {
sprite: spriteset_fingerpost_3(3);
xextent: 4;
yextent: 4;
zextent: 24;
xoffset: 0; //from NE edge
yoffset: 6; //from NW edge
zoffset: 0;
}
}
</pre>

=== Purchase menu ===
Now we have again broken the purchase menu, because the <code>terrain_type</code> [http://newgrf-specs.tt-wiki.net/wiki/NML:Objects#Object_variables object variable] is also not available there. This can be solved easily by again not doing the calculation for the purchase menu and always have the grass terrain sprite in the purchase menu. So for the purchase menu we just set the temporary storage register 1 value to <code>GROUNDSPRITE_NORMAL</code>.

This change is similar to the change of the other switch block we just did:

<pre class="example">
switch (FEAT_OBJECTS, SELF, switch_fingerpost_3_purchase, [
//use flat gound sprite for purchase menu
STORE_TEMP(0, 0),
//use normal terrain for purchase menu
STORE_TEMP(GROUNDSPRITE_NORMAL, 1),
]) {
switch_fingerpost_3_view;
}
</pre>

So for the purchase menu we just use the flat sprite of the grass terrain. Now the purchase menu works again.

With this the end of the object example is reached. You can now encode this as a NewGRF.

== The complete code ==
If you put everything in the correct order, this will be the complete NML file:

<pre class="example small">
// define the newgrf
grf {
grfid: "\FB\FB\05\01";
name: string(STR_GRF_NAME);
desc: string(STR_GRF_DESCRIPTION);
version: 0;
min_compatible_version: 0;
}

//check OpenTTD version
//parameterized spritelayout is only supported since OpenTTD 1.2.0 r22723
if (version_openttd(1,2,0,22723) > openttd_version) {
error(FATAL, REQUIRES_OPENTTD, string(STR_OPENTTD_VERSION));
}

//templates
template template_fingerpost(x,y,filename) {
[x, y, 20, 32, -10, -28, filename]
[x+30, y, 20, 32, -10, -28, filename]
[x+60, y, 20, 32, -10, -28, filename]
[x+90, y, 20, 32, -10, -28, filename]
}

//spriteset with four directions
spriteset (spriteset_fingerpost_3) {
template_fingerpost(0,0,"gfx/dutch_fingerpost.png")
}

/* spritelayouts */

//south east
spritelayout spritelayout_fingerpost_3_SE {
ground {
sprite: LOAD_TEMP(0) + LOAD_TEMP(1);
}
building {
sprite: spriteset_fingerpost_3(0);
xextent: 4;
yextent: 4;
zextent: 24;
xoffset: 6; //from NE edge
yoffset: 12; //from NW edge
zoffset: 0;
}
}

//south west
spritelayout spritelayout_fingerpost_3_SW {
ground {
sprite: LOAD_TEMP(0) + LOAD_TEMP(1);
}
building {
sprite: spriteset_fingerpost_3(1);
xextent: 4;
yextent: 4;
zextent: 24;
xoffset: 12; //from NE edge
yoffset: 6; //from NW edge
zoffset: 0;
}
}

//north west
spritelayout spritelayout_fingerpost_3_NW {
ground {
sprite: LOAD_TEMP(0) + LOAD_TEMP(1);
}
building {
sprite: spriteset_fingerpost_3(2);
xextent: 4;
yextent: 4;
zextent: 24;
xoffset: 6; //from NE edge
yoffset: 0; //from NW edge
zoffset: 0;
}
}

//north east
spritelayout spritelayout_fingerpost_3_NE {
ground {
sprite: LOAD_TEMP(0) + LOAD_TEMP(1);
}
building {
sprite: spriteset_fingerpost_3(3);
xextent: 4;
yextent: 4;
zextent: 24;
xoffset: 0; //from NE edge
yoffset: 6; //from NW edge
zoffset: 0;
}
}

//decide spritelayout for each of the 4 views
switch (FEAT_OBJECTS, SELF, switch_fingerpost_3_view, view) {
1: spritelayout_fingerpost_3_SW;
2: spritelayout_fingerpost_3_NW;
3: spritelayout_fingerpost_3_NE;
spritelayout_fingerpost_3_SE;
}

//calculate ground sprite for object
switch (FEAT_OBJECTS, SELF, switch_fingerpost_3_object, [
//tile slope offset in storage register 0
STORE_TEMP(slope_to_sprite_offset(tile_slope), 0),
//terrain type in storage register 1
STORE_TEMP(GROUNDSPRITE_NORMAL, 1),
STORE_TEMP(terrain_type == TILETYPE_DESERT ? GROUNDSPRITE_DESERT : LOAD_TEMP(1), 1),
STORE_TEMP(terrain_type == TILETYPE_SNOW ? GROUNDSPRITE_SNOW : LOAD_TEMP(1), 1)
]) {
switch_fingerpost_3_view;
}

//calculate ground sprite for purchase menu
switch (FEAT_OBJECTS, SELF, switch_fingerpost_3_purchase, [
//use flat gound sprite for purchase menu
STORE_TEMP(0, 0),
//use normal terrain for purchase menu
STORE_TEMP(GROUNDSPRITE_NORMAL, 1),
]) {
switch_fingerpost_3_view;
}

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 {
default: switch_fingerpost_3_object;
purchase: switch_fingerpost_3_purchase;
autoslope: return(CB_RESULT_AUTOSLOPE);
additional_text: string(STR_FINGERPOST_3_PURCHASE);
}
}
</pre>

The language file will now contain:

<pre class="example small">
##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.

#error messages
STR_OPENTTD_VERSION :1.2.0 (r22723)

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

The next part of the tutorial will teach you some things about adding 32 bit sprites to your NewGRFs.

{{NMLTutorialNavbar|Version check|32 bit sprites}}

NMLTutorial/Road vehicle 32 bit sprites

2012-06-26T11:19:56Z

FooBar: finish page

{{NMLTutorial}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{NMLTutorialNavbar|32 bit sprites|Conclusion}}

NMLTutorial/Road vehicle 32 bit sprites

2012-06-26T11:08:38Z

FooBar: intermediate save

{{NMLTutorial}}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Other zoom levels ==
For each additional zoom level, you simply add additional <code>alternative_sprites</code> blocks.

{{NMLTutorialNavbar|32 bit sprites|Conclusion}}

NMLTutorial/Road vehicle 32 bit sprites

2012-06-26T10:51:07Z

FooBar: intermediate save

File:Flatbed truck 1 goods mask.png

2012-06-26T10:44:25Z

FooBar: Example graphics for NML Tutorial. Graphics by DanMack and Zephyris. License: GPL v2 and higher.

Example graphics for NML Tutorial. Graphics by DanMack and Zephyris. License: GPL v2 and higher.

File:Flatbed truck 1 goods 32.png

2012-06-26T10:34:57Z

FooBar: Example graphics for NML Tutorial. Graphics by DanMack and Zephyris. License: GPL v2 and higher.

Example graphics for NML Tutorial. Graphics by DanMack and Zephyris. License: GPL v2 and higher.

NMLTutorial/32 bit sprites

2012-06-26T09:59:43Z

FooBar: create page

{{NMLTutorial}}

As of OpenTTD 1.2.0, 32 bit graphics are to be provided via NewGRF. NML has the ability to add 32 bit sprites to your NewGRF, as well as different sprites for different zoom levels in both 8 bit and 32 bit colour depth. Here we'll focus on the most common: adding 32 bit sprites for normal, 2x zoom in and 4x zoom in.

'''Important:''' it is mandatory to provide 8 bit sprites for the normal zoom level. You cannot make NewGRFs without the 'classic' sprites. If you only have/want 32 bit sprites, this means that you have to do one of the following:
* Also draw classic 8 bit sprites for your project;
* Do a simple batch conversion from 32 bit to 8 bit in your graphics editor;
* Provide transparent 1x1 px sprites for 8 bit normal zoom.

Of course the first option is preferred, as there are always players who want to stick to 8 bit. The last option will break your NewGRF outside of 32 bit blitters, so if you don't care about 8 bit sprites you still may want to go for the second option.

32 bit sprites in NML are added via <code>alternative_sprites</code> blocks. These blocks are similar to <code>spriteset</code> blocks and generally appear right after them.

== Alternative sprites ==
Like the [[NMLTutorial/Spriteset_and_spritegroup|spriteset]], the <code>alternative_sprites</code> block defines where sprites can be found in a graphics file, how big these sprites are and what their offsets should be with respect to the ingame bounding box. In addition to the spriteset, alternative_sprites also specifies the colour depth and zoom level for this block. So if you want to provide 32 bit sprites for multiple zoom levels, you're going to need an alternative_sprites block for each of the zoom levels.

The general syntax is as follows:

<pre class="pseudo">
alternative_sprites(<identifier>, <zoom_level>, <type> [, <filename> [, <mask_filename>] ] ) {
<list_of_realsprites>
}
</pre>

* The <code><identifier></code> is the same as the identifier for the <code>spriteset</code> this block provides alternative sprites for. This way you connect the additional sprites to the classic 8 bit sprites.
*The <code><zoom_level></code> entry sets for what zoom level these sprites are intended. Most used will be <code>ZOOM_LEVEL_NORMAL</code>, <code>ZOOM_LEVEL_IN_2X</code> and <code>ZOOM_LEVEL_IN_4X</code>. See the [http://newgrf-specs.tt-wiki.net/wiki/NML:Alternative_sprites NML documentation] for other options.
* The <code><type></code> indicates if 8 bit or 32 bit sprites are provided. Use either <code>BIT_DEPTH_8BPP</code> or <code>BIT_DEPTH_32BPP</code>.
* The <code><filename></code> and <code><mask_filename></code> are optional. You either provide them here and don't specify file names for the individual realsprites in this block, or you don't provide them here and instead provide the filenames for each individual realsprite.
** The <code><filename></code> is mandatory either here or with the realsprites. Like with a spriteset, it points to the png file with the sprites.
** The <code><mask_filename></code> is optional either here or with the realsprites. It only applies to 32 bit sprites and points to an 8 bit png file containing the mask for recolouring purposes. You can leave it out if you don't want recolouring or action colours in your sprites.

=== <list_of_realsprites> ===
The <code><list_of_realsprites></code> defines the details of each actual sprite. The format is the same as for [[NMLTutorial/Spriteset_and_spritegroup|spriteset]]s:

<pre class="pseudo">
[left_x, upper_y, width, height, offset_x, offset_y]
[left_x, upper_y, width, height, offset_x, offset_y, filename]
[offset_x, offset_y]
[offset_x, offset_y, filename]
</pre>

In addition to that, the following options are available in case you want to provide a mask file with the individual 32 bit sprites:

<pre class="pseudo">
[left_x, upper_y, width, height, offset_x, offset_y, filename, mask_filename]
[offset_x, offset_y, filename, mask_filename]
</pre>

Consult the tutorial page on [[NMLTutorial/Spriteset_and_spritegroup|spriteset]] for more details on the individual bits and pieces, in case you've forgotten.

On the next page we're going to apply this new knowledge to the example road vehicle from the beginning of this tutorial.

{{NMLTutorialNavbar|Object slopes|Road vehicle 32 bit sprites}}

Template:NMLTutorial

2012-06-26T09:24:13Z

FooBar: Add entries for 32 bit sprites

<noinclude>This is the main NML Tutorial navigation template, it is designed to be included in tutorial pages.</noinclude><div style="float:right; padding-left:12px; background:none;"><div style="width:180px; border:1px solid #2f6fab; background:#b1cff8; padding:5px; -moz-border-radius-topleft:5px; -moz-border-radius-topright:5px; font-size: 12pt;">
<center><strong><font size="3">[[NMLTutorial|NML Tutorial]]</font></strong></center>
</div>
<div style="width:180px; border:1px solid #2f6fab; border-top-width: 0px; background:#eaf6f8; padding:5px; font-size: 8pt; line-height: 12pt;">

;[[NMLTutorial/Installation|Installation]]
;[[NMLTutorial/Graphic files|Graphics files]]
;[[NMLTutorial/Language files|Language files]]
;[[NMLTutorial/NML Syntax|NML Syntax]]
;[[NMLTutorial/Starting an NML file|Starting an NML file (grf block)]]
*[[NMLTutorial/Road vehicle|Creating a road vehicle]]
;[[NMLTutorial/Item|Item blocks]]
**[[NMLTutorial/Road vehicle item definition|Item definition]]
;[[NMLTutorial/Spriteset and spritegroup|Spriteset & spritegroup blocks]]
**[[NMLTutorial/Road vehicle graphics|Adding the graphics]]
;[[NMLTutorial/Template|Template blocks]]
**[[NMLTutorial/Road vehicle graphics template|Templating the graphics]]
;[[NMLTutorial/Cargotable|Cargotable block]]
**[[NMLTutorial/Road vehicle cargo graphics|Cargo-dependent graphics]]
;[[NMLTutorial/Callback and switch|Callbacks and switch blocks]]
*[[NMLTutorial/Tram|Creating a tram]]

**[[NMLTutorial/Tram articulation|Make it articulated]]

**[[NMLTutorial/Tram graphics|Adding the graphics]]

**[[NMLTutorial/Tram purchase menu|Fix the purchase menu]]

*[[NMLTutorial/Train|Creating a train]]
;[[NMLTutorial/Railtypetable|Railtypetable block]]
**[[NMLTutorial/Train single engine|Single engine]]

**[[NMLTutorial/Train three part articulated|Three part articulated]]

**[[NMLTutorial/Train four part refit|Four part refit]]
;[[NMLTutorial/Parameters|GRF Parameters]]
**[[NMLTutorial/Train recolour|Real life recolour scheme]]

*[[NMLTutorial/Object|Creating an object]]
;[[NMLTutorial/Spritelayout|Spritelayout blocks]]
**[[NMLTutorial/Object graphics|Adding the graphics]]
;[[NMLTutorial/Version check|Version checks]]
**[[NMLTutorial/Object slopes|Objects on slopes]]
;[[NMLTutorial/32 bit sprites|32 bit sprites]]
**[[NMLTutorial/Road vehicle 32 bit sprites|Adding 32 bit sprites]]
;[[NMLTutorial/Conclusion|Conclusion]]
:[[NMLTutorial/Glossary|Glossary]]

</div>
<div style="width:180px; border:1px solid #2f6fab; border-top-width: 0px; background:#eaf6f8; padding:5px; font-size: 8pt; line-height: 12pt;">

;[http://newgrf-specs.tt-wiki.net/wiki/NML:Main NML Documentation]

</div>
</div>

Dutch Town Names

2012-06-21T11:12:47Z

FooBar: add links to forum and devzone

{{DutchSets}}

[[File:Dutchtownnamesheader.png|link=Dutch Town Names|center]]

'''Dutch Town Names''' is a NewGRF that provides over 4000 real Dutch town names for use in your games.

== Downloads ==
You can get this set from the [http://www.tt-forums.net/viewtopic.php?t=51962 Forums Topic].

== Author ==
Hyronymus

== Links ==
* [http://www.tt-forums.net/viewtopic.php?t=51962 Downloads]
* [http://www.tt-forums.net/viewtopic.php?t=51962 Release Topic]
* [http://dev.openttdcoop.org/projects/dutchtowns DevZone project]

Dutch Town Names

2012-06-21T10:42:22Z

FooBar: create page

File:Dutchtownnamesheader.png

2012-06-21T10:40:09Z

FooBar:

Dutch Rail Furniture

2012-06-21T10:28:59Z

FooBar: create page

{{DutchSets}}

[[File:Dutchrailfurniturebutton.png|link=Dutch Rail Furiture|center]]

'''Dutch Rail Furnitue''' is a NewGRF that replaces the default level crossings graphics with Dutch style level crossings. Currently only OpenGFX in the three regular climates is supported. Eventually the [[Dutch Catenary]] and [[Dutch Signals]] will also move to this set.

== Downloads ==
OpenTTD users can download this set from the ingame Online Content. If you're playing TTDPatch or want to install manually, you can get the set from the [http://bundles.openttdcoop.org/dutchrailfurniture/releases/LATEST/ DevZone].

== Authors ==
* Graphics: Purno
* Code: FooBar

== Links ==
* [http://bundles.openttdcoop.org/dutchrailfurniture/releases/LATEST/ Downloads]
* [http://dev.openttdcoop.org/projects/dutchrailfurniture DevZone project]
* [http://www.tt-forums.net/viewtopic.php?t=58880 Development topic]

File:Dutchrailfurniturebutton.png

2012-06-21T10:21:28Z

FooBar:

Template:DutchSets

2012-06-20T21:40:09Z

FooBar: Add entry for Dutch Rail Furniture

<noinclude>This is the main navigation template for Dutch Set pages.</noinclude><div style="float:right; padding-left:12px; background:none;"><div style="width:180px; border:1px solid #F90; border-bottom: none; background:#C00; color:#FFF; padding:5px; -moz-border-radius-topleft:8px; -moz-border-radius-topright:8px; font-size: 12pt;">
<center><strong><font size="3">Dutch Sets</font></strong></center>
</div>
<div style="width:180px; border:1px solid #F90; border-top: none; border-bottom: none; background:#FFF; padding:5px; font-size: 8pt; line-height: 12pt;">

;Rail sets
:[[Dutch Trainset 2]]
:: [[Dutch Trainset 2/Handbook|Handbook]]
:: [[Dutch Trainset 2/Vehicles|Vehicles]]
:[[Dutch Stationset|Dutch Stations]]
:: [[Dutch Stations/Handbook|Handbook]]
:: [[Dutch Stations/Stations|Stations]]
:[[Dutch Track Set]]
:: [[Dutch Track Set/Handbook|Handbook]]
:[[Dutch Rail Furniture]]
:[[Dutch Catenary]]
:[[Dutch Signals]]

;Road sets
:[[Dutch Tram Set 2]]
:: [[Dutch Tram Set 2/Handbook|Handbook]]
:: [[Dutch Tram Set 2/Vehicles|Vehicles]]
:[[Dutch Road Furniture]]
:: [[Dutch Road Furniture/Handbook|Handbook]]
:: [[Dutch Road Furniture/Objects|Objects]]

;Other sets
:[[Dutch Town Names]]

;Deprecated sets
:[[Dutch Trainset|Dutch Trainset 1]]
:[[Dutch Trainset Cargo Extension]]
:[[Dutch Tram Set|Dutch Tram Set 1]]

</div>
<div style="width:180px; border:1px solid #F90; border-top: none; background:#009; padding:5px; font-size: 8pt; line-height: 12pt; text-align:center;">
'''[[Dutch Sets|<span style="color:#FFF">Main Page</span>]]'''
</div>
</div>
[[Category:Dutch]]

Dutch Sets

2012-06-20T21:36:39Z

FooBar: Add entry for Dutch Rail Furniture

{{DutchSets}}
__NOTOC__

Welcome to the main entry page for all Dutch NewGRFs. The menu at the right will help you navigate through the different sections with background information, screenshots and guides. The table below gives an overview of all Dutch Sets and their compatibility with OpenTTD and TTDPatch.

For some time it has been possible to replace the original graphics in Transport Tycoon Deluxe with self-made graphics. This was first accomplished by Patchman with his releases of [http://www.ttdpatch.net/ TTDPatch]. Later on things got even more exciting when [http://www.openttd.org/ OpenTTD] was released, a clone of Transport Tycoon Deluxe completely rewritten in C.

One of the first artists to develop a comprehensive graphics set to replace original game graphics was Michael Blunck. Inspired by his DBSet with German trains a group of people on the [http://www.tt-forums.net/ TT-forums] community decided it was time for a Dutch trainset. After keeping the public in suspense for quite some time version 1.0 was released on March 1st, 2009.

In the mean time other people started work on a Dutch Stationset and a Dutch Tramset. In between Purno managed to squeeze out Dutch signals and Dutch catenary. All of these graphics are available for download in NewGRF format. You will find links to the sets in the menu to the right. The tables below give a quick overview of all that we have available for you. If you're interested in the details behind each set we highly recommend you to browse through the various set's pages.

== Rail related NewGRFs ==

{| style="width:700px;margin-top:16px;"
! colspan="3" style="background-color:#C00; color:#FFF" | Dutch Trainset 2
|-
| rowspan="3" style="padding:4px;width:311px" | [[File:DTSnew3.PNG|link=Dutch Trainset 2]] || Version 2.0.0-alpha5 || Released June 20th, 2012
|-
| style="width:160px" | [[File:Openttd_icon.png|OpenTTD compatible|link=]] 1.2.0-RC1 or higher || [[ottdwiki:Online content|Online Content]] or [http://bundles.openttdcoop.org/dutchtrains/releases/LATEST/ DevZone]
|-
| [[File:Ttdpatch_icon.png|TTDPatch compatible|link=]] not compatible || -
|-
| colspan="3" style="background-color:#00C; color:#FFF" | [[Dutch Trainset 2|<span style="color:#FFF">Main page</span>]] | [[Dutch Trainset 2/Handbook|<span style="color:#FFF">Handbook</span>]] | [[Dutch Trainset 2/Vehicles|<span style="color:#FFF">Vehicles</span>]]
<div style="float:right">[http://dev.openttdcoop.org/projects/dutchtrains <span style="color:#FFF">DevZone project</span>] | [http://www.tt-forums.net/viewtopic.php?t=59353 <span style="color:#FFF">Release topic</span>] | [http://www.tt-forums.net/viewtopic.php?f=26&t=5033 <span style="color:#FFF">Development topic</span>]</div>
|}

{| style="width:700px;margin-top:16px;"
! colspan="3" style="background-color:#C00; color:#FFF" | Dutch Station Set
|-
| rowspan="3" style="padding:4px;width:311px" | [[File:Dutchstationsetbutton.png|link=Dutch Stationset]] || Version 1.0.0 || Released April 25th, 2008
|-
| style="width:160px" | [[File:Openttd_icon.png|OpenTTD compatible|link=]] compatible || [[ottdwiki:Online content|Online Content]] or [http://bundles.openttdcoop.org/dutchstations/releases/1.0.0/ DevZone]
|-
| [[File:Ttdpatch_icon.png|TTDPatch compatible|link=]] compatible || [http://bundles.openttdcoop.org/dutchstations/releases/1.0.0/ DevZone]
|-
| colspan="3" style="background-color:#00C; color:#FFF" | [[Dutch Stationset|<span style="color:#FFF">Main page</span>]] | [[Dutch Stations/Handbook|<span style="color:#FFF">Handbook</span>]] | [[Dutch Stations/Stations|<span style="color:#FFF">Stations</span>]]
<div style="float:right">[http://dev.openttdcoop.org/projects/dutchstations <span style="color:#FFF">DevZone project</span>] | [http://www.tt-forums.net/viewtopic.php?f=26&t=23638 <span style="color:#FFF">Development topic</span>]</div>
|}

{| style="width:700px;margin-top:16px;"
! colspan="3" style="background-color:#C00; color:#FFF" | Dutch Track Set
|-
| rowspan="3" style="padding:4px;width:311px" | [[File:Dutchtracksetbutton.png|link=Dutch Track Set]] || - || Not yet released
|-
| style="width:160px" | [[File:Openttd_icon.png|OpenTTD compatible|link=]] compatible || -
|-
| [[File:Ttdpatch_icon.png|TTDPatch compatible|link=]] not compatible || -
|-
| colspan="3" style="background-color:#00C; color:#FFF" | [[Dutch Track Set|<span style="color:#FFF">Main page</span>]] | [[Dutch Track Set/Handbook|<span style="color:#FFF">Handbook</span>]]
<div style="float:right">[http://dev.openttdcoop.org/projects/dutchtracks <span style="color:#FFF">DevZone project</span>] | [http://www.tt-forums.net/viewtopic.php?t=59201 <span style="color:#FFF">Development topic</span>]</div>
|}

{| style="width:700px;margin-top:16px;"
! colspan="3" style="background-color:#C00; color:#FFF" | Dutch Rail Furniture
|-
| rowspan="3" style="padding:4px;width:311px" | [[File:Dutchrailfurniturebutton.png|link=Dutch Rail Furniture]] || Version 0.1.0 || Released June 20th, 2012
|-
| style="width:160px" | [[File:Openttd_icon.png|OpenTTD compatible|link=]] 1.2.0-RC1 or higher || [[ottdwiki:Online content|Online Content]] or [http://bundles.openttdcoop.org/dutchrailfurniture/releases/LATEST/ DevZone]
|-
| [[File:Ttdpatch_icon.png|TTDPatch compatible|link=]] not compatible || -
|-
| colspan="3" style="background-color:#00C; color:#FFF" | [[Dutch Rail Furniture|<span style="color:#FFF">Main page</span>]]<div style="float:right">[http://dev.openttdcoop.org/projects/dutchrailfurniture<span style="color:#FFF">DevZone project</span>] | [http://www.tt-forums.net/viewtopic.php?t=58880 <span style="color:#FFF">Development topic</span>]</div>
|}

{| style="width:700px;margin-top:16px;"
! colspan="3" style="background-color:#C00; color:#FFF" | Dutch Catenary
|-
| rowspan="3" style="padding:4px;width:311px" | [[File:Dutchcatenarybutton.png|link=Dutch Catenary]] || Version 1.0.0 || Released April 20th, 2006
|-
| style="width:160px" | [[File:Openttd_icon.png|OpenTTD compatible|link=]] compatible || [[ottdwiki:Online content|Online Content]] or [http://bundles.openttdcoop.org/dutchrailfurniture/releases/dutchcatenary-1.0.0/ DevZone]
|-
| [[File:Ttdpatch_icon.png|TTDPatch compatible|link=]] compatible || [http://bundles.openttdcoop.org/dutchrailfurniture/releases/dutchcatenary-1.0.0/ DevZone]
|-
| colspan="3" style="background-color:#00C; color:#FFF" | [[Dutch Catenary|<span style="color:#FFF">Main page</span>]]
|}

{| style="width:700px;margin-top:16px;"
! colspan="3" style="background-color:#C00; color:#FFF" | Dutch Signals
|-
| rowspan="3" style="padding:4px;width:311px" | [[File:Dutchsignalsbutton.png|link=Dutch Signals]] || Version 1.0.0 || Released May 3rd, 2006
|-
| style="width:160px" | [[File:Openttd_icon.png|OpenTTD compatible|link=]] compatible || [[ottdwiki:Online content|Online Content]] or [http://bundles.openttdcoop.org/dutchrailfurniture/releases/dutchsignals-1.0.0/ DevZone]
|-
| [[File:Ttdpatch_icon.png|TTDPatch compatible|link=]] compatible || [http://bundles.openttdcoop.org/dutchrailfurniture/releases/dutchsignals-1.0.0/ DevZone]
|-
| colspan="3" style="background-color:#00C; color:#FFF" | [[Dutch Signals|<span style="color:#FFF">Main page</span>]]
|}

== Road related NewGRFs ==

{| style="width:700px;margin-top:16px;"
! colspan="3" style="background-color:#C00; color:#FFF" | Dutch Tram Set 2
|-
| rowspan="3" style="padding:4px;width:311px" | [[File:Dutchtramsetheader.png|link=Dutch Tram Set 2]] || Version 2.0.0 || Released January 1st, 2012
|-
| style="width:160px" | [[File:Openttd_icon.png|OpenTTD compatible|link=]] 1.2.0-beta1 or higher || [[ottdwiki:Online content|Online Content]] or [http://bundles.openttdcoop.org/dutchtramset/releases/LATEST/ DevZone]
|-
| [[File:Ttdpatch_icon.png|TTDPatch compatible|link=]] not compatible || -
|-
| colspan="3" style="background-color:#00C; color:#FFF" | [[Dutch Tram Set 2|<span style="color:#FFF">Main page</span>]] | [[Dutch Tram Set 2/Handbook|<span style="color:#FFF">Handbook</span>]] | [[Dutch Tram Set 2/Vehicles|<span style="color:#FFF">Vehicles</span>]]
<div style="float:right">[http://dev.openttdcoop.org/projects/dutchtramset <span style="color:#FFF">DevZone project</span>] | [http://www.tt-forums.net/viewtopic.php?t=45456 <span style="color:#FFF">Release topic</span>] | [http://www.tt-forums.net/viewtopic.php?t=33180 <span style="color:#FFF">Development topic</span>]</div>
|}

{| style="width:700px;margin-top:16px;"
! colspan="3" style="background-color:#C00; color:#FFF" | Dutch Road Furniture
|-
| rowspan="3" style="padding:4px;width:311px" | [[File:Dutchroadfurniturebutton.png|link=Dutch Road Furniture]] || Version 0.6.0 || Released January 19th, 2012
|-
| style="width:160px" | [[File:Openttd_icon.png|OpenTTD compatible|link=]] 1.2.0-beta4 or higher || [[ottdwiki:Online content|Online Content]] or [http://bundles.openttdcoop.org/dutchroadfurniture/releases/LATEST/ DevZone]
|-
| [[File:Ttdpatch_icon.png|TTDPatch compatible|link=]] not compatible || -
|-
| colspan="3" style="background-color:#00C; color:#FFF" | [[Dutch Road Furniture|<span style="color:#FFF">Main page</span>]] | [[Dutch Road Furniture/Handbook|<span style="color:#FFF">Handbook</span>]] | [[Dutch Road Furniture/Objects|<span style="color:#FFF">Objects</span>]]
<div style="float:right">[http://dev.openttdcoop.org/projects/dutchroadfurniture <span style="color:#FFF">DevZone project</span>] | [http://www.tt-forums.net/viewtopic.php?t=58107 <span style="color:#FFF">Release topic</span>] | [http://www.tt-forums.net/viewtopic.php?t=56316 <span style="color:#FFF">Development topic</span>]</div>
|}

== Other NewGRFs ==

{| style="width:700px;margin-top:16px;"
! colspan="3" style="background-color:#C00; color:#FFF" | Dutch Town Names
|-
| rowspan="3" style="padding:4px;width:311px" | [[File:Dutchtownnamesheader.png|link=Dutch Town Names]] || Version 1 || Released December 22nd, 2010
|-
| style="width:160px" | [[File:Openttd_icon.png|OpenTTD compatible|link=]] compatible || [http://www.tt-forums.net/viewtopic.php?t=51962 TT-Forums topic]
|-
| [[File:Ttdpatch_icon.png|TTDPatch compatible|link=]] not specified || -
|-
| colspan="3" style="background-color:#00C; color:#FFF" | [[Dutch Town Names|<span style="color:#FFF">Main page</span>]]
<div style="float:right">[http://dev.openttdcoop.org/projects/dutchtowns <span style="color:#FFF">DevZone project</span>] | [http://www.tt-forums.net/viewtopic.php?t=51962 <span style="color:#FFF">Release topic</span>]</div>
|}

== Deprecated NewGRFs ==

{| style="width:700px;margin-top:16px;"
! colspan="3" style="background-color:#C00; color:#FFF" | Dutch Trainset
|-
| rowspan="3" style="padding:4px;width:311px" | [[File:Dutchtrainsetbutton.png|link=Dutch Trainset]] || Version 1.0.0 || Released March 1st, 2009
|-
| style="width:160px" | [[File:Openttd_icon.png|OpenTTD compatible|link=]] compatible || [[ottdwiki:Online content|Online Content]] or [http://bundles.openttdcoop.org/dutchtrains/releases/1.0.0/ DevZone]
|-
| [[File:Ttdpatch_icon.png|TTDPatch compatible|link=]] compatible || [http://bundles.openttdcoop.org/dutchtrains/releases/1.0.0/ DevZone]
|-
| colspan="3" style="background-color:#00C; color:#FFF" | [[Dutch Trainset|<span style="color:#FFF">Main page</span>]] | [[Dutch Trainset/Screenshots|<span style="color:#FFF">Screenshots</span>]] | [[Dutch Trainset/Locomotives|<span style="color:#FFF">Vehicles: Locomotives</span>]] | [[Dutch Trainset/MUs|<span style="color:#FFF">Vehicles: Multiple Units</span>]] | [[Dutch Trainset/Wagons|<span style="color:#FFF">Vehicles: Coaches</span>]]
|}

{| style="width:700px;margin-top:16px;"
! colspan="3" style="background-color:#C00; color:#FFF" | Dutch Trainset Cargo Extension
|-
| rowspan="3" style="padding:4px;width:311px" | [[File:Dutchtrainsetcargoextensionbutton.png|link=Dutch Trainset Cargo Extension]] || Version 1.0.0 || Released July 20th, 2011
|-
| style="width:160px" | [[File:Openttd_icon.png|OpenTTD compatible|link=]] compatible || [[ottdwiki:Online content|Online Content]] or [http://www.tt-forums.net/viewtopic.php?t=55872 TT-Forums]
|-
| [[File:Ttdpatch_icon.png|TTDPatch compatible|link=]] not compatible || -
|-
| colspan="3" style="background-color:#00C; color:#FFF" | [[Dutch Trainset Cargo Extension|<span style="color:#FFF">Main page</span>]]
|}

{| style="width:700px;margin-top:16px;"
! colspan="3" style="background-color:#C00; color:#FFF" | Dutch Tram Set
|-
| rowspan="3" style="padding:4px;width:311px" | [[File:Dutchtramsetbutton.png|link=Dutch Tram Set]] || Version 1.0.0-RC1 || Released October 11th, 2009
|-
| style="width:160px" | [[File:Openttd_icon.png|OpenTTD compatible|link=]] compatible || [http://www.tt-forums.net/viewtopic.php?p=609644#p609644 TT-Forums]
|-
| [[File:Ttdpatch_icon.png|TTDPatch compatible|link=]] compatible || [http://www.tt-forums.net/viewtopic.php?p=609644#p609644 TT-Forums]
|-
| colspan="3" style="background-color:#00C; color:#FFF" | [[Dutch Tram Set|<span style="color:#FFF">Main page</span>]]
|}

==Links==
;Transport Tycoon (Deluxe) and OpenTTD
*[http://grfcrawler.tt-forums.net Oskar's Grfcrawler (an index of graphics sets)]
*[http://ttdpatch.de/download/ Website of Michael Blunck's graphics sets]
*[http://www.tt-forums.net THE forums to talk about Transport Tycoon Deluxe and related games]
*[http://www.ttdpatch.net Website of Josef Drexler's TTDPatch]
*[http://www.openttd.org OpenTTD, an Open Source Transport Tycoon Deluxe Clone]

;Resource websites (mostly in Dutch)
*[http://www.spoorwegmuseum.nl Website of the Dutch Railway Museum]
*[http://www.gotischeboog.com/ Website of the 'Gotische Boog' H0 module group]
*[http://home.hccnet.nl/pj.klarenbeek/nl/ns/submenu.html A site with sideviews of many Dutch rolling stock]
*[http://www.nicospilt.com/ Website of Nico Spilt, contains large amounts of images (both Dutch and foreign trains)]
*[http://www.arthurstreinenpagina.nl/ Website with many drawings of trains and a screensaver!]
*[http://www.railfaneurope.net/ The largest database of European train images]
*[http://www.modelspoormuseum.nl Website of the Dutch Model Railway Museum]
*[http://www.seinarm.nl/ Website with detailed information on MUs and wagons, as well as the Dutch signalling system]

Template:DutchSets

2012-06-03T13:22:13Z

FooBar: Add entry for Dutch Town Names

<noinclude>This is the main navigation template for Dutch Set pages.</noinclude><div style="float:right; padding-left:12px; background:none;"><div style="width:180px; border:1px solid #F90; border-bottom: none; background:#C00; color:#FFF; padding:5px; -moz-border-radius-topleft:8px; -moz-border-radius-topright:8px; font-size: 12pt;">
<center><strong><font size="3">Dutch Sets</font></strong></center>
</div>
<div style="width:180px; border:1px solid #F90; border-top: none; border-bottom: none; background:#FFF; padding:5px; font-size: 8pt; line-height: 12pt;">

;Rail sets
:[[Dutch Trainset 2]]
:: [[Dutch Trainset 2/Handbook|Handbook]]
:: [[Dutch Trainset 2/Vehicles|Vehicles]]
:[[Dutch Stationset|Dutch Stations]]
:: [[Dutch Stations/Handbook|Handbook]]
:: [[Dutch Stations/Stations|Stations]]
:[[Dutch Track Set]]
:: [[Dutch Track Set/Handbook|Handbook]]
:[[Dutch Catenary]]
:[[Dutch Signals]]

;Road sets
:[[Dutch Tram Set 2]]
:: [[Dutch Tram Set 2/Handbook|Handbook]]
:: [[Dutch Tram Set 2/Vehicles|Vehicles]]
:[[Dutch Road Furniture]]
:: [[Dutch Road Furniture/Handbook|Handbook]]
:: [[Dutch Road Furniture/Objects|Objects]]

;Other sets
:[[Dutch Town Names]]

;Deprecated sets
:[[Dutch Trainset|Dutch Trainset 1]]
:[[Dutch Trainset Cargo Extension]]
:[[Dutch Tram Set|Dutch Tram Set 1]]

</div>
<div style="width:180px; border:1px solid #F90; border-top: none; background:#009; padding:5px; font-size: 8pt; line-height: 12pt; text-align:center;">
'''[[Dutch Sets|<span style="color:#FFF">Main Page</span>]]'''
</div>
</div>
[[Category:Dutch]]

Dutch Sets

2012-06-03T13:21:15Z

FooBar: Add entry for Dutch Town Names

{{DutchSets}}
__NOTOC__

Welcome to the main entry page for all Dutch NewGRFs. The menu at the right will help you navigate through the different sections with background information, screenshots and guides. The table below gives an overview of all Dutch Sets and their compatibility with OpenTTD and TTDPatch.

For some time it has been possible to replace the original graphics in Transport Tycoon Deluxe with self-made graphics. This was first accomplished by Patchman with his releases of [http://www.ttdpatch.net/ TTDPatch]. Later on things got even more exciting when [http://www.openttd.org/ OpenTTD] was released, a clone of Transport Tycoon Deluxe completely rewritten in C.

One of the first artists to develop a comprehensive graphics set to replace original game graphics was Michael Blunck. Inspired by his DBSet with German trains a group of people on the [http://www.tt-forums.net/ TT-forums] community decided it was time for a Dutch trainset. After keeping the public in suspense for quite some time version 1.0 was released on March 1st, 2009.

In the mean time other people started work on a Dutch Stationset and a Dutch Tramset. In between Purno managed to squeeze out Dutch signals and Dutch catenary. All of these graphics are available for download in NewGRF format. You will find links to the sets in the menu to the right. The tables below give a quick overview of all that we have available for you. If you're interested in the details behind each set we highly recommend you to browse through the various set's pages.

== Rail related NewGRFs ==

{| style="width:700px;margin-top:16px;"
! colspan="3" style="background-color:#C00; color:#FFF" | Dutch Trainset 2
|-
| rowspan="3" style="padding:4px;width:311px" | [[File:DTSnew3.PNG|link=Dutch Trainset 2]] || Version 2.0.0-alpha1 || Released April 1st, 2012
|-
| style="width:160px" | [[File:Openttd_icon.png|OpenTTD compatible|link=]] 1.2.0-RC1 or higher || [[ottdwiki:Online content|Online Content]] or [http://bundles.openttdcoop.org/dutchtrains/releases/LATEST/ DevZone]
|-
| [[File:Ttdpatch_icon.png|TTDPatch compatible|link=]] not compatible || -
|-
| colspan="3" style="background-color:#00C; color:#FFF" | [[Dutch Trainset 2|<span style="color:#FFF">Main page</span>]] | [[Dutch Trainset 2/Handbook|<span style="color:#FFF">Handbook</span>]] | [[Dutch Trainset 2/Vehicles|<span style="color:#FFF">Vehicles</span>]]
<div style="float:right">[http://dev.openttdcoop.org/projects/dutchtrains <span style="color:#FFF">DevZone project</span>] | [http://www.tt-forums.net/viewtopic.php?t=59353 <span style="color:#FFF">Release topic</span>] | [http://www.tt-forums.net/viewtopic.php?f=26&t=5033 <span style="color:#FFF">Development topic</span>]</div>
|}

{| style="width:700px;margin-top:16px;"
! colspan="3" style="background-color:#C00; color:#FFF" | Dutch Station Set
|-
| rowspan="3" style="padding:4px;width:311px" | [[File:Dutchstationsetbutton.png|link=Dutch Stationset]] || Version 1.0.0 || Released April 25th, 2008
|-
| style="width:160px" | [[File:Openttd_icon.png|OpenTTD compatible|link=]] compatible || [[ottdwiki:Online content|Online Content]] or [http://bundles.openttdcoop.org/dutchstations/releases/1.0.0/ DevZone]
|-
| [[File:Ttdpatch_icon.png|TTDPatch compatible|link=]] compatible || [http://bundles.openttdcoop.org/dutchstations/releases/1.0.0/ DevZone]
|-
| colspan="3" style="background-color:#00C; color:#FFF" | [[Dutch Stationset|<span style="color:#FFF">Main page</span>]] | [[Dutch Stations/Handbook|<span style="color:#FFF">Handbook</span>]] | [[Dutch Stations/Stations|<span style="color:#FFF">Stations</span>]]
<div style="float:right">[http://dev.openttdcoop.org/projects/dutchstations <span style="color:#FFF">DevZone project</span>] | [http://www.tt-forums.net/viewtopic.php?f=26&t=23638 <span style="color:#FFF">Development topic</span>]</div>
|}

{| style="width:700px;margin-top:16px;"
! colspan="3" style="background-color:#C00; color:#FFF" | Dutch Track Set
|-
| rowspan="3" style="padding:4px;width:311px" | [[File:Dutchtracksetbutton.png|link=Dutch Track Set]] || - || Not yet released
|-
| style="width:160px" | [[File:Openttd_icon.png|OpenTTD compatible|link=]] compatible || -
|-
| [[File:Ttdpatch_icon.png|TTDPatch compatible|link=]] not compatible || -
|-
| colspan="3" style="background-color:#00C; color:#FFF" | [[Dutch Track Set|<span style="color:#FFF">Main page</span>]] | [[Dutch Track Set/Handbook|<span style="color:#FFF">Handbook</span>]]
<div style="float:right">[http://dev.openttdcoop.org/projects/dutchtracks <span style="color:#FFF">DevZone project</span>] | [http://www.tt-forums.net/viewtopic.php?t=59201 <span style="color:#FFF">Development topic</span>]</div>
|}

{| style="width:700px;margin-top:16px;"
! colspan="3" style="background-color:#C00; color:#FFF" | Dutch Catenary
|-
| rowspan="3" style="padding:4px;width:311px" | [[File:Dutchcatenarybutton.png|link=Dutch Catenary]] || Version 1.0.0 || Released April 20th, 2006
|-
| style="width:160px" | [[File:Openttd_icon.png|OpenTTD compatible|link=]] compatible || [[ottdwiki:Online content|Online Content]] or [http://bundles.openttdcoop.org/dutchrailfurniture/releases/dutchcatenary-1.0.0/ DevZone]
|-
| [[File:Ttdpatch_icon.png|TTDPatch compatible|link=]] compatible || [http://bundles.openttdcoop.org/dutchrailfurniture/releases/dutchcatenary-1.0.0/ DevZone]
|-
| colspan="3" style="background-color:#00C; color:#FFF" | [[Dutch Catenary|<span style="color:#FFF">Main page</span>]]
|}

{| style="width:700px;margin-top:16px;"
! colspan="3" style="background-color:#C00; color:#FFF" | Dutch Signals
|-
| rowspan="3" style="padding:4px;width:311px" | [[File:Dutchsignalsbutton.png|link=Dutch Signals]] || Version 1.0.0 || Released May 3rd, 2006
|-
| style="width:160px" | [[File:Openttd_icon.png|OpenTTD compatible|link=]] compatible || [[ottdwiki:Online content|Online Content]] or [http://bundles.openttdcoop.org/dutchrailfurniture/releases/dutchsignals-1.0.0/ DevZone]
|-
| [[File:Ttdpatch_icon.png|TTDPatch compatible|link=]] compatible || [http://bundles.openttdcoop.org/dutchrailfurniture/releases/dutchsignals-1.0.0/ DevZone]
|-
| colspan="3" style="background-color:#00C; color:#FFF" | [[Dutch Signals|<span style="color:#FFF">Main page</span>]]
|}

== Road related NewGRFs ==

{| style="width:700px;margin-top:16px;"
! colspan="3" style="background-color:#C00; color:#FFF" | Dutch Tram Set 2
|-
| rowspan="3" style="padding:4px;width:311px" | [[File:Dutchtramsetheader.png|link=Dutch Tram Set 2]] || Version 2.0.0 || Released January 1st, 2012
|-
| style="width:160px" | [[File:Openttd_icon.png|OpenTTD compatible|link=]] 1.2.0-beta1 or higher || [[ottdwiki:Online content|Online Content]] or [http://bundles.openttdcoop.org/dutchtramset/releases/LATEST/ DevZone]
|-
| [[File:Ttdpatch_icon.png|TTDPatch compatible|link=]] not compatible || -
|-
| colspan="3" style="background-color:#00C; color:#FFF" | [[Dutch Tram Set 2|<span style="color:#FFF">Main page</span>]] | [[Dutch Tram Set 2/Handbook|<span style="color:#FFF">Handbook</span>]] | [[Dutch Tram Set 2/Vehicles|<span style="color:#FFF">Vehicles</span>]]
<div style="float:right">[http://dev.openttdcoop.org/projects/dutchtramset <span style="color:#FFF">DevZone project</span>] | [http://www.tt-forums.net/viewtopic.php?t=45456 <span style="color:#FFF">Release topic</span>] | [http://www.tt-forums.net/viewtopic.php?t=33180 <span style="color:#FFF">Development topic</span>]</div>
|}

{| style="width:700px;margin-top:16px;"
! colspan="3" style="background-color:#C00; color:#FFF" | Dutch Road Furniture
|-
| rowspan="3" style="padding:4px;width:311px" | [[File:Dutchroadfurniturebutton.png|link=Dutch Road Furniture]] || Version 0.6.0 || Released January 19th, 2012
|-
| style="width:160px" | [[File:Openttd_icon.png|OpenTTD compatible|link=]] 1.2.0-beta4 or higher || [[ottdwiki:Online content|Online Content]] or [http://bundles.openttdcoop.org/dutchroadfurniture/releases/LATEST/ DevZone]
|-
| [[File:Ttdpatch_icon.png|TTDPatch compatible|link=]] not compatible || -
|-
| colspan="3" style="background-color:#00C; color:#FFF" | [[Dutch Road Furniture|<span style="color:#FFF">Main page</span>]] | [[Dutch Road Furniture/Handbook|<span style="color:#FFF">Handbook</span>]] | [[Dutch Road Furniture/Objects|<span style="color:#FFF">Objects</span>]]
<div style="float:right">[http://dev.openttdcoop.org/projects/dutchroadfurniture <span style="color:#FFF">DevZone project</span>] | [http://www.tt-forums.net/viewtopic.php?t=58107 <span style="color:#FFF">Release topic</span>] | [http://www.tt-forums.net/viewtopic.php?t=56316 <span style="color:#FFF">Development topic</span>]</div>
|}

== Other NewGRFs ==

{| style="width:700px;margin-top:16px;"
! colspan="3" style="background-color:#C00; color:#FFF" | Dutch Town Names
|-
| rowspan="3" style="padding:4px;width:311px" | [[File:Dutchtownnamesheader.png|link=Dutch Town Names]] || Version 1 || Released December 22nd, 2010
|-
| style="width:160px" | [[File:Openttd_icon.png|OpenTTD compatible|link=]] compatible || [http://www.tt-forums.net/viewtopic.php?t=51962 TT-Forums topic]
|-
| [[File:Ttdpatch_icon.png|TTDPatch compatible|link=]] not specified || -
|-
| colspan="3" style="background-color:#00C; color:#FFF" | [[Dutch Town Names|<span style="color:#FFF">Main page</span>]]
<div style="float:right">[http://dev.openttdcoop.org/projects/dutchtowns <span style="color:#FFF">DevZone project</span>] | [http://www.tt-forums.net/viewtopic.php?t=51962 <span style="color:#FFF">Release topic</span>]</div>
|}

== Deprecated NewGRFs ==

{| style="width:700px;margin-top:16px;"
! colspan="3" style="background-color:#C00; color:#FFF" | Dutch Trainset
|-
| rowspan="3" style="padding:4px;width:311px" | [[File:Dutchtrainsetbutton.png|link=Dutch Trainset]] || Version 1.0.0 || Released March 1st, 2009
|-
| style="width:160px" | [[File:Openttd_icon.png|OpenTTD compatible|link=]] compatible || [[ottdwiki:Online content|Online Content]] or [http://bundles.openttdcoop.org/dutchtrains/releases/1.0.0/ DevZone]
|-
| [[File:Ttdpatch_icon.png|TTDPatch compatible|link=]] compatible || [http://bundles.openttdcoop.org/dutchtrains/releases/1.0.0/ DevZone]
|-
| colspan="3" style="background-color:#00C; color:#FFF" | [[Dutch Trainset|<span style="color:#FFF">Main page</span>]] | [[Dutch Trainset/Screenshots|<span style="color:#FFF">Screenshots</span>]] | [[Dutch Trainset/Locomotives|<span style="color:#FFF">Vehicles: Locomotives</span>]] | [[Dutch Trainset/MUs|<span style="color:#FFF">Vehicles: Multiple Units</span>]] | [[Dutch Trainset/Wagons|<span style="color:#FFF">Vehicles: Coaches</span>]]
|}

{| style="width:700px;margin-top:16px;"
! colspan="3" style="background-color:#C00; color:#FFF" | Dutch Trainset Cargo Extension
|-
| rowspan="3" style="padding:4px;width:311px" | [[File:Dutchtrainsetcargoextensionbutton.png|link=Dutch Trainset Cargo Extension]] || Version 1.0.0 || Released July 20th, 2011
|-
| style="width:160px" | [[File:Openttd_icon.png|OpenTTD compatible|link=]] compatible || [[ottdwiki:Online content|Online Content]] or [http://www.tt-forums.net/viewtopic.php?t=55872 TT-Forums]
|-
| [[File:Ttdpatch_icon.png|TTDPatch compatible|link=]] not compatible || -
|-
| colspan="3" style="background-color:#00C; color:#FFF" | [[Dutch Trainset Cargo Extension|<span style="color:#FFF">Main page</span>]]
|}

{| style="width:700px;margin-top:16px;"
! colspan="3" style="background-color:#C00; color:#FFF" | Dutch Tram Set
|-
| rowspan="3" style="padding:4px;width:311px" | [[File:Dutchtramsetbutton.png|link=Dutch Tram Set]] || Version 1.0.0-RC1 || Released October 11th, 2009
|-
| style="width:160px" | [[File:Openttd_icon.png|OpenTTD compatible|link=]] compatible || [http://www.tt-forums.net/viewtopic.php?p=609644#p609644 TT-Forums]
|-
| [[File:Ttdpatch_icon.png|TTDPatch compatible|link=]] compatible || [http://www.tt-forums.net/viewtopic.php?p=609644#p609644 TT-Forums]
|-
| colspan="3" style="background-color:#00C; color:#FFF" | [[Dutch Tram Set|<span style="color:#FFF">Main page</span>]]
|}

==Links==
;Transport Tycoon (Deluxe) and OpenTTD
*[http://grfcrawler.tt-forums.net Oskar's Grfcrawler (an index of graphics sets)]
*[http://ttdpatch.de/download/ Website of Michael Blunck's graphics sets]
*[http://www.tt-forums.net THE forums to talk about Transport Tycoon Deluxe and related games]
*[http://www.ttdpatch.net Website of Josef Drexler's TTDPatch]
*[http://www.openttd.org OpenTTD, an Open Source Transport Tycoon Deluxe Clone]

;Resource websites (mostly in Dutch)
*[http://www.spoorwegmuseum.nl Website of the Dutch Railway Museum]
*[http://www.gotischeboog.com/ Website of the 'Gotische Boog' H0 module group]
*[http://home.hccnet.nl/pj.klarenbeek/nl/ns/submenu.html A site with sideviews of many Dutch rolling stock]
*[http://www.nicospilt.com/ Website of Nico Spilt, contains large amounts of images (both Dutch and foreign trains)]
*[http://www.arthurstreinenpagina.nl/ Website with many drawings of trains and a screensaver!]
*[http://www.railfaneurope.net/ The largest database of European train images]
*[http://www.modelspoormuseum.nl Website of the Dutch Model Railway Museum]
*[http://www.seinarm.nl/ Website with detailed information on MUs and wagons, as well as the Dutch signalling system]

NMLTutorial/Train recolour

2012-05-03T16:54:56Z

FooBar: use length instead of shorten_vehicle

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Add to the graphics block:

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

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

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

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

Change the current switch block:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{NMLTutorialNavbar|Parameters|Object}}

NMLTutorial/Train four part refit

2012-05-03T16:53:45Z

FooBar: use length instead of shorten_vehicle

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

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

Then we get the two switch blocks:

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

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

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

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

Now the vehicle looks good in both refits.

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

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

Add to the graphics block:

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

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

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

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

Add to the graphics block:

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

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

Reference the switch block from the graphics block:

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

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

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

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

Again, reference the switch block from the graphics block:

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

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

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

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

Again, reference the switch block from the graphics block:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

NMLTutorial/Tram purchase menu

2012-05-03T16:48:24Z

FooBar: use length instead of shorten_vehicle

{{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;
length: 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;
length: 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;
length: 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 6;
return 7;
}

//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;
length: 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

2012-05-03T16:47:29Z

FooBar: use length instead of shorten_vehicle

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

== Vehicle length 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 vehicle length callback, incidentally named <code>length</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;
length: 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 the desired length of the vehicle part, where 8 is longest possible length (32px) and 1 is the shortest possible length (4px). The first and last part of the vehicle are 28px, which equals a value of 7. The middle part is 24px, which equals a value of 6. The switch block:

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

The second vehicle part (with index 1 in <code>position_in_consist</code>) returns value 6 and a default value 7 is returned for all other positions (the first and last part of the vehicle). Counting of the vehicle parts starts at zero and you only have to list the part numbers that differ from the default you'll be specifying. 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 6;
return 7;
}

//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;
length: switch_length_htm_4001;
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/Train recolour

2012-05-03T16:39:09Z

FooBar: remove refittable_cargo_types

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Add to the graphics block:

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

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

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

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

Change the current switch block:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{{NMLTutorialNavbar|Parameters|Object}}

NMLTutorial/Train four part refit

2012-05-03T16:38:36Z

FooBar: remove refittable_cargo_types

{{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 cargo types need explicit enabling/disabling
// It's an intercity train, loading is relatively slow:
loading_speed: 6;
cost_factor: 45;
running_cost_factor: 100; // Changed by callback
sprite_id: SPRITE_ID_NEW_TRAIN;
speed: 141 km/h; // actually 140, but there are rounding errors
misc_flags: bitmask(TRAIN_FLAG_2CC, TRAIN_FLAG_MU);
refit_cost: 0; //refit costs don't apply to subcargo display
// callback flags are not set manually
track_type: ELRL; // from rail type table
ai_special_flag: AI_FLAG_PASSENGER;
power: 1260 kW; // Changed by CB
running_cost_base: RUNNING_COST_ELECTRIC;
dual_headed: 0;
cargo_capacity: 36; // per part, changed by callback
weight: 144 ton; // Total, changed by callback
ai_engine_rank: 0; // not intended to be used by the ai
engine_class: ENGINE_CLASS_ELECTRIC;
extra_power_per_wagon: 0 kW;
// 4/12 of weight on driving wheels, with a default friction coefficient of 0.3:
tractive_effort_coefficient: 0.3 / 3; // changed by callback
air_drag_coefficient: 0.06;
shorten_vehicle: SHORTEN_TO_8_8;
// Overridden by callback to disable for non-powered wagons:
visual_effect_and_powered: visual_effect_and_powered(VISUAL_EFFECT_ELECTRIC, 2, DISABLE_WAGON_POWER);
extra_weight_per_wagon: 0 ton;
bitmask_vehicle_info: 0;
}
/* Define graphics and callbacks
* Setting all callbacks is not needed, only define what is used */
graphics {
default: sw_icm_graphics;
purchase: set_icm_purchase;
cargo_subtype_text: sw_icm_cargo_subtype_text;
additional_text: return string(STR_ICM_ADDITIONAL_TEXT);
start_stop: sw_icm_start_stop;
articulated_part: sw_icm_articulated_part;
can_attach_wagon: sw_icm_can_attach_wagon;
running_cost_factor: return (cargo_subtype == 1) ? 150 : 100;
/* Capacity is per part */
cargo_capacity: return (cargo_subtype == 0) && ((position_in_consist % 4) == 2) ? 0 : 36;
/* In the purchase menu, we want to show the capacity for the three-part version,
* i.e. divide the capacity of three cars across four */
purchase_cargo_capacity: return 36 * 3 / 4;
/* 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

2012-05-03T16:37:58Z

FooBar: remove refittable_cargo_types

NMLTutorial/Train single engine

2012-05-03T16:37:28Z

FooBar: remove refittable_cargo_types

NMLTutorial/Cargotable

2012-05-03T16:33:52Z

FooBar: Information on the 'new' cargo_(dis)allow_refit properties

{{NMLTutorial}}

Whenever you want to work with specific cargos, you need to teach NML about those cargos. The reason for this is that new cargos can be invented at will, so NML doesn't keep a list of existing cargo labels and therefore you have to provide this list yourself. 

== Cargotable ==

The cargotable is the means to let NML know about the cargo labels you want to use in your NML file. An NML file can have exactly one cargotable. The cargotable needs to be defined before you reference a cargo label in your NML code.

The cargotable itself is no more than a list of cargo labels. You need to [http://newgrf-specs.tt-wiki.net/wiki/CargoTypes#Cargo_Labels look the cargo labels up] for the cargos you want to do special things with. This is what the general syntax looks like:

<pre class="pseudo">
cargotable {
<cargo_label1> [, <cargo_label2> [, <cargo_label3> ... ]]
}
</pre>

You can add as many cargo labels to the cargotable as you want/need.

=== First 32 cargo labels ===
[[File:Ttdpatch_icon.png]] When making a vehicle set for TTDPatch, the first 32 cargo labels should be selected with care. The reasons for this is that only the first 32 cargos can be used in the <code>refittable_cargo_types</code> property for vehicles. So stick cargo labels you use in that property into the cargotable first and add other cargo labels at the end.

[[File:Openttd_icon.png]] If you're using more advanced features of NewGRF that only work in OpenTTD anyways, the order of labels in the cargotable doesn't matter. For OpenTTD-only vehicle sets you should not use the <code>refittable_cargo_types</code> property, but the <code>cargo_allow_refit</code> and <code>cargo_disallow_refit</code> properties instead.

== Cargo labels or cargo classes? ==
When it comes to allowing cargos in a vehicle, you should always use cargo classes and not only cargo labels. That way your vehicle set will be compatible with cargos that don't even exist yet.

[[File:Ttdpatch_icon.png]] Use cargo labels only to deny or allow specific cargos in your vehicles that don't match the cargo classes you have set.

[[File:Openttd_icon.png]] For OpenTTD-only vehicle NewGRFs, define all known cargo labels in the <code>cargo_allow_refit</code> and <code>cargo_disallow_refit</code> properties and provide the cargo classes additionally to that for compatibility with future cargoes that haven't been invented yet.

Furthermore, industries and houses don't work with cargo classes, so there you can only use the cargo labels. Also if you want specific graphics for specific cargoes, you have to use cargo types and not cargo classes.

Now that you know about the cargotable, let's add some cargo specific graphics to our example road vehicle.

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

Save paletted image files

2012-04-16T18:14:48Z

FooBar: missed one

This pagecovers how to apply a palette to a graphics file in several graphics editor. If your editor is not listed here and you know how to work with palettes using it, please add it here.

You find a range of palettes with and without action colours (which might be useful for conversions) for various graphics programmes on the [http://dev.openttdcoop.org/documents/1 DevZone]

== Adobe Photoshop ==
[[Image:Photoshop palette window with windows ttd palette.png|thumb|50%|Fig. 1: Photoshop palette window showing in this case the Windows palette]]
[[Image:Photoshop indexed color window.png|thumb|50%|Fig. 2: Photoshop indexed color window]]

In this subsection it is explained how to create a palette file and how to apply it using Adobe Photoshop (CS5 is used here, but identical or similar procedures apply in other versions of Photoshop). It is assumed that you have a clue about working with Photoshop.

=== Retreiving a palette file ===
You can use an existing graphics file that has the correct palette applied to retrieve the palette and save it to a separate file. This palette can then be applied to graphics files that don't have a palette. You can skip this part if you have [http://dev.openttdcoop.org/attachments/1749/photoshop-ttd-dos.act downloaded a premade palette file].

# Open a graphics file of which you know it has the correct palette in Photoshop. Decoded NewGRFs (using GRFCodec) surely will have the correct palette applied.
# Go to Image > Mode > Color Table... The window from Fig. 1 will appear.
# Click Save... and store the palette file (*.act) somewhere on your computer.

=== Applying a palette from file ===
The Windows or DOS TTD palette must be applied to your graphics file for them to work in GRFCodec and NML. For the next steps we assume that you have a palette file (*.act) with the palette of your choice stored somewhere on your computer.

# Open a graphics file in Photoshop.
# Go to Image > Mode and check if RGB Color is checked. Select it if that is not the case, which will convert your graphics file to full-colour, maintaining the colours as they appear.
# Go to Image > Mode > Indexed Color... The window from Fig. 2 will appear.
# From the Palette drop-down, select Custom... The palette window (see Fig. 1) appears.
# Click Load... and browse the palette file. Click OK to close the palette window.
# In the indexed color window, you may select your choise of Dither. The dither will convert all colours that are in the graphics file but not in the palette to the palette colours. Either use the Diffusion dither (with preserving exact colors) or the Noise dither. Play around with the settings using the Preview to see the result and pick whatever looks best. If the sprites in the image file were drawn properly (using only palette colours), you should see no difference.
# Click OK to apply the palette file (and dither) to this image file. Note that this will flatten all layers (if any) in your graphics file.
# Save the file as (preferrably) a PNG image.

=== Important note on PCX files in Photoshop ===
Photoshop has a quirk in which palettes from PCX files are read and written backwards. This is no problem is you stay with pcx, but it is if you convert from pcx to png (and the other way round). Any such conversion will have the palette stored backwards in the target file, making it unusable by GRFCodec or NML. Note:
* You cannot use the palette file saved from a PCX file for a PNG file;
* You cannot use the palette file saved from a PNG file for a PCX file;
* When converting PCX <-> PNG, you must convert to RGB Color first and then back to Indexed Color, applying the palette file of your target file format (e.g. when converting to PNG, apply the palette retrieved from a PNG file).

== GIMP ==
[[Image:GIMP palette window.png|thumb|50%|Fig. 3: GIMP palette window]]
[[Image:GIMP import palette window.png|thumb|50%|Fig. 4: GIMP import pallete window showing the TTD Windows palette]]
[[Image:GIMP indexed color conversion window.png|thumb|50%|Fig. 5: GIMP indexed color conversion window]]

In this subsection it is explained how to create a palette file and how to apply it using the GNU Image Manipulation Program (2.6 is used here, but identical or similar procedures should apply in other versions). It is assumed that you have a clue about working with GIMP.

=== Download a palette file ===
In case of doubt you simply want to get the [http://dev.openttdcoop.org/attachments/1741/ttd-newgrf-dos.gpl DOS palette]. See the above link to the DevZone for more options.

=== Import a palette file ===
Before you can use a palette in GIMP you must import it. You can import a palette form a file that has the correct palette applied or import a downloaded palette (*.gpl) file.

# Open a graphics file of which you know it has the correct palette in GIMP if you want to get the palette from that file (otherwise go to the next step). Decoded NewGRFs (using GRFCodec) surely will have the correct palette applied.
# Go to Windows > Dockable Dialogs > Palettes... The window from Fig. 3 with a list of builtin palettes will appear.
# Rightclick anywhere in the list with palettes and click Import Palette... from the context menu. The window from Fig 4. will appear.
# Now choose if you want to retrieve the palette from the opened image or if you want to import a palette from a palette file.
## Select Image below Select Source to get the palette from the current image file.
## Select Palette file below Select Source and browse to a *.gpl palette file to get the palette from that file.
# The palette will be shown. Give the palette a name and click Import. The TTD palette will now be added to the list of palettes.

=== Applying a palette ===
Make sure the palette you want to use is imported in GIMP (see above).

# Open a graphics file in GIMP.
# Go to Image > Mode and check if RGB is selected. Select it if that is not the case, which will convert your graphics file to full-colour, maintaining the colours as they appear.
# Go to Image > Mode > Indexed... The window from Fig. 5 will appear.
# Select Use custom palette and then select the TTD palette from the palette list (click on the button showing a palette).
# Make sure to '''uncheck''' Remove unused colors from colormap.
# In the same window, you may select your choise of Dithering. The dither will convert all colours that are in the graphics file but not in the palette to the palette colours. Play around with the settings to find the best result. If the sprites in the image file were drawn properly (using only palette colours), you should see no difference.
# Click Convert to apply the palette (and dither) to this image file.
# Save the file as (preferrably) a PNG image.

=== Saving a palette to file ===
If you want to share your imported palette, you must have a palette file.

# Exit GIMP to automatically save your palette(s).
# Reopen GIMP (and the palette window via Windows > Dockable Dialogs > Palettes if this is closed).
# Rightclick your palette in the palette window and choose Copy Palette Location. This copies the path to the palette file to the clipboard
# With GIMP open, get the clipboard contents and browse to the specified folder (usualy ~/.gimp-2.6/palettes).
# Copy or upload the *.gpl file with the palette from there.

Surely there must be an easier way to do this, but I haven't found that so far.

[[Category:Tutorials]]

Save paletted image files

2012-04-16T18:14:28Z

FooBar: Fix: there shouldn't be a pipe in url links

This pagecovers how to apply a palette to a graphics file in several graphics editor. If your editor is not listed here and you know how to work with palettes using it, please add it here.

You find a range of palettes with and without action colours (which might be useful for conversions) for various graphics programmes on the [http://dev.openttdcoop.org/documents/1| DevZone]

== Adobe Photoshop ==
[[Image:Photoshop palette window with windows ttd palette.png|thumb|50%|Fig. 1: Photoshop palette window showing in this case the Windows palette]]
[[Image:Photoshop indexed color window.png|thumb|50%|Fig. 2: Photoshop indexed color window]]

In this subsection it is explained how to create a palette file and how to apply it using Adobe Photoshop (CS5 is used here, but identical or similar procedures apply in other versions of Photoshop). It is assumed that you have a clue about working with Photoshop.

=== Retreiving a palette file ===
You can use an existing graphics file that has the correct palette applied to retrieve the palette and save it to a separate file. This palette can then be applied to graphics files that don't have a palette. You can skip this part if you have [http://dev.openttdcoop.org/attachments/1749/photoshop-ttd-dos.act downloaded a premade palette file].

# Open a graphics file of which you know it has the correct palette in Photoshop. Decoded NewGRFs (using GRFCodec) surely will have the correct palette applied.
# Go to Image > Mode > Color Table... The window from Fig. 1 will appear.
# Click Save... and store the palette file (*.act) somewhere on your computer.

=== Applying a palette from file ===
The Windows or DOS TTD palette must be applied to your graphics file for them to work in GRFCodec and NML. For the next steps we assume that you have a palette file (*.act) with the palette of your choice stored somewhere on your computer.

# Open a graphics file in Photoshop.
# Go to Image > Mode and check if RGB Color is checked. Select it if that is not the case, which will convert your graphics file to full-colour, maintaining the colours as they appear.
# Go to Image > Mode > Indexed Color... The window from Fig. 2 will appear.
# From the Palette drop-down, select Custom... The palette window (see Fig. 1) appears.
# Click Load... and browse the palette file. Click OK to close the palette window.
# In the indexed color window, you may select your choise of Dither. The dither will convert all colours that are in the graphics file but not in the palette to the palette colours. Either use the Diffusion dither (with preserving exact colors) or the Noise dither. Play around with the settings using the Preview to see the result and pick whatever looks best. If the sprites in the image file were drawn properly (using only palette colours), you should see no difference.
# Click OK to apply the palette file (and dither) to this image file. Note that this will flatten all layers (if any) in your graphics file.
# Save the file as (preferrably) a PNG image.

=== Important note on PCX files in Photoshop ===
Photoshop has a quirk in which palettes from PCX files are read and written backwards. This is no problem is you stay with pcx, but it is if you convert from pcx to png (and the other way round). Any such conversion will have the palette stored backwards in the target file, making it unusable by GRFCodec or NML. Note:
* You cannot use the palette file saved from a PCX file for a PNG file;
* You cannot use the palette file saved from a PNG file for a PCX file;
* When converting PCX <-> PNG, you must convert to RGB Color first and then back to Indexed Color, applying the palette file of your target file format (e.g. when converting to PNG, apply the palette retrieved from a PNG file).

== GIMP ==
[[Image:GIMP palette window.png|thumb|50%|Fig. 3: GIMP palette window]]
[[Image:GIMP import palette window.png|thumb|50%|Fig. 4: GIMP import pallete window showing the TTD Windows palette]]
[[Image:GIMP indexed color conversion window.png|thumb|50%|Fig. 5: GIMP indexed color conversion window]]

In this subsection it is explained how to create a palette file and how to apply it using the GNU Image Manipulation Program (2.6 is used here, but identical or similar procedures should apply in other versions). It is assumed that you have a clue about working with GIMP.

=== Download a palette file ===
In case of doubt you simply want to get the [http://dev.openttdcoop.org/attachments/1741/ttd-newgrf-dos.gpl DOS palette]. See the above link to the DevZone for more options.

=== Import a palette file ===
Before you can use a palette in GIMP you must import it. You can import a palette form a file that has the correct palette applied or import a downloaded palette (*.gpl) file.

# Open a graphics file of which you know it has the correct palette in GIMP if you want to get the palette from that file (otherwise go to the next step). Decoded NewGRFs (using GRFCodec) surely will have the correct palette applied.
# Go to Windows > Dockable Dialogs > Palettes... The window from Fig. 3 with a list of builtin palettes will appear.
# Rightclick anywhere in the list with palettes and click Import Palette... from the context menu. The window from Fig 4. will appear.
# Now choose if you want to retrieve the palette from the opened image or if you want to import a palette from a palette file.
## Select Image below Select Source to get the palette from the current image file.
## Select Palette file below Select Source and browse to a *.gpl palette file to get the palette from that file.
# The palette will be shown. Give the palette a name and click Import. The TTD palette will now be added to the list of palettes.

=== Applying a palette ===
Make sure the palette you want to use is imported in GIMP (see above).

# Open a graphics file in GIMP.
# Go to Image > Mode and check if RGB is selected. Select it if that is not the case, which will convert your graphics file to full-colour, maintaining the colours as they appear.
# Go to Image > Mode > Indexed... The window from Fig. 5 will appear.
# Select Use custom palette and then select the TTD palette from the palette list (click on the button showing a palette).
# Make sure to '''uncheck''' Remove unused colors from colormap.
# In the same window, you may select your choise of Dithering. The dither will convert all colours that are in the graphics file but not in the palette to the palette colours. Play around with the settings to find the best result. If the sprites in the image file were drawn properly (using only palette colours), you should see no difference.
# Click Convert to apply the palette (and dither) to this image file.
# Save the file as (preferrably) a PNG image.

=== Saving a palette to file ===
If you want to share your imported palette, you must have a palette file.

# Exit GIMP to automatically save your palette(s).
# Reopen GIMP (and the palette window via Windows > Dockable Dialogs > Palettes if this is closed).
# Rightclick your palette in the palette window and choose Copy Palette Location. This copies the path to the palette file to the clipboard
# With GIMP open, get the clipboard contents and browse to the specified folder (usualy ~/.gimp-2.6/palettes).
# Copy or upload the *.gpl file with the palette from there.

Surely there must be an easier way to do this, but I haven't found that so far.

[[Category:Tutorials]]