NMLTutorial/Spriteset and spritegroup - Revision history

FooBar: compression isn't interesting for someone learning NML, so let's not bother the reader with that

2011-09-08T18:58:42Z

compression isn't interesting for someone learning NML, so let's not bother the reader with that

← Older revision		Revision as of 18:58, 8 September 2011
Line 22:		Line 22:
	<pre class="pseudo">		<pre class="pseudo">
	[left_x, upper_y, width, height, offset_x, offset_y]		[left_x, upper_y, width, height, offset_x, offset_y]
	[left_x, upper_y, width, height, offset_x, offset_y, compression]
	[left_x, upper_y, width, height, offset_x, offset_y, filename]		[left_x, upper_y, width, height, offset_x, offset_y, filename]
	[left_x, upper_y, width, height, offset_x, offset_y, compression, filename]
	[offset_x, offset_y]		[offset_x, offset_y]
	[offset_x, offset_y, compression]
	[offset_x, offset_y, filename]		[offset_x, offset_y, filename]
	[offset_x, offset_y, compression, filename]
	</pre>		</pre>

	Use ~~one of~~ the first ~~four~~ if you have more than one sprite in a single graphics file. ~~Formats~~ ~~five and~~ ~~six~~ can only be used if the spriteset has exactly one sprite and the graphics file contains exactly the one sprite (and no extraneous white around it). The last ~~two~~ can be used if you have each sprite in a separate file.		Use the first or second format if you have more than one sprite in a single graphics file. The third format can only be used if the spriteset has exactly one sprite and the graphics file contains exactly the one sprite (and no extraneous white around it). The last format can be used if you have each sprite in a separate file.

	An explanation of the values you need to provide:		An explanation of the values you need to provide:
