NML:Block syntax

From GRFSpecs
Jump to navigationJump to search
Block Syntax


In the description of the individual block types you'll often see a word enclosed by the less-than and greater-than symbols. These words should not be written literally, instead they reference to another block/item you should put there. The following words will be used:

A string enclosed by quotes, for example "this is a literal string"
A string defined in the language file, for example string(STR_GRF_NAME)
An expression, this can be a computation or single value constructed using <number>, <float>, <parameter>, <variable>, <function-call>
The name of an item or block. IDs should start with a letter or underscore. The rest of the ID may consist of letters, underscores and numbers.

If something is enclosed by square brackets [] it's optional.

Available block types




Recolour sprites








Random switch


Railtypetable / Roadtypetable / Tramtypetable




Disable items

Deactivate other NewGRFs

Testing for other NewGRFs

Overriding vehicles in other NewGRFs

Sprite replacement

Alternative (32bpp) sprites

Town names

Snow line

Parameter assignment

Setting base costs

Sorting vehicles in the purchase list

An example block

NML files are mainly composed from blocks. A block starts with the type of the block, optional arguments and then the contents enclosed by curly braces. Nearly all NML files will start with a grf-block. The grf-block takes no parameters and is one of the simplest blocks there is. Following is an example grf-block.

 grf {
 	grfid : "AB\02\03";
 	name : string(STR_GRF_NAME);
 	desc : string(STR_GRF_DESCRIPTION);
 	version: 10;
 	min_compatible_version: 5;

Let's look at this code line for line.

 grf {

This block is a grf-block. A grf-block has no parameters. The '{' is the start of the block content.

 	grfid : "AB\02\03";

This line sets the grfid of the resulting grf. The value is the letters AB followed by a byte with value 2 and then another one with value 3. The semicolon marks the end of the statement.

 	name : string(STR_GRF_NAME);

The name of the grf. In NML nearly all strings are put in language files. The format of the language files is described in another section. For now just assume a string with the name STR_GRF_NAME exists. To reference a string from the language file you use string(<stringname>) where <stringname> should be replaced by the actual name of the string.

 	desc : string(STR_GRF_DESCRIPTION);

This looks a lot like the previous line, only it sets the description instead of the name.

 	version : 10;

For a new grf you should set the version to 1. Every time you release a new version you should increase the version field by at least 1.

 	min_compatible_version : 5;

For a new NewGRF you should set the min_compatible_version to 1. Every time you change something in your newgrf which makes it incompatible to previous versions, you should set min_compatible_version to the current version. Changes which make a NewGRF incompatible to previous versions are most functional changes to existing behaviour, among others: changing vehicleIDs as well as some of their properties, changing industry layouts, railtype compatibility, changing (de-)activation conditions... Adding new, additional things and expanding existing behaviour (without changing the current one) is mostly considered safe).


This marks the end of the last-opened block, in this case the grf-block.