NML:Realsprites

From GRFSpecs
Revision as of 21:01, 3 March 2012 by Hirundo (talk | contribs) (→‎Templates: Include something about usage)
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.

As of NML r1654 the 'flags' have only two possible values. When omitted the default value is used.

Name Description
CROP (default) or NOCROP Whether to crop the sprites when the -c command line option is set.

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.


Example:

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

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.