TTWiki - User contributions [en-gb]

NMLTutorial/NML Syntax

2012-10-13T17:51:22Z

Hirogen2: write style

{{NMLTutorial}}

This page will be a theoretical introduction to the NML syntax. It is very well possible that you do not understand anything of what is written here. If that is the case, please read the page carefully ''once'' and then just continue with the next page which will take you on an example journey through the world of coding in NML.

If you do understand this page completely, then it is very likely that you do not need the rest of this NML tutorial and just can look up what you need in the [http://newgrf-specs.tt-wiki.net/wiki/NML:Main NML Documentation]. At your option, you can browse through the tutorial quickly or just start making your NewGRF and figure things out as you go.

== NML is a programming language ==
NFO is not a programming language: it is hex editing. NML on the other hand is a human-readable programming language and contains things like if/else statements, operators such as <code>&&</code>, <code>||</code>, <code>!=</code>, <code>>=</code> etc. and curly brackets to enclose groups of statements.

If you already know a programming language such as C++ or PHP, it is probably very easy to understand and adapt to the NML syntax. If you are new to programming, you should understand a few concepts:

=== If you are new to programming ===
; Name things the way you want
: If you define something, it is you who gives it a name. There is no set of rules how things should be called. If you want to name everything foo0001 through foo9999, that is up to you. That does not make it very easy to remember what is what, but it is not wrong per se. However, do not use any fancy symbols in names: you may use (capital) letters a through z, numbers 0 through 9 and an underscore (_). Numbers furthermore cannot be at the beginning of the name of an identifier.

; When referencing something, it needs to exist
: If you want to use a string, the string needs to exists. That probably makes as much sense to you as that a circle is round, right? But it goes further than that: if you define a vehicle and want it to use this and that graphics, the graphics need to be defined ''before'' you define the vehicle that uses it. This applies to everything; if your reference something somewhere, that something needs to exists and essentially needs to be before the reference.

; Compilers do not understand typos
: If you make a typo, the compiler (in this case nmlc) will not understand what you mean. This especially applies to the names of things we discussed earlier. If you name your vehicle definition KirbyPaulTank, then you must use the exact capitalization everywhere. For a compiler, Kirbypaultank, kirbypaultank, kirbypaulTank etc. are all completely different things. You need to pay special attention to this if you come from Windows. In Windows, there is no difference if you give a file or directory a name with or without captials; in a programming language, with or without capitals is a completely different thing and essentially a typo when not used consistently.

; Add more comments than you think is necessary
: When working on a piece of code, you easily remember what does what and why you made it the way you did. However, if you do not, look at a piece of code for a couple of months, chances are you have no clue what it does if you have not commented it. Using decent names for definitions helps a great deal towards reducing the amount of comments, but ideally every code block should have a line stating what it is for and more complicated things also get comments as you go. If you do certain things differently for a reason, state ''why'' you did that. If you work with more people on one project, comments are vital in helping fellow developers understand why you did what.

== NML structure: blocks ==
NML files are mainly composed from blocks. A block starts with the type of the block, optional arguments and then the contents enclosed by curly braces. Some blocks are supplied with an identifier (''a name'') as argument, some with even more arguments and some are only referenced by their type. The basic block syntax is as follows:

<pre class="pseudo">
type {
<block_contents>
}
</pre>
or
<pre class="pseudo">
type <identifier> {
<block_contents>
}
</pre>
or
<pre class="pseudo">
type (<identifier>, <argument1>, [<argument2> [,...]] {
<block_contents>
}
</pre>
''Note: the identifier is not necessarily the first argument of a block in case of multiple arguments.''

When a block syntax is explained in the tutorial, some arguments may be optional. These are written between [ straight/square brackets ]. These brackets indicate that something is optional; the brackets are not part of the actual NML code. <code>[,...]</code> means that you can have any number of arguments of the same type as the previous argument. Things between < pointy/angular brackets > must be replaced with actual content. What this content must be is explained directly after the introduction of the block's syntax. Also, pointy brackets are not part of actual NML code. Round and curly brackets are part of the NML code and must be written as indicated. Words or text not between pointy brackets is also part of the NML code and must appear as indicated.

Currently, the following block types exist:
<div style="float:left">
* grf
* item
* recolour_sprite
* template
* spriteset
* spritegroup
* spritelayout
* tilelayout
</div><div style="float:left">
* switch
* produce
* random_switch
* cargotable
* railtypetable
* error
* disable_item
* deactivate
</div><div style="float:left">
* engine_override
* replace
* replacenew
* font_glpyh
* alt_sprites
* town_names
* snowline
* basecost
</div><div style="clear:left"></div>

Some special "blocks", which are not really blocks, but language constructs, exist as well:
* if
* else

Furthermore, there are too many [http://newgrf-specs.tt-wiki.net/wiki/NML:Builtin_functions functions] to list here. For now, you can forget these if you want, but it is good to have seen their names.

The blocks define things that can be referenced or make new things available in the game. Some blocks can contain sub-blocks. The <code>grf</code> block can contain a <code>param</code> subblock to add parameter settings. The <code>item</code> block can contain <code>property</code>, <code>graphics</code> and <code>livery_override</code> subblocks.

If you need to do some calculations, you do those outside the blocks, or in some special cases, in a block's ''expression'' argument, but never inside a block. <code>if</code>s and <code>else</code>s also have no place inside blocks and can only be used outside them.

=== Identifiers ===
As you have read earlier, some blocks need to have an ''identifier''. You can see this identifier as a name for the block and you choose this identifier yourself.

'''All identifiers need to be unique throughout you NML file!''' This even applies for identifiers of totally different blocks. An easy method to avoid duplicate identifiers is to precede the identifier name with the name of the block type. While this is not foolproof, it simply reduces the chances for duplicates. It is also a good idea to add the name of the item (vehicle, object, etc.) an identifier belongs to to the name of the identifier.

With both the block name and item name in the identifier, you can also see quickly from the identifier what this is for, without having to write that down somewhere seperately.

== Features ==
Some blocks can do multiple things. For example, the <code>item</code> can define a train, but also a road vehicle, ship, or aircraft. In case of such a block, you need to set which ''feature'' the block is for and supply this to the block as an argument. Below is a table of available features:

{| class="t"
! Name
! Description
|-
| FEAT_TRAINS
| Trains
|-
| FEAT_ROADVEHS
| Road vehicles
|-
| FEAT_SHIPS
| Ships
|-
| FEAT_AIRCRAFT
| Aircraft
|-
| FEAT_STATIONS
| Train stations
|-
| FEAT_CANALS
| Canals
|-
| FEAT_BRIDGES
| Bridges
|-
| FEAT_HOUSES
| Town houses
|-
| FEAT_GLOBALVARS
| Various global variables
|-
| FEAT_INDUSTRYTILES
| Industry tiles (visible part of industries)
|-
| FEAT_INDUSTRIES
| Industries
|-
| FEAT_CARGOS
| Cargo types
|-
| FEAT_SOUNDEFFECTS
| Sound effects
|-
| FEAT_AIRPORTS
| Airports
|-
| FEAT_SIGNALS
| Train signals
|-
| FEAT_OBJECTS
| Non-interactive objects (example: lighthouse)
|-
| FEAT_RAILTYPES
| Rail types
|-
| FEAT_AIRPORTTILES
| Airport tiles (visible part of airports)
|}

== Comments ==
As said before, it is useful to add comments to your NML code to indicate what things are for.

Comments can be written as comment block or as inline comment. Comment blocks go between different lines of NML code, while inline comments can also go there as well as at the end of each line.

Comment block example:

<pre style="color:darkblue">
/*
This is a comment block, it starts with a slash and an asterisk.
It can span multiple lines
Before it ends with an asterisk and a slash
*/
</pre>

Inline comment example:

<pre style="color:darkblue">
// An inline comment is preceded by two slashes
// If you need multiple lines, each line gets two slashes in front

grf {
name: string(STR_GRF_NAME); // it can also go at the end of a line

}
</pre>

== Conclusion ==
Yes, that is a bunch of stuff with little hands-on examples, but I warned you about that. You will find (most of) these different blocks explained in the remainder of this tutorial. And, of course, how every block should be written is clearly documented in the [http://newgrf-specs.tt-wiki.net/wiki/NML:Block_syntax block syntax] chapter of the NML Documentation.

{{NMLTutorialNavbar|Language files|Starting an NML file}}

NMLTutorial/Language files

2012-10-13T17:41:21Z

Hirogen2: write style

{{NMLTutorial}}

All texts (or ''strings'') you want or need to use in a NewGRF go into a language file. Each language has its own language file, which makes translations in NML very easy.

== Language folder structure ==
Of course you want to keep all the source files for one NewGRF together in one directory, right? In this directory, create a subdirectory with the name <code>lang</code>. This is the default directory name NML looks in for language files. You can use a different name if you want to, but then you need to teach NML this name.

=== File extensions ===
Every language file needs to have the <code>.lng</code> file extension, otherwise NML will not recognise them.

=== Default language ===
You need to have exactly one default language for your NewGRF project. This language will be used if the user selects a language not available in the NewGRF, or if some translation is not complete. The default default language is ''english.lng''. If that is fine with you, you do not have to make any other settings. If you want a different default language, you need to tell NML which one this is; see the [[NMLTutorial/Installation#NML_Commandline_Options|installation page]] on which commandline option to supply to do this.

=== Example directory structure ===
As a result, your directory structure should look something like the following:

mygrf
\_ lang
| \_ english.lng
| \_ other_language.lng
\_ mygrf.nml (which we will create later)

== Language file structure ==
The contents of each language file itself has the following structure:

<pre class="pseudo">
##grflangid <number>
<string-name> :<text>
<string-name> :<text>
...
</pre>

<code><number></code> is the number of the language in this file. You can look these numbers up [http://newgrf-specs.tt-wiki.net/wiki/NML:Language_files here]. This number needs to be written with the hexadecimal prefix <code>0x</code>. For example, the language number for British English is 01, so as <code><number></code> you need to put <code>0x01</code>. Dutch has 1F as language number, so in case of <code>dutch.lng</code>, you put <code>0x1F</code>.

=== String names ===
Each piece of text, a string, needs to have a unique <code><string-name></code>. For this, you can choose whatever you want, but it is common practice to start each string name with STR_ and write it completely in capitals. That way, you do not get duplicates with other names you will be using in your NML file, and the captitals make the code a little bit easier to read.

Every new string name will start on a new line in the language file.

=== Texts ===
The text, or strings, themselves are written directly behind the string name, both completely on a single line. The string name and the string are separated by a colon. If you want to align the strings, you can do that by adding spaces of tabs ''in front of'' the colon. If you add them behind the colon, this whitespace will be part of the string!

=== String codes ===
You can use some special string codes inside strings, for instance, to instruct the game to continue the string on a new line, to use colours in your string, or to do some special things with strings. The formatting for these string codes is the same as [http://wiki.openttd.org/Strings used by OpenTTD]. However, not all string codes are available in all locations where strings are displayed. Colours and special characters are generally available anywhere; other things you will just have to try and see.

=== ASCII or Unicode ===
When saving the language file, you should pay a little attention to the character encoding you use. If you only use ISO8859-1 or -15 (Latin-1/-15) characters in your language file, you can save as both ASCII and UTF-8 (one of many Unicode encodings). If you use non-Latin characters, such as for Cyrillic, Arabic or Asian languages, you must save as UTF-8.

=== Comments in language files ===
If you want to add comments in language files to make some notes in it that are not string definitions, start the line with the comment with a hash tag (#). Then you can write anything you want on that line and it will not be interpreted by NML.

=== Example language file ===
An example english.lng could contain the following:

<pre style="color:darkblue">
##grflangid 0x01
# This is the English language file

# GRF name and description definitions
STR_GRF_NAME :My GRF 0.1.0
STR_GRF_DESCRIPTION :My GRF is the best there is and makes all other grfs obsolete!{}{COPYRIGHT}2011 Derp{}License: GPL v2

# vehicle names
STR_NAME_MYVEHICLE :General Robotics Anti-Grav UFO Mark X
</pre>

Note the string codes for a new line {} and the copyright symbol in the GRF description.

== Custom string codes ==
For things such as a version number, it is useful to define a custom string code. That way, you do not have to go and update the version number in every language file whenever you make a new release. You can also use it for the GRF title and basically anything you want, but these are the most useful applications.

Custom string codes go in a file called <code>custom_tags.txt</code> which resides outside the ''lang'' directory, next to your nml file:

mygrf
\_ lang
| \_ english.lng
| \_ other_language.lng
\_ custom_tags.txt
\_ mygrf.nml

The format of <code>custom_tags.txt</code> is similar to a language file, but does not have the <code>##grflangid</code> definition, for example:

<pre style="color:darkblue">
VERSION :0.1.0
TITLE :My GRF
</pre>

The same rules for character encoding apply, and once you have this, you can change your language file into something like the following:

<pre style="color:darkblue">
##grflangid 0x01
# This is the English language file

# GRF name and description definitions
STR_GRF_NAME :{TITLE} {VERSION}
STR_GRF_DESCRIPTION :{TITLE} is the best there is and makes all other grfs obsolete!{}{COPYRIGHT}2011 Derp{}License: GPL v2

# vehicle names
STR_NAME_MYVEHICLE :General Robotics Anti-Grav UFO Mark X
</pre>

The Dutch language file for example then can use these same custom sting codes:

<pre style="color:darkblue">
##grflangid 0x1F
# This is the Dutch language file

# GRF name and description definitions
STR_GRF_NAME :{TITLE} {VERSION} - Mijn GRF
STR_GRF_DESCRIPTION :Mijn GRF is de beste die er is en maakt alle andere grfs overbodig!{}{COPYRIGHT}2011 Derp{}Licentie: GPL v2

# we will use the English vehicle name as well for Dutch, and don't re-define it here.
</pre>

Now you know how to create language files, where they need to go and what you should put into them. Go ahead and create the default (English) language file and a language file for your own language (if English is your own language, then stick with the one default file). Add a name and description for the NewGRF you want to make and use <code>custom_tags.txt</code> where it is useful.

Got that? Great! Now there is only one step left before you are going to create your actual NML file!

{{NMLTutorialNavbar|Graphic files|NML Syntax}}

NMLTutorial/Graphic files

2012-10-13T17:34:10Z

Hirogen2: wr style

{{NMLTutorial}}

You can use any graphics file format as long as it is supported by the [http://www.pythonware.com/products/pil/ Python Image Library] and as long the graphics file has one of the TTD palettes applied.

== What image files should I use? ==
If you are unsure about what file format to use, take PNG as a safe bet. It can work with palettes and has the added advantage that it can be viewed by browsers and as such, you can just upload your sprite files to the forums if you want to show them. PNG files are also widely supported by graphics editors.

== What is this palette business? ==
Graphics for TTD can only use a limited set of colours (OpenTTD 32bpp graphics are an exception to this; while NML can handle these for you, it is not covered in this tutorial). Check the NewGRF Specs for [http://newgrf-specs.tt-wiki.net/wiki/PalettesAndCoordinates#Palettes what these palettes are] and which colours are available to use. The DOS palette has a few more colours, so if you are still in the position to choose, go for that.

In theory, you can draw in true colour (24 or 32 bpp) and then convert your result to the TTD palette, but that usually does not work out too well. It is best to only use the colours from the palette in the first place. Each sprite should get a blue background, for which you use the blue from index 0 (indicated as "Transparent" on the page of the link above, or hex colour #0000FF).

Make sure to actually save the graphics files with a palette applied, or NML will complain that you do not have one. If you do not have this palette, you can extract it from any decoded GRF file or [http://newgrf-specs.tt-wiki.net/wiki/NML:Graphic_files download] a premade palette file.

See [[Save paletted image files]] for how to create image files with the correct pallete applied.

== How do I draw sprites? ==
This tutorial is not about drawing, but about coding once you have drawn. If you want to learn how to draw sprites, check the [[GraphicsTutorial]].

{{NMLTutorialNavbar|Installation|Language files}}

NMLTutorial/Installation

2012-10-13T17:32:32Z

Hirogen2: write style

{{NMLTutorial}}

NML is written in Python and therefore can be made to run on every operating system that can run Python. This includes the popular operating sytems Linux, Mac OS X and Windows. Below you will find a description on how to install NML and how to use the command-line NML program on your operating system.

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

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

=== Installing NML ===
For Linux users, there are several ways to get NML. If you have Python 2.7, you can get it as precompiled binary. Otherwise you should be able to compile NML without too much effort. Pick the method of your choice below.

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

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

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

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

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

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

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

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

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

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

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

== Mac OS X ==
For Mac OS X, you are currently required to compile NML yourself, as there are no precompiled binaries available.

=== Installing NML ===
Please add a detailed explanation if you know how to do this.

=== Using NML ===
Please add a detailed explanation if you know how to do this.

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

=== Installing NML ===
Go to http://bundles.openttdcoop.org/nml/nightlies/LATEST/ and download nml-rXXXX-windows-win32.zip, replacing XXXX with the actual version number of the package. The ZIP file contains a number of files that all need to stay together. Where these files go depends on whether you want to take the easy route or do it properly.

==== Easy route ====
The easy route is to extract all the NML program files in the same directory as your NML project (where your file with the NML code and the directories with language and graphics files will go later). With this, you can use the NML program for this project alone. If you want to work on multiple NewGRF projects coded in NML, you need to copy the NML program files to each of these project directories.

==== Proper route ====
If you want to run NML from any directory, you need to add the directory containing the nmlc.exe executable (and related files) to your PATH environment variable. This can break Windows if you do not do it correctly, so follow the instructions carefully. The instructions have been written for Windows 7 and may differ slightly on other Windows versions.

First, extract the NML program files to a directory of your choice, e.g. C:\tools\NML. It is preferred that you do not have spaces in the directory path, so avoid the "Program Files" directory. Once you have that, remember the directory path and follow these steps carefully:
# Rightclick "Computer" on the desktop or in the Start menu and select ''Properties''. This will open the System window from the Configuration Panel.
# Click ''Advanced system settings'' in the left pane. This will open the System Properties window.
# Click the ''Advanced'' tab.
# On the Advanced tab, click the ''Environment Variables...'' button. This will open the Environment Variables window.
# In the bottom half of the window below System variables, find the ''Path'' entry and select it.
# With the Path entry selected, click the ''Edit...'' button. An edit box will appear.
# '''Do not touch the Variable name and do not remove anything from the Variable value!''' (This is where you can break your computer.)
# Put your cursor at the end of the ''Variable name'' box and type a semicolon followed by the directory path to the NML program, in this case <code>;C:\tools\NML</code>
# Confirm your changes by clicking the ''OK'' button in each of the three windows.

Now you can use the NML program from any directory on your computer.

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

Next, you need to change directory to the project folder which has your NML (code) file in it. Then run the nmlc program to compile your GRF. For example:

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

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

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

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

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

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

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

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

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

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

{{NMLTutorialNavbar||Graphic files}}