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, MacOS 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 (MacOS description currently missing, as I don't have that, but please add it).

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

Linux

NML requires 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 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.

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, so extract the zip file entirely into a single folder, for example D:\grfs\nml.

If you leave it at this, you can already start to use NML, but only from that folder. This makes compiling grfs a bit more difficult as you have to write full paths when encoding a grf file. If you want to run NML from any directory, you need to add the directory containing the nmlc.exe executable to your PATH environment variable. As this can break Windows if you don't do this properly, we'll not be explaining this here and go for the long route instead. You're of course free to change your PATH yourself; if you do, you're probably also smart enough to know how to change the commands as explained in the section below.

Using NML

As said before, NML is a 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 folder where you have nmlc.exe in. Then you can run NML from there. For the example below we'll be assuming the following:

• nmlc.exe and related files are in D:\grfs\nml
• The nml file you want to encode is D:\grfs\mygrf\mygrf.nml
• The grf file to be created needs to go into D:\grfs\mygrf\mygrf.grf

From the command prompt you can now run the following commands, one at a time, confirm with Enter after each line:

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

This will encode the nml file D:\grfs\mygrf\mygrf.nml into the grf file D:\grfs\mygrf\mygrf.grf. The -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 the complete path in double quotes, e.g.: nmlc -c --grf "D:\grfs\my grf\mygrf.grf" "D:\grfs\mgrf\mygrf.nml". 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 »