NMLTutorial/Spritelayout

NML Tutorial

Installation

Graphics files

Language files

NML Syntax

Starting an NML file (grf block)

• Creating a road vehicle

Item blocks

• • Item definition

Spriteset & spritegroup blocks

• • Adding the graphics

Template blocks

• • Templating the graphics

Cargotable block

• • Cargo-dependent graphics

Callbacks and switch blocks

• Creating a tram

• • Make it articulated

• • Adding the graphics

• • Fix the purchase menu

• Creating a train

Railtypetable block

• • Single engine

• • Three part articulated

• • Four part refit

GRF Parameters

• • Real life recolour scheme

• Creating an object

Spritelayout blocks

• • Adding the graphics

Version checks

• • Objects on slopes

32 bit sprites

• Adding 32 bit sprites

Base graphics replacement

• 32 bit base graphics

Conclusion

Glossary

NML Documentation

Where spritegroup blocks are used with vehicles, you must use spritelayouts in case of objects, stations, houses, airport- and industry tiles (from here on this page jointly referred to as objects). The reason for this is vehicles get their bounding box defined by the game because they have a standard size. Objects can come in any size (well, within it's limitations) so you must define a bounding box yourself. This is done through spritelayouts, together with referencing actual sprites from spritesets.

So for objects spritelayout blocks link the spriteset block to the item block. As opposed to spritegroup blocks, spritelayout blocks are mandatory and cannot be ommited.

Spritelayout

A spritelayout combines multiple sprites or spritesets and one or more bounding box definitions into a single entity. It is available for objects, stations, houses, airport- and industry tiles.

The general syntax is as follows:

spritelayout <identifier> {
	ground {
		<block-contents>
	}
	childsprite {
		<block-contents>
	}
	building {
		<block-contents>
	}
	childsprite {
		<block-contents>
	}
}

Childsprite blocks are optional and furthermore you must have at least a ground block or building block. It's recommended to always supply a ground block, otherwise your object might look weird (in transparent mode if the object itself is covering the entire tile). If your object is completely flat you don't need a building block, but if there's an object on the tile this is defined in the building block. Childsprite blocks allow overlaying multiple ground or building sprites. These childsprite blocks are optional and share their bounding box with the previous block. Ground blocks don't have bounding boxes, and the childsprite blocks directly after it don't have one either. Building blocks do have bounding boxes and childsprite blocks following a building blocks will use the same bounding box as defined in the building block.

The general syntax of <block-contents> is:

 		sprite: <number>|<identifier>;
 		[recolour_mode: <mode>;
 		palette: <palette>;]
 		[hide_sprite: 0|1;]
 		[always_draw: 0|1;]
 		xextent: <number>;
 		yextent: <number>;
 		zextent: <number>;
 		xoffset: <number>;
 		yoffset: <number>;
 		zoffset: <number>;

This may look difficult, but let's explain each entry:

sprite

Always in ground, building and childsprite blocks. Here you either reference:

a TTD sprite number from the base graphics set

Either type a number directly or use one of the predefined constants (see NML Documentation). Terrain sprites can be combined with the slope_to_sprite_offset function to get a specific sloped terrain sprite.

a spriteset block

If you reference a complete spriteset block, this may contain up to four sprites used for construction stages of houses and industry tiles (last sprite is the finished building). Stations, objects and airport tiles don't have construction states and as such the first sprite of the spriteset block is always used. All spriteset blocks used in the same spritelayout block must have the same number of sprites in them.

or a specific sprite from a spriteset block

If you only need a single sprite each time, you can put all these sprites in a single spriteset block and reference them individually by supplying an argument to the spriteset identifier. That way you don't have to have a spriteset block for each single sprite. The argument works like spriteset_identifier(<number>). The number corresponds to the nth sprite in the spriteset block, starting count at 0.

recolour_mode and palette

Optional, you either have them both or you don't have them. Allows to define a recolour scheme for the sprite. Available in ground, building and childsprite blocks.

hide_sprite

Optional. When set to 1, this sprite and all it's childsprites are not drawn. Available in ground, building and childsprite blocks.

always_draw

Optional. When set to 1, this sprite will ignore transparency settings. Available in ground, building and childsprite blocks.

xextent, yextent and zextent

Only in building blocks. This defines the size of the bounding box. A tile has a length of 16 in both x and y direction. The X-axis runs from top-right to bottom-left and the Y-axis from top-left to bottom-right. The z-direction is vertical and is defined in pixels. Each of these default to 16 when undefined.

xoffset, yoffset and zoffset

Defines the position of the bounding box relative to the upper corner of the tile. Units the same as corresponding extent value; default to 0 when undefined.

More details on each of these entries can be found in the NML Documentation.

This was a brief introduction into spritelayout blocks, just enough to be able to understand the rest of the object example. For more details about spritelayout blocks, you should consult the NML Documentation, which has all the details and some examples. The documentation on spritelayouts is rather extensive and there's no need to duplicate it here.

Next we'll use these spritelayouts to add graphics to our example object.

« Object

NML Tutorial: Spritelayout

Object graphics »