NML:Getting started

From GRFSpecs
Revision as of 20:30, 1 February 2012 by Andythenorth (talk | contribs)
Jump to navigationJump to search

NML is a a python-based compiler, capable to compile NML files (along with their associated language, sound and graphic files) into grf and / or nfo files. Windows users can install the windows binary which contains a binary which bundles all required libraries. Users on other OS need to install them separately, best by means of their packet manager. In order to work, the following items are required:

If you don't install these with the packet manager of your choice (or there is none like on windows and you don't use the pre-compiled binary file), you should install these libraries as well as NML itself using python setup.py install from your command prompt.

OS X users: do not use PIL and PLY from Macports. They may not work properly. Install from downloads using the links above. Follow the instructions in the PIL readme carefully, it is prone to failing if you don't. You'll need GCC to build PIL, it's part of Apple developer tools on your OS X install DVD.

To verify that everything is installed, enter nmlc --version in your command line. This should output the version of NML as well as the version of the installed libraries.

Examples for small NML "projects" are found in the examples and regression folder of NML. Generally it's assumed that the language files are in a separate language folder lang, thus a simple project may look like this:

mynewgrf.nml
graphics.png
funny_sound.wav

lang/english.lng

The compiler itself nmlc is a command line tool and can take a number of parameters, at least the nml filename which it shall process, e.g. nmlc mynewgrf.nml will compile your nml file into the grf-file mynewgrf.grf.

The full syntax is:

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>
 -M                    output a rule suitable for make describing the
                       graphics dependencies of the main grf file (requires
                       input file or --grf)
 --MF=<file>           When used with -M, specifies a file to write the
                       dependencies to
 --MT=<file>           target of the rule emitted by dependency generation
                       (requires -M)
 -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'