NML:Realsprites

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

Real sprites

Several features will need to reference actual graphics from files you created. There is a lot of information you'll need to provide, some of which is optional. Most important are the filename, the location of the sprite in that file and the offset used to position the sprite. Since blocks that reference realsprites will you to specify a default filename, you don't often need to give a filename for every separate sprite.

The format is as follows. Optional parts are placed between parentheses:

[(left_x, upper_y, width, height, )offset_x, offset_y(, flags)(, filename)(, mask)]

Unless otherwise indicated below, all parameters are numbers. They can be any expression, as long as they evaluate to a compile-time constant.

left_x, upper_y, width and height specify the location of the sprite within the file. Either all or none of them should be provided. If not specified, the whole file is used.

offset_x and offset_y are used to position the sprite. All sprites have a certain origin, e.g. for (full-length) vehicles this is the center of the vehicle. offset_x and offset_y define the position of the top-left corner of the sprite relative to this origin. Values are often negative.

flags can be a combination of the following:

Name	Description
CROP (default) or NOCROP	Whether to crop the sprites when the -c command line option is set. NOCROP is required for building sprites with childsprites in sprite layouts.
ALPHA (default) or NOALPHA	NML 0.4 Warn about semi-transparent pixels (1% - 99% alpha) in 32bpp sprites. This can be used to check whether sprites have sharp edges as, for example, required for ground sprites.
NOWHITE (default) or WHITE	NML 0.4 Warn about pure-white pixels in 8bpp sprites. Usually white pixels indicate an error in the sprite coordinates.
NOANIM (default) or ANIM	NML 0.4 Warn about palette-animated pixels in 8bpp sprites. When sprites are converted to 8bpp via some external graphics program, usage of animated colours is usually unintentional.

Multiple flags are combined using '|', for example 'NOCROP | ANIM'.

filename is a literal (quoted) string that specifies the file containing the sprite. If not specified, the default filename of the block containing the real sprite is used. If this is not specified either, it is an error.

The last parameter 'mask' is available only for 32bpp sprites defined in an alternative_sprites-block. This allows specifying an 8bpp paletted sprite with the exact same size and offsets as the 32bpp sprite. This sprite is used for recolouring purposes. Palette entry 0 means to draw the 32bpp as usual, the other colours define a replacement colour where then the 32bpp sprite is interpreted as giving intensity and alpha channel information. Note that the alternative_sprites parameter <default-mask-file> can be used to assign a mask filename to all sprites in the block. There are several possible values:

Name	Description
"mask-filename"	Filename where the mask sprite can be found. x_left and y_upper are the same as for the normal sprite
["mask-filename"]	Same as above, but the array format can prevent the mask file from being interpreted as the normal filename.
[] (an empty array)	Use no mask, even if a default mask file is specified.
["mask-filename", x_left, y_upper]	Filename containing the mask sprite, and the x and y-coordinates of the sprite within that file.
[x_left, y_upper]	x and y-coordinates of the sprite within the mask file. The mask filename is taken from the alternative_sprites block.

Example:

 [0, 0, 64, 31, -31, 0, NOCROP]

Empty / Dummy sprite

If a spriteset needs to have a specific amount of sprites, but not all entries are actually used, it is possible to set some entries as empty:

 []

For example in a vehicle purchase list spriteset:

spriteset(set_purchase, "icm.png") {
  []
  []
  []
  []
  []
  []
  [1, 1, 53, 14, -25, -10]
  []
}

Templates

NML allows to define templates to avoid repetitive declaration of the same sprite alignment (e.g. when coding different train wagons of the same size). The may be used in any place where a real sprite would be used. Templates may also be nested. Parameters may be numbers or strings (for the filename).

template templatename([param [, param [, param...]]]) {
	list of realsprites
	...
}

To use this template, simply include the following as if it were a real sprite:

templatename(<parameters>)

with <parameters> being a comma-seperated list of parameter values.

For an example see the spritegroup.