Line 40:		Line 36:
	* '''offset_x''': horizontal offset in pixels from the center of the bounding box (see below);		* '''offset_x''': horizontal offset in pixels from the center of the bounding box (see below);
	* '''offset_y''': vertical offset in pixels from the center of the bounding box (see below);		* '''offset_y''': vertical offset in pixels from the center of the bounding box (see below);
	* '''compression''': [http://newgrf-specs.tt-wiki.net/wiki/NML:Realsprites compression] to use for this sprite, omit it if you don't care;
	* '''filename''': path and file name of the graphics file this sprite is in, if it is different than the one defined in the spriteset itself.		* '''filename''': path and file name of the graphics file this sprite is in, if it is different than the one defined in the spriteset itself.

FooBar: some more details on sprite offsets

2011-09-08T17:41:22Z

some more details on sprite offsets

← Older revision		Revision as of 17:41, 8 September 2011
Line 38:		Line 38:
	* '''width''': width of the sprite in pixels;		* '''width''': width of the sprite in pixels;
	* '''height''': height of the sprite in pixels;		* '''height''': height of the sprite in pixels;
	* '''offset_x''': horizontal offset in pixels from the center of the bounding box ~~[1]~~;		* '''offset_x''': horizontal offset in pixels from the center of the bounding box (see below);
	* '''offset_y''': vertical offset in pixels from the center of the bounding box ~~[1]~~;		* '''offset_y''': vertical offset in pixels from the center of the bounding box (see below);
	* '''compression''': [http://newgrf-specs.tt-wiki.net/wiki/NML:Realsprites compression] to use for this sprite, omit it if you don't care;		* '''compression''': [http://newgrf-specs.tt-wiki.net/wiki/NML:Realsprites compression] to use for this sprite, omit it if you don't care;
	* '''filename''': path and file name of the graphics file this sprite is in, if it is different than the one defined in the spriteset itself.		* '''filename''': path and file name of the graphics file this sprite is in, if it is different than the one defined in the spriteset itself.
Line 58:		Line 58:
	</pre>		</pre>

	==== Bounding boxes ====		==== Bounding boxes and offsets ====
	Every object with a height has a bounding box in TTD. This bounding box helps the game draw the sprites in the correct order.		Every object with a height has a bounding box in TTD. This bounding box helps the game draw the sprites in the correct order. You can see this bounding box as a cuboid in which the object is drawn. In OpenTTD, you can view these bounding boxes by pressing ctrl+B (you need to have <code>newgrf_developer_tools</code> active). More details on bounding boxes can be found [http://newgrf-specs.tt-wiki.net/wiki/PalettesAndCoordinates#Coordinates here].


	In OpenTTD, you can view these bounding boxes by pressing ctrl+B (you need to have <code>newgrf_developer_tools</code> active). More details on bounding boxes can be found [http://newgrf-specs.tt-wiki.net/wiki/PalettesAndCoordinates#Coordinates here].
			The offsets you set in a spriteset define where the sprite is drawn inside this bounding box.

			For vehicles this is relative to the middle of the bounding box. So both offsets set to zero will put the top left corner of the sprite in the middle of the bounding box. A general rule of thumb here is to take half the width/height (rounded down) and then the negative of that for the x/y offset. This places the vehicle roughly in the middle of it's bounding box.

			For buildings and other non-vehicle things the sprites are drawn relative to the furthest (lower) corner of the bounding box. In this case with a 0/0 offset the top left of the sprite is in that particular corner. The rule of thumb here is to take negative half the sprite width for the x-offset and minus sprite height plus diagonal bounding box depth for the y-offset.

			Even with these rules of thumb nearly every sprite will need minor tweakings. The ingame sprite aligner ([http://wiki.openttd.org/NewGRF_Debugging OpenTTD] \| [http://www.tt-wiki.net/wiki/GRFAuthorHelperWindow TTDPatch]) is a great tool to help you with that.

	=== Paths ===		=== Paths ===

FooBar: use identifier consistently

2011-08-28T16:13:55Z

use identifier consistently

← Older revision		Revision as of 16:13, 28 August 2011
Line 85:		Line 85:

	<pre class="pseudo">		<pre class="pseudo">
	spritegroup <~~spritegroup_name~~> {		spritegroup <identifier> {
	loading: <~~spriteset_name1~~>;		loading: <spriteset_identifier1>;
	loaded: <~~spriteset_name2~~>;		loaded: <spriteset_identifier2>;
	}		}
	</pre>		</pre>
Line 94:		Line 94:

	<pre class="pseudo">		<pre class="pseudo">
	spritegroup <~~spritegroup_name~~> {		spritegroup <identifier> {
	loading: [<~~spriteset_name1empty~~>, <~~spriteset_name1full~~>];		loading: [<spriteset_identifier1empty>, <spriteset_identifier1full>];
	loaded: [<~~spriteset_name2empty~~>, <~~spriteset_name2intermediate~~>, <~~spriteset_name2full~~>];		loaded: [<spriteset_identifier2empty>, <spriteset_identifier2intermediate>, <spriteset_identifier2full>];
	}		}
	</pre>		</pre>
Line 102:		Line 102:
	It is up to you how many states between empty and full you want to provide. You can just stick with the two (empty and full), or provide any number of intermediate sprites to show a gradual loading effect.		It is up to you how many states between empty and full you want to provide. You can just stick with the two (empty and full), or provide any number of intermediate sprites to show a gradual loading effect.

	The <code><~~spritegroup_name~~></code> again is an ~~identifier~~ you choose yourself. This time it's useful to precede it with ''spritegroup_'', for reasons hopefully known to you by now (if not, read back).		The <code><identifier></code> again is a name for the block you choose yourself. This time it's useful to precede it with ''spritegroup_'', for reasons hopefully known to you by now (if not, read back).

	The <code><~~spriteset_name~~...></code> refer each to a ~~separate~~ spriteset. You may use the same spritesets in <code>loading</code> and <code>loaded</code> if you for instance want to show open doors in a station. If you end up all spritesets in a spritegroup definition being the same, you can best completely leave the spritegroup out and reference the spriteset directly from where you need it (e.g. in case of the purchase menu sprite).		The <code><spriteset_identifier...></code> refer each to a spriteset block. You may use the same spritesets in <code>loading</code> and <code>loaded</code> if you for instance want to show open doors in a station. If you end up all spritesets in a spritegroup definition being the same, you can best completely leave the spritegroup out and reference the spriteset directly from where you need it (e.g. in case of the purchase menu sprite).

FooBar: pre class

2011-08-27T22:18:33Z

pre class

← Older revision		Revision as of 22:18, 27 August 2011
Line 9:		Line 9:
	The general syntax is as follows:		The general syntax is as follows:

	<pre>		<pre class="pseudo">
	spriteset (<identifier> [, <graphics_file>]) {		spriteset (<identifier> [, <graphics_file>]) {
	<list_of_realsprites>		<list_of_realsprites>
Line 20:		Line 20:
	The <code><list_of_realsprites></code> defines the details of each actual sprite. A vehicle typically has eight sprites in its spriteset. Each sprite definition in the spriteset has one of the following formats:		The <code><list_of_realsprites></code> defines the details of each actual sprite. A vehicle typically has eight sprites in its spriteset. Each sprite definition in the spriteset has one of the following formats:

	<pre>		<pre class="pseudo">
	[left_x, upper_y, width, height, offset_x, offset_y]		[left_x, upper_y, width, height, offset_x, offset_y]
	[left_x, upper_y, width, height, offset_x, offset_y, compression]		[left_x, upper_y, width, height, offset_x, offset_y, compression]
Line 45:		Line 45:
	Each realsprite goes on its own line inside the spriteset. You '''don't''' end each line with a semicolon as you would do with regular code lines. So for a vehicle with eight views, you'll end up with a spriteset as the following:		Each realsprite goes on its own line inside the spriteset. You '''don't''' end each line with a semicolon as you would do with regular code lines. So for a vehicle with eight views, you'll end up with a spriteset as the following:

	<pre>		<pre class="pseudo">
	spriteset (<identifier>, <graphics_file>) {		spriteset (<identifier>, <graphics_file>) {
	[left_x1, upper_y1, width1, height1, offset_x1, offset_y1]		[left_x1, upper_y1, width1, height1, offset_x1, offset_y1]
Line 84:		Line 84:
	If you only have different sprites for vehicles at stations and vehicles travelling, the general syntax is as follows:		If you only have different sprites for vehicles at stations and vehicles travelling, the general syntax is as follows:

	<pre>		<pre class="pseudo">
	spritegroup <spritegroup_name> {		spritegroup <spritegroup_name> {
	loading: <spriteset_name1>;		loading: <spriteset_name1>;
Line 93:		Line 93:
	If you also have different sprites for loaded and unloaded states, each line turns into an array:		If you also have different sprites for loaded and unloaded states, each line turns into an array:

	<pre>		<pre class="pseudo">
	spritegroup <spritegroup_name> {		spritegroup <spritegroup_name> {
	loading: [<spriteset_name1empty>, <spriteset_name1full>];		loading: [<spriteset_name1empty>, <spriteset_name1full>];

FooBar: /* Spriteset */ unique identifiers

2011-08-24T13:05:24Z

Spriteset: unique identifiers

← Older revision		Revision as of 13:05, 24 August 2011
Line 15:		Line 15:
	</pre>		</pre>

	The <code><identifier></code> is again a name for this spriteset you choose yourself. It's useful to precede the name with ''spriteset_'' so ~~that~~ you know this identifier is that of a spriteset. <code><graphics_file></code> is optional and may be omitted if you set the path and file name for each sprite individually.		The <code><identifier></code> is again a name for this spriteset you choose yourself. It's useful to precede the name with ''spriteset_'' followed by the name of the item this spriteset belongs to. This way you know this identifier is that of a spriteset for this particular item and helps keeping unique identifiers. <code><graphics_file></code> is optional and may be omitted if you set the path and file name for each sprite individually.

	=== <list_of_realsprites> ===		=== <list_of_realsprites> ===
Line 78:		Line 78:

	The (relative) path and filename to be used in the nml file in this case will be <code>gfx/sprites.png</code>.		The (relative) path and filename to be used in the nml file in this case will be <code>gfx/sprites.png</code>.


	== Spritegroup ==		== Spritegroup ==

FooBar: Clarify how a spriteset looks with realsprites in it.

2011-08-23T16:59:25Z

Clarify how a spriteset looks with realsprites in it.

@@ Line 42: / Line 42: @@
 * '''compression''': [http://newgrf-specs.tt-wiki.net/wiki/NML:Realsprites compression] to use for this sprite, omit it if you don't care;
 * '''filename''': path and file name of the graphics file this sprite is in, if it is different than the one defined in the spriteset itself.
 ==== Bounding boxes ====

FooBar: don't hit save if you mean preview; this time there's actually stuff to save

2011-08-22T20:47:33Z

don't hit save if you mean preview; this time there's actually stuff to save

← Older revision		Revision as of 20:47, 22 August 2011
Line 1:		Line 1:
	{{NMLTutorial}}		{{NMLTutorial}}

			Spritesets link an actual graphics file to the NML code. Spritegroups combine multiple spritesets to show different graphics for loaded and unloaded vehicles as well as different graphics for vehicles travelling and vehicles in stations.


	{{NMLTutorialNavbar\|\|}}
			== Spriteset ==
			The spriteset defines where sprites can be found in a graphics file, how big these sprites are, what their offsets should be with respect to the ingame bounding box and optionally what compression to use for the sprite. The location of the graphics file can be set once per spriteset or for each sprite separately.

			The general syntax is as follows:

			<pre>
			spriteset (<identifier> [, <graphics_file>]) {
			<list_of_realsprites>
			}
			</pre>

			The <code><identifier></code> is again a name for this spriteset you choose yourself. It's useful to precede the name with ''spriteset_'' so that you know this identifier is that of a spriteset. <code><graphics_file></code> is optional and may be omitted if you set the path and file name for each sprite individually.

			=== <list_of_realsprites> ===
			The <code><list_of_realsprites></code> defines the details of each actual sprite. A vehicle typically has eight sprites in its spriteset. Each sprite definition in the spriteset has one of the following formats:

			<pre>
			[left_x, upper_y, width, height, offset_x, offset_y]
			[left_x, upper_y, width, height, offset_x, offset_y, compression]
			[left_x, upper_y, width, height, offset_x, offset_y, filename]
			[left_x, upper_y, width, height, offset_x, offset_y, compression, filename]
			[offset_x, offset_y]
			[offset_x, offset_y, compression]
			[offset_x, offset_y, filename]
			[offset_x, offset_y, compression, filename]
			</pre>

			Use one of the first four if you have more than one sprite in a single graphics file. Formats five and six can only be used if the spriteset has exactly one sprite and the graphics file contains exactly the one sprite (and no extraneous white around it). The last two can be used if you have each sprite in a separate file.

			An explanation of the values you need to provide:
			* '''left_x''': horizontal distance in pixels from the top left of the image file to the top left of the sprite;
			* '''upper_y''': vertical distance in pixels from the top left of the image file to the top left of the sprite;
			* '''width''': width of the sprite in pixels;
			* '''height''': height of the sprite in pixels;
			* '''offset_x''': horizontal offset in pixels from the center of the bounding box [1];
			* '''offset_y''': vertical offset in pixels from the center of the bounding box [1];
			* '''compression''': [http://newgrf-specs.tt-wiki.net/wiki/NML:Realsprites compression] to use for this sprite, omit it if you don't care;
			* '''filename''': path and file name of the graphics file this sprite is in, if it is different than the one defined in the spriteset itself.

			==== Bounding boxes ====
			Every object with a height has a bounding box in TTD. This bounding box helps the game draw the sprites in the correct order.

			In OpenTTD, you can view these bounding boxes by pressing ctrl+B (you need to have <code>newgrf_developer_tools</code> active). More details on bounding boxes can be found [http://newgrf-specs.tt-wiki.net/wiki/PalettesAndCoordinates#Coordinates here].

			=== Paths ===
			The path to a graphics file can be either absolute to your hard drive or relative to the nml file. It's recommended to use relative paths, as this allows you to move the folder with the NML source files without having to edit all paths and it allows others to use your source without too much problems as well.

			Let's take a look at the following folder structure for instance:

			mygrf
			\|- gfx
			\| \|- sprites.png
			\|- lang
			\| \|- english.lng
			\| \|- other_language.lng
			\|- custom_tags.txt
			\|- mygrf.nml

			The (relative) path and filename to be used in the nml file in this case will be <code>gfx/sprites.png</code>.


			== Spritegroup ==
			A spritegroup combines multiple spritesets into a single entity. It is only available for vehicles and is used to show different graphics for loaded and unloaded vehicles as well as different graphics for vehicles travelling and vehicles in stations.

			If you only have different sprites for vehicles at stations and vehicles travelling, the general syntax is as follows:

			<pre>
			spritegroup <spritegroup_name> {
			loading: <spriteset_name1>;
			loaded: <spriteset_name2>;
			}
			</pre>

			If you also have different sprites for loaded and unloaded states, each line turns into an array:

			<pre>
			spritegroup <spritegroup_name> {
			loading: [<spriteset_name1empty>, <spriteset_name1full>];
			loaded: [<spriteset_name2empty>, <spriteset_name2intermediate>, <spriteset_name2full>];
			}
			</pre>

			It is up to you how many states between empty and full you want to provide. You can just stick with the two (empty and full), or provide any number of intermediate sprites to show a gradual loading effect.

			The <code><spritegroup_name></code> again is an identifier you choose yourself. This time it's useful to precede it with ''spritegroup_'', for reasons hopefully known to you by now (if not, read back).

			The <code><spriteset_name...></code> refer each to a separate spriteset. You may use the same spritesets in <code>loading</code> and <code>loaded</code> if you for instance want to show open doors in a station. If you end up all spritesets in a spritegroup definition being the same, you can best completely leave the spritegroup out and reference the spriteset directly from where you need it (e.g. in case of the purchase menu sprite).


			Continue to learn how to apply this new knowledge to the example road vehicle.

			{{NMLTutorialNavbar\|Road vehicle item definition\|Road vehicle graphics}}

FooBar: Created page with "{{NMLTutorial}} {{NMLTutorialNavbar||}}"

2011-08-22T20:03:33Z

Created page with "{{NMLTutorial}} {{NMLTutorialNavbar||}}"

New page