NML:Spritegroup

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

A spritegroup combines several spritesets into a single unit. It is supported only for vehicles and stations.

Vehicles

A typical spritegroup looks like:

spritegroup spritegroup_name {
	loading: (spriteset_name | [spriteset_name1, spriteset_name2, ...])
	loaded: (spriteset_name | [spriteset_name1, spriteset_name2, ...])
}

Vehicles take two different series of spritesets; loading is used when the vehicle is loading within the station, loaded is used when the vehicle is travelling. Each of those can be a single spriteset, or a (bracketed) array of spritesets. Both loading and loaded are required and should provide at least one spriteset each. If a spritegroup would contain only one spriteset, it's better to omit the spritegroup and directly use the spriteset instead. Spritegroups are used to show different graphics depending on how much the vehicle is loaded, with increasing load from left to right. Furthermore, you can easily provide special graphics for when loading in the station (for example: wagon with doors open).

Stations

A typical spritegroup looks like:

spritegroup spritegroup_name {
	little: (spriteset_name | [spriteset_name1, spriteset_name2, ...])
	lots: (spriteset_name | [spriteset_name1, spriteset_name2, ...])
}

Stations pick a spriteset depending on the amount of waiting cargo and the property cargo_threshold.

• 0 ≤ amount ≤ cargo_threshold: use spriteset from little list.
• cargo_threshold ≤ amount < 4096: use spriteset from lots list.
• 4096 ≤ amount: use last spriteset from lots list.

Within the ranges for little and lots the listed spritesets are distributed equally-spaced.

You must define at least one spriteset for lots; little may be left empty, and will fall back to using the first lots spriteset.

The amount of waiting cargo is computed depending on:

• If the station uses cargo-specific graphics (using a cargo-identifier in the graphics section), then the amount of this cargo type is used.
• If no cargo of any of the cargo-specific graphics is waiting, then the default callback is used, and the amount will be the sum of all waiting cargo.
• By default the total amount of cargo is attributed to every tile. If STAT_FLAG_DISTRIBUTED_CARGO is set in property general_flags, then the cargo amount is split equally between all station tiles.

Example

Below a simple example for defining a train engine with a livery override. The passenger wagon shows different sprites whether it is travelling empty or is filled with people.

 // Define the sprites for the engine
 template tmpl_train_length78(x, y) {
 	[x,     y,  8,22,   -3,-10]
 	[x+ 16, y, 21,15,  -14, -7]
 	[x+ 48, y, 31,12,  -16, -8]
 	[x+ 96, y, 21,16,   -6, -7]
 	[x+118, y,  8,24,   -3,-10]
 	[x+144, y, 21,16,  -15, -6]
 	[x+196, y, 32,12,  -16, -8]
 	[x+224, y, 21,15,   -6, -7]
 }
 
 spriteset(turbotrain_engine_set, "src/gfx/turbotrain.png") {
 	tmpl_train_length78(142, 118)
 }
 // Define the sprites for the passenger wagon when used with this engine
 // Loading sprites with open doors
 spriteset(turbotrain_passenger_loading_set, "src/gfx/turbotrain.png") {
 	tmpl_train_length78(142, 139)
 }
 // Passenger wagon is empty. No people shown
 spriteset(turbotrain_passenger_traveling_empty_set, "src/gfx/turbotrain.png") {
 	tmpl_train_length78(142, 159)
 }
 // Passenger wagon is full. Show people through the window
 spriteset(turbotrain_passenger_traveling_full_set, "src/gfx/turbotrain.png") {
 // has slightly different dimensions, don't use template
 	[142,159,  8,21,   -3,-10]
 	[158,159, 20,15,  -13, -7]
 	[190,159, 28,10,  -12, -6]
 	[238,159, 20,16,   -6, -7]
 	[270,159,  8,21,   -3,-10]
 	[286,159, 20,15,  -15, -6]
 	[318,159, 28,10,  -16, -6]
 	[366,159, 20,16,   -6, -7]
 }
 
 // Engine has no sprite group, because it always looks the same the spriteset is used directly.
 
 // Associate graphics with the wagon for the different loading stages
 spritegroup turbotrain_passenger_group {
 	loading: turbotrain_passenger_loading_set;
 	loaded: [turbotrain_passenger_traveling_empty_set, turbotrain_passenger_traveling_full_set];
 }
 
 // Define new graphics for the turbotrain (it has vehicleID 20):
 item(FEAT_TRAINS, turbotrain, 20) {
 	property {
 		sprite_id:                    SPRITE_ID_NEW_TRAIN;    // We have our own sprites
 		misc_flags:                   bitmask(TRAIN_FLAG_MU); // We use special sprites for passenger and mail wagons
 	}
 	graphics {                           // graphics for engine
 		turbotrain_engine_set; // note that no spritegroup is used here, it is not needed
 	}
 	livery_override(passenger_wagon) {   // graphics for alternative look of passenger wagon when used with this engine
 		turbotrain_passenger_group;
 	}
 }