NML:Block syntax

NewGRF Meta Language

Preface

Getting started

Graphics files

Blocks

Units

Expressions

Elementary values

Builtin functions

Language files

Lists of props, vars and CBs

Warnings

Additional references

NewGRF compatibility

Deprecated syntax

Changes from NML 0.2 to 0.3

Changes from NML 0.3 to 0.4

Changes from NML 0.4 to 0.5

Vehicles, Stations, Canals, Bridges, Towns, Houses, Industries (Tiles), Cargos, Airports+Tiles, Objects, Railtypes, Roadtypes, Tramtypes, Terrain

NML Tutorial

Block Syntax

GRF

• GRF parameters

Item

• Property
• Graphics
• Livery override

Realsprites

Recolour sprites

Template

Spriteset

Spritegroup

Spritelayout

Tilelayout

Switch

Produce

Random switch

Cargotable

Railtypetable / Roadtypetable / Tramtypetable

If/else

While

Error

Disable items

Deactivate other NewGRFs

Testing for other NewGRFs

Overriding vehicles in other NewGRFs

Sprite replacement

• Replace TTD sprites
• Replace new sprites
• Add font glyphs

Alternative (32bpp) sprites

Town names

• Town names parts

Snow line

Parameter assignment

Setting base costs

Sorting vehicles in the purchase list

Syntax

In the next sections 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:

<literal-string>

A string enclosed by quotes, for example "this is a literal string"

<string>

A string defined in the language file, for example string(STR_GRF_NAME)

<expression>

An expression, this can be a computation or single value constructed using <number>, <float>, <parameter>, <variable>, <function-call>

<ID>

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.

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.

Features

NewGRFs can be used to modify various types of items. Examples include trains, stations and industries. Such a type of item is called a feature. The following table contains a list of features and their identifiers. These identifiers may be used to refer to the feature when needed.

Name	Description
FEAT_TRAINS	Trains
FEAT_ROADVEHS	Road vehicles
FEAT_SHIPS	Ships
FEAT_AIRCRAFT	Aircraft
FEAT_STATIONS	Train stations
FEAT_CANALS	Canals
FEAT_BRIDGES	Bridges
FEAT_HOUSES	Town houses
FEAT_GLOBALVARS	Various global variables
FEAT_INDUSTRYTILES	Industry tiles (visible part of industries)
FEAT_INDUSTRIES	Industries
FEAT_CARGOS	Cargo types
FEAT_SOUNDEFFECTS	Sound effects
FEAT_AIRPORTS	Airports
FEAT_SIGNALS	Train signals
FEAT_OBJECTS	Non-interactive objects (example: lighthouse)
FEAT_RAILTYPES	Rail types
FEAT_ROADTYPES	Road types
FEAT_TRAMTYPES	Tram types
FEAT_AIRPORTTILES	Airport tiles (visible part of airports)