NMLTutorial/Installation

NML Tutorial

Installation

Graphics files

Language files

NML Syntax

Starting an NML file (grf block)

• Creating a road vehicle

Item blocks

• • Item definition

Spriteset & spritegroup blocks

• • Adding the graphics

Template blocks

• • Templating the graphics

Cargotable block

• • Cargo-dependent graphics

Callbacks and switch blocks

• Creating a tram

• • Make it articulated

• • Adding the graphics

• • Fix the purchase menu

• Creating a train

Railtypetable block

• • Single engine

• • Three part articulated

• • Four part refit

GRF Parameters

• • Real life recolour scheme

• Creating an object

Spritelayout blocks

• • Adding the graphics

Version checks

• • Objects on slopes

32 bit sprites

• Adding 32 bit sprites

Base graphics replacement

• 32 bit base graphics

Conclusion

Glossary

NML Documentation

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 http://bundles.openttdcoop.org/nml/nightlies/LATEST/rpms/nml-rXXXX-suseYYYY.noarch.rpm

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 exit 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 (hg clone http://hg.openttdcoop.org/nml).

Also, this time, you need the terminal as superuser. Then change directory to the (extracted) NML source and run python setup.py install. 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 nmlc and the general usage is nmlc [options] <filename>. First, change directory to the directory which has your nml file. Then run the nmlc program to compile your GRF. For example:

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

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

All command-line options available to NML are available via the nmlc -h command and are also 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

Make sure you have python version 3.4 or higher and pip installed, as well as Setuptools.

After that, run these commands:

pip3 install ply
pip3 install Pillow
pip3 install nml

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 by pressing CMD+Space to open Spotlight, and searching for "Terminal".

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:

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

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

Windows

NML is available as pre-built (64-bit) Windows executable from Github, so there is no need to compile it yourself.

Installing NML

Go to https://github.com/OpenTTD/nml/releases to find the latest release, click on assets and download nml-standalone-XXXX-win64.zip , replacing XXXX with the actual version number of the package. The ZIP file contains a number of files. 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 the NML program file 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 file 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 to your PATH environment variable. This can break Windows if you do not do it correctly, so follow the instructions carefully.

First, extract the NML program file 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:

Windows 7 or earlier:

1. Rightclick "Computer" on the desktop or in the Start menu and select Properties. This will open the System window from the Configuration Panel.
2. Click Advanced system settings in the left pane. This will open the System Properties window.
3. Click the Advanced tab.
4. On the Advanced tab, click the Environment Variables... button. This will open the Environment Variables window.
5. In the bottom half of the window below System variables, find the Path entry and select it.
6. With the Path entry selected, click the Edit... button. An edit box will appear.
7. Do not touch the Variable name and do not remove anything from the Variable value! (This is where you can break your computer.)
8. Put your cursor at the end of the Variable value box and type a semicolon followed by the directory path to the NML program, in this case ;C:\tools\NML
9. Confirm your changes by clicking the OK button in each of the three windows.

Windows 8 and up:

1. Either locate, or type "env" into the search bar, and click on 'Edit system environment variables'.
2. On the Advanced tab, click the Environment Variables... button. This will open the Environment Variables window.
3. In the bottom half of the window below System variables, find the Path entry and select it.
4. With the Path entry selected, click the Edit... button. An edit box will appear.
5. Click New and type in the path to your NML program, in the example case C:\tools\NML
6. Do not edit or remove any of the existing entries!
7. 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 cmd 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 D:\grfs\mygrf\mygrf.nml into the GRF file D:\grfs\mygrf\mygrf.grf. The -c option is not mandatory, but crops extraneous blue from sprites, reducing the filesize of the grf file. Note that if you have any spaces in a directory or file name, you need to enclose that complete path or filename in double quotes, e.g.: cd "D:\Users\Username\My Documents\mygrf". It is therefore recommended not to have any spaces.

All command-line options available to NML are available via the nmlc -h command and are also 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

• Geany
• VS Code

Linux

• Kate, vim

MacOS

• XCode

Windows

• Notepad++
• Sublime Text

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 VS Code, Notepad++ and Geany. If you want to create your own syntax highlighter, there is a script available as well that will help you create the keyword lists.

« NMLTutorial main page

NML Tutorial: Installation

Graphic files »