NML:Spritelayout - Revision history

Andythenorth: Since https://github.com/OpenTTD/nml/pull/309, 'all spritesets used in a layout must have the same number of sprites' no longer applies

2025-11-02T13:34:58Z

Since https://github.com/OpenTTD/nml/pull/309, 'all spritesets used in a layout must have the same number of sprites' no longer applies

← Older revision		Revision as of 13:34, 2 November 2025
Line 52:		Line 52:
	<references />		<references />

	Alternatively, you can set the value to (the name of) a [[NML:Spriteset\|spriteset]], to provide a custom sprite. When the value is just a spriteset identifier, a sprite from that set will be selected depending on the construction stage, see below~~. All spritesets used in a layout '''must''' have the same number of sprites, due to a restriction in the NFO format~~. If you supply an argument (e.g. <code style="color:darkgreen">sprite: some_sprite_set(2);</code>), the corresponding sprite from the sprite set will be used, with an argument of 0 corresponding to the first sprite. Note that the argument may also be variable, so you could e.g. use <code style="color:darkgreen">sprite: some_set(construction_state);</code> to use the construction state to select the sprite (as is the default). If the spriteset has labels defined, you can use these labels in the argument expression.		Alternatively, you can set the value to (the name of) a [[NML:Spriteset\|spriteset]], to provide a custom sprite. When the value is just a spriteset identifier, a sprite from that set will be selected depending on the construction stage, see below. If you supply an argument (e.g. <code style="color:darkgreen">sprite: some_sprite_set(2);</code>), the corresponding sprite from the sprite set will be used, with an argument of 0 corresponding to the first sprite. Note that the argument may also be variable, so you could e.g. use <code style="color:darkgreen">sprite: some_set(construction_state);</code> to use the construction state to select the sprite (as is the default). If the spriteset has labels defined, you can use these labels in the argument expression.

	* For stations, objects and airport tiles, there are no construction stages, so the first sprite from the set is used always.		* For stations, objects and airport tiles, there are no construction stages, so the first sprite from the set is used always.

Jgr: /* Sprite */

2025-08-19T21:23:28Z

Sprite

← Older revision		Revision as of 21:23, 19 August 2025
Line 48:		Line 48:
	* <code style="color:darkgreen">GROUNDSPRITE_RAIL_X <ref name="spritenames" /></code> ground tile with rail and terrain appropriate ground, NE-SW orientation (provided by railtype)		* <code style="color:darkgreen">GROUNDSPRITE_RAIL_X <ref name="spritenames" /></code> ground tile with rail and terrain appropriate ground, NE-SW orientation (provided by railtype)
	* <code style="color:darkgreen">GROUNDSPRITE_RAIL_Y <ref name="spritenames" /></code> ground tile with rail and terrain appropriate ground, NW-SE orientation (provided by railtype)		* <code style="color:darkgreen">GROUNDSPRITE_RAIL_Y <ref name="spritenames" /></code> ground tile with rail and terrain appropriate ground, NW-SE orientation (provided by railtype)
			* <code style="color:darkgreen">GROUNDSPRITE_ROAD_X <ref name="spritenames" /></code> ground tile with straight road piece on grass, NE-SW orientation

			* <code style="color:darkgreen">GROUNDSPRITE_ROAD_Y <ref name="spritenames" /></code> ground tile with straight road piece on grass, NW-SE orientation
	<references />		<references />

Frosch: Undo revision 4973 by Frosch (talk)

2025-04-04T13:57:03Z

Undo revision 4973 by Frosch (talk)

← Older revision		Revision as of 13:57, 4 April 2025
Line 126:		Line 126:
	* must not extend below the south tile edges,		* must not extend below the south tile edges,
	* must not extend left/right of the west/east tile corners,		* must not extend left/right of the west/east tile corners,
	* must not extend above the north corner by more than 200 pixels including the (default) foundation. If foundations are present, this is reduced by up to 16 pixels (steep slope N) to 184 pixels.		* must not extend above the north corner by more than 200 pixels including the (default) foundation. If foundations are present, this is reduced by up to 16 pixels (steep slope S) to 184 pixels.

	The following image shows the limitations for flat tiles, and the extreme cases of steep slopes:		The following image shows the limitations for flat tiles, and the extreme cases of steep slopes:

Frosch: /* Maximum sprite size */

2025-04-04T13:47:45Z

Maximum sprite size

← Older revision		Revision as of 13:47, 4 April 2025
Line 126:		Line 126:
	* must not extend below the south tile edges,		* must not extend below the south tile edges,
	* must not extend left/right of the west/east tile corners,		* must not extend left/right of the west/east tile corners,
	* must not extend above the north corner by more than 200 pixels including the (default) foundation. If foundations are present, this is reduced by up to 16 pixels (steep slope S) to 184 pixels.		* must not extend above the north corner by more than 200 pixels including the (default) foundation. If foundations are present, this is reduced by up to 16 pixels (steep slope N) to 184 pixels.

	The following image shows the limitations for flat tiles, and the extreme cases of steep slopes:		The following image shows the limitations for flat tiles, and the extreme cases of steep slopes:

