NML:Spritegroup

From GRFSpecs
Jump to: navigation, search
Block Syntax

A spritegroup combines several spritesets into a single unit. It is supported only for 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).

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;
 	}
 }