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'll 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're looking to compiling NML yourself, you also need the Python Setuptools. Note that NML currently only runs on Python 2.5 through 2.7, but not 3.x. Look for the following in your package manager:

• python (you might already have this)
• python-imaging (pil)
• python-ply
• python-setuptools

Installing NML

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 don't forget to exit sudo again, preventing yourself from doing stupid things from this point.

Compiling NML yourself

The other option to get NML is to compile it yourself. First you need to get the source from http://bundles.openttdcoop.org/nml/nightlies/LATEST/ or via Mercurial checkout from http://hg.openttdcoop.org/nml (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 doesn't have a GUI; much like GRFCodec in fact. That means you need to run it from a terminal window. The NML program itself is called 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're 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's files in the same directory as your NML project (where later your file with the NML code and the directories with language and graphics files will go). 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's 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 don't 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 don't 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:

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. Don't touch the Variable name and don't remove anything from the Variable value!!! (This is where you can break your computer).
8. 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 ;C:\tools\NML
9. 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 doesn't have a GUI; much like GRFCodec in fact. That means you need to run it from a command prompt window. You can start the command prompt from Start > Programs > Accessories > Command Prompt. Or by entering 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 folder 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

Linux

• Kate

MacOS

• XCode

Windows

• Notepad++

If you use an editor which you think is quite good and not listed here, you're 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 Notepad++ and Geany. If you want to create your own syntax highlighter, there's a script available as well that will help you create the keyword lists.

« NMLTutorial main page

NML Tutorial: Installation

Graphic files »