From GRFSpecs
Jump to navigationJump to search
Block Syntax

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.


 [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]


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:


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

For an example see the spritegroup.