Frosch: /* Maximum sprite size */

2025-04-04T13:38:50Z

Maximum sprite size

← Older revision		Revision as of 13:38, 4 April 2025
Line 131:		Line 131:

	[[File:Max_tile_sprite_size.png]]		[[File:Max_tile_sprite_size.png]]

			These values apply since {{ottd\|1.5}}.

	===Example (advanced) Spritelayout===		===Example (advanced) Spritelayout===

Frosch: expand on the maximum sprite size

2025-04-04T13:07:51Z

expand on the maximum sprite size

@@ Line 118: / Line 118: @@
 ** For track in Y direction: Set ''xextent'' to 5, ''yextent'' to 16.
 ** Set ''zextent'' to "<number of occupied height levels> * 8 - 2". A rough estimate is good enough.
 ===Example (advanced) Spritelayout===

Frosch: formatting

2025-04-04T11:22:38Z

formatting

← Older revision		Revision as of 11:22, 4 April 2025
Line 85:		Line 85:

	* <code style="color:darkgreen">ground</code>: Ground sprites cannot be positioned.		* <code style="color:darkgreen">ground</code>: Ground sprites cannot be positioned.
	* <code style="color:darkgreen">building</code>: A three-dimensional bounding box may be defined. The X-axis runs from top-right to bottom-left and the Y-axis from top-left to bottom-right. Both X and Y are measured in 1/16 length of the the tile border. The Z axis is vertical and measured in pixels.		* <code style="color:darkgreen">building</code>: A three-dimensional bounding box may be defined. The X-axis runs from top-right to bottom-left and the Y-axis from top-left to bottom-right. Both X and Y are measured in 1/16 length of the the tile border. The Z axis is vertical and measured in pixels.<br/>Extending the bounding box over the edges of a tile is possible, but not recommended as it may lead to glitches. '''Unless you know exactly what you are doing, please follow the recommendations below. They are most likely exactly what you need'''.<br/>In NewGRF developer mode in OpenTTD, it's possible to view the bounding boxes of all sprites by pressing Ctrl+B. In order to use and define a custom bounding box, the following attributes can be used:
	Extending the bounding box over the edges of a tile is possible, but not recommended as it may lead to glitches. '''Unless you know exactly what you are doing, please follow the recommendations below. They are most likely exactly what you need'''.
	In NewGRF developer mode in OpenTTD, it's possible to view the bounding boxes of all sprites by pressing Ctrl+B. In order to use and define a custom bounding box, the following attributes can be used:
	** <code style="color:darkgreen">xoffset</code>: Offset from the northwestern edge to the start of the bounding box (X). Unit is 1/16 of the tile border. Default value is 0.		** <code style="color:darkgreen">xoffset</code>: Offset from the northwestern edge to the start of the bounding box (X). Unit is 1/16 of the tile border. Default value is 0.
	** <code style="color:darkgreen">yoffset</code>: Offset from the northeastern edge to the start of the bounding box (Y). Unit is 1/16 of the tile border. Default value is 0.		** <code style="color:darkgreen">yoffset</code>: Offset from the northeastern edge to the start of the bounding box (Y). Unit is 1/16 of the tile border. Default value is 0.

Frosch: expand on recommendations for bounding boxes

2025-04-04T11:01:21Z

expand on recommendations for bounding boxes

@@ Line 85: / Line 85: @@
 * <code style="color:darkgreen">ground</code>: Ground sprites cannot be positioned.
-* <code style="color:darkgreen">building</code>: A three-dimensional bounding box may be defined. The X-axis runs from top-right to bottom-left and the Y-axis from top-left to bottom-right. Both X and Y are measured in 1/16 length of the the tile border. The Z axis is vertical and measured in pixels. Extending the bounding box over the edges of a tile is possible, but not recommended as it may lead to glitches. '''Unless you know exactly what you are doing, do not define any offsets or extents, but use NML's defaults. They are most likely exactly what you need'''. Default values are 0, 0, 0, 16, 16, 16, respectively. In NewGRF developer mode in OpenTTD, it's possible to view the bounding boxes of all sprites by pressing Ctrl+B. In order to use and define a custom bounding box, the following attributes can be used:
+* <code style="color:darkgreen">building</code>: A three-dimensional bounding box may be defined. The X-axis runs from top-right to bottom-left and the Y-axis from top-left to bottom-right. Both X and Y are measured in 1/16 length of the the tile border. The Z axis is vertical and measured in pixels.
-** <code style="color:darkgreen">zoffset</code>: Offset from the lowest tile corner (with foundation added) to the start of the bounding box (Z). Unit is pixels
+** <code style="color:darkgreen">xoffset</code>: Offset from the northwestern edge to the start of the bounding box (X). Unit is 1/16 of the tile border. Default value is 0.
-** <code style="color:darkgreen">xextent</code>: Size of the bounding box, in the X-direction. Must be a compile-time constant. Unit is 1/16 of the tile border
+** <code style="color:darkgreen">yoffset</code>: Offset from the northeastern edge to the start of the bounding box (Y). Unit is 1/16 of the tile border. Default value is 0.
-** <code style="color:darkgreen">yextent</code>: Size of the bounding box, in the Y-direction. Must be a compile-time constant. Unit is 1/16 of the tile border
+** <code style="color:darkgreen">zoffset</code>: Offset from the lowest tile corner (with foundation added) to the start of the bounding box (Z). Unit is pixels. Default value is 0.
-** <code style="color:darkgreen">zextent</code>: Size of the bounding box, in the Z-direction. Must be a compile-time constant. Unit is pixels
+** <code style="color:darkgreen">xextent</code>: Size of the bounding box, in the X-direction. Must be a compile-time constant. Unit is 1/16 of the tile border. Default value is 16.
 * <code style="color:darkgreen">childsprite</code>: Child sprites may be positioned relative to their 'parent' sprite that defines the bounding box. <code style="color:darkgreen">xoffset</code> and <code style="color:darkgreen">yoffset</code> may be set to specify an offset in pixels between the origin of the parent and child sprite. When the parent sprite is the ground sprite, TTDPatch does not support offsets other than 0,0. Note that all child sprites should fit inside the bounding box of the parent sprite to avoid visual glitches.
 ===Example (advanced) Spritelayout===

Frosch: mention special ground sprites

2025-04-04T10:33:06Z

mention special ground sprites

← Older revision		Revision as of 10:33, 4 April 2025
Line 44:		Line 44:
	* <code style="color:darkgreen">GROUNDSPRITE_SNOW_4_4 <ref name="spritenames" /></code> snowy ground tile		* <code style="color:darkgreen">GROUNDSPRITE_SNOW_4_4 <ref name="spritenames" /></code> snowy ground tile
	* <code style="color:darkgreen">GROUNDSPRITE_CONCRETE</code> concrete ground tile		* <code style="color:darkgreen">GROUNDSPRITE_CONCRETE</code> concrete ground tile
	* <code style="color:darkgreen">GROUNDSPRITE_WATER</code> flat water tile		* <code style="color:darkgreen">GROUNDSPRITE_WATER</code> flat water tile, automatically choosen from sea, river and canal sprites, including river and canal borders.
	* <code style="color:darkgreen">GROUNDSPRITE_CLEARED <ref name="spritenames" /></code> ground tile that has just been bulldozed (with brown colour)		* <code style="color:darkgreen">GROUNDSPRITE_CLEARED <ref name="spritenames" /></code> ground tile that has just been bulldozed (with brown colour)
	* <code style="color:darkgreen">GROUNDSPRITE_RAIL_X <ref name="spritenames" /></code> ground tile with rail and terrain appropriate ground, NE-SW orientation		* <code style="color:darkgreen">GROUNDSPRITE_RAIL_X <ref name="spritenames" /></code> ground tile with rail and terrain appropriate ground, NE-SW orientation (provided by railtype)
	* <code style="color:darkgreen">GROUNDSPRITE_RAIL_Y <ref name="spritenames" /></code> ground tile with rail and terrain appropriate ground, NW-SE orientation		* <code style="color:darkgreen">GROUNDSPRITE_RAIL_Y <ref name="spritenames" /></code> ground tile with rail and terrain appropriate ground, NW-SE orientation (provided by railtype)

	<references />		<references />
Line 60:		Line 60:
	** If there are four sprites, one is used for each construction stage.		** If there are four sprites, one is used for each construction stage.
	** Sprites after the first four are always ignored.		** Sprites after the first four are always ignored.
			* For road stops the usage of the ground sprite depends on the [[NML:Roadstops#List of draw mode flags\|''draw_mode'' property]].
			* For objects the usage of the ground sprite may be skipped depending on the [[NML:Objects#List of object flags\|''OBJ_FLAG_DRAW_WATER'' flag]], which has the same effect as ''GROUNDSPRITE_WATER''.

	===Recolouring===		===Recolouring===

Andythenorth: /* Sprite */ - GROUNDSPRITE_RAIL_X and GROUNDSPRITE_RAIL_Y

2023-10-02T18:27:45Z

Sprite: - GROUNDSPRITE_RAIL_X and GROUNDSPRITE_RAIL_Y

← Older revision		Revision as of 18:27, 2 October 2023
Line 46:		Line 46:
	* <code style="color:darkgreen">GROUNDSPRITE_WATER</code> flat water tile		* <code style="color:darkgreen">GROUNDSPRITE_WATER</code> flat water tile
	* <code style="color:darkgreen">GROUNDSPRITE_CLEARED <ref name="spritenames" /></code> ground tile that has just been bulldozed (with brown colour)		* <code style="color:darkgreen">GROUNDSPRITE_CLEARED <ref name="spritenames" /></code> ground tile that has just been bulldozed (with brown colour)
			* <code style="color:darkgreen">GROUNDSPRITE_RAIL_X <ref name="spritenames" /></code> ground tile with rail and terrain appropriate ground, NE-SW orientation
			* <code style="color:darkgreen">GROUNDSPRITE_RAIL_Y <ref name="spritenames" /></code> ground tile with rail and terrain appropriate ground, NW-SE orientation

	<references />		<references />