NMLTutorial/Installation
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 commandline NML program on your operating system (MacOS description currently missing, as I don't have that, but please add it).
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 Pyton, the Python Image Library and Ply. 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 commandline 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 commandline 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 prebuilt (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 commandline 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 commandline 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 Commandline 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
- Linux
- MacOS
- Windows
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.
NML Tutorial: Installation
