Difference between revisions of "NML:Realsprites"

From GRFSpecs
Jump to navigationJump to search
(Templates are part of realsprites as they can only be used there)
m (Grammatical error in "ALPHA" description)
 
(8 intermediate revisions by 3 users not shown)
Line 3: Line 3:
 
== Real sprites ==
  
== Real sprites ==
   
−
Several features will need to reference actual graphics from files you created. You can provide real sprites in many different formats, all detailed below. There is a lot of information you'll need to provide. Most important are the filename and the location of the sprite in that file. Since most blocks that reference realsprites will allow you to specify a default filename, you don't often need to give a filename for every separate sprite.
 +
Several features will need to reference actual graphics from files you created. There is a lot of information you'll need to provide, some of which is optional. Most important are the filename, the location of the sprite in that file and the offset used to position the sprite. Since blocks that reference realsprites will you to specify a default filename, you don't often need to give a filename for every separate sprite.
   
  +
The format is as follows. Optional parts are placed between parentheses:
−
Allowed formats:
  
   
−
[left_x, upper_y, width, height, offset_x, offset_y]
 +
[(left_x, upper_y, width, height, )offset_x, offset_y(, flags)(, filename)(, mask)]
−
[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]
  
   
  +
Unless otherwise indicated below, all parameters are numbers. They can be any expression, as long as they evaluate to a compile-time constant.
−
If you don't specify left_x, upper_y, width and height it'll default to the complete file. If you don't specify the filename it'll take the filename from the block containing this realsprite. It's a fatal error not to specify a filename for either the block containing a realsprite or the realsprite itself. For possible values of compression, see the table below.
  
   
  +
left_x, upper_y, width and height specify the location of the sprite within the file. Either all or none of them should be provided. If not specified, the whole file is used.
−
For all parameters you can use expressions as complex as you want as long as they can be resolved at compile time.
  
   
  +
offset_x and offset_y are used to position the sprite. All sprites have a certain origin, e.g. for (full-length) vehicles this is the center of the vehicle. offset_x and offset_y define the position of the top-left corner of the sprite relative to this origin. Values are often negative.
−
As of NML r1654 the compression bit has only two possible values. When ommitted it will take the default value.
  
   
  +
flags can be a combination of the following:
 
{| class="t"
  
{| class="t"
 
! Name
  
! Name
 
! Description
  
! Description
 
|-
  
|-
−
| CROP (default) or NOCROP
 +
| <code style="color:darkgreen">CROP</code> (default) or <code style="color:darkgreen">NOCROP</code>
 
| Whether to crop the sprites when the -c command line option is set.
  
| Whether to crop the sprites when the -c command line option is set.
  +
<code style="color:darkgreen">NOCROP</code> is required for building sprites with childsprites in [[NML:Spritelayout|sprite layouts]].
  +
|-
  +
| <code style="color:darkgreen">ALPHA</code> (default) or <code style="color:darkgreen">NOALPHA</code>
  +
| {{nml|0.4}} Warn about semi-transparent pixels (1% - 99% alpha) in 32bpp sprites.
  +
This can be used to check whether sprites have sharp edges as, for example, required for ground sprites.
  +
|-
  +
| <code style="color:darkgreen">NOWHITE</code> (default) or <code style="color:darkgreen">WHITE</code>
  +
| {{nml|0.4}} Warn about pure-white pixels in 8bpp sprites.
  +
Usually white pixels indicate an error in the sprite coordinates.
  +
|-
  +
| <code style="color:darkgreen">NOANIM</code> (default) or <code style="color:darkgreen">ANIM</code>
  +
| {{nml|0.4}} Warn about palette-animated pixels in 8bpp sprites.
  +
When sprites are converted to 8bpp via some external graphics program, usage of animated colours is usually unintentional.
  +
|}
  +
Multiple flags are combined using '<code style="color:darkgreen">|</code>', for example '<code style="color:darkgreen">NOCROP | ANIM</code>'.
  +
  +
filename is a literal (quoted) string that specifies the file containing the sprite. If not specified, the default filename of the block containing the real sprite is used. If this is not specified either, it is an error.
  +
  +
The last parameter 'mask' is available only for 32bpp sprites defined in an [[NML:Alternative_sprites|alternative_sprites]]-block. This allows specifying an 8bpp paletted sprite with the exact same size and offsets as the 32bpp sprite. This sprite is used for recolouring purposes. Palette entry 0 means to draw the 32bpp as usual, the other colours define a replacement colour where then the 32bpp sprite is interpreted as giving intensity and alpha channel information. Note that the alternative_sprites parameter <default-mask-file> can be used to assign a mask filename to all sprites in the block. There are several possible values:
  +
  +
{| class="t"
  +
! Name
  +
! Description
  +
|-
  +
| "mask-filename"
  +
| Filename where the mask sprite can be found. x_left and y_upper are the same as for the normal sprite
  +
|-
  +
| ["mask-filename"]
  +
| Same as above, but the array format can prevent the mask file from being interpreted as the normal filename.
  +
|-
  +
| [] (an empty array)
  +
| Use no mask, even if a default mask file is specified.
  +
|-
  +
| ["mask-filename", x_left, y_upper]
  +
| Filename containing the mask sprite, and the x and y-coordinates of the sprite within that file.
  +
|-
  +
| [x_left, y_upper]
  +
| x and y-coordinates of the sprite within the mask file. The mask filename is taken from the alternative_sprites block.
 
|}
  
|}
   
Line 34: Line 66:
   
 
<pre style="color:blue">
  
<pre style="color:blue">
−
[0, 0, 64, 31, -31, 0, TILE]
 +
[0, 0, 64, 31, -31, 0, NOCROP]
 
</pre>
  
</pre>
   
  +
== Empty / Dummy sprite ==
  +
If a spriteset needs to have a specific amount of sprites, but not all entries are actually used, it is possible to set some entries as empty:
  +
<pre>
  +
[]
  +
</pre>
  +
  +
For example in a vehicle purchase list spriteset:
  +
<pre>
  +
spriteset(set_purchase, "icm.png") {
  +
[]
  +
[]
  +
[]
  +
[]
  +
[]
  +
[]
  +
[1, 1, 53, 14, -25, -10]
  +
[]
  +
}
  +
</pre>
   
 
== Templates ==
  
== Templates ==
Line 47: Line 98:
 
...
  
...
 
}
  
}
  +
  +
To use this template, simply include the following as if it were a real sprite:
  +
  +
templatename(<parameters>)
  +
  +
with <parameters> being a comma-seperated list of parameter values.
   
 
For an example see the [[NML:Spritegroup|spritegroup]].
  
For an example see the [[NML:Spritegroup|spritegroup]].

Latest revision as of 14:12, 6 June 2020

Block Syntax

Real sprites

Several features will need to reference actual graphics from files you created. There is a lot of information you'll need to provide, some of which is optional. Most important are the filename, the location of the sprite in that file and the offset used to position the sprite. Since blocks that reference realsprites will you to specify a default filename, you don't often need to give a filename for every separate sprite.

The format is as follows. Optional parts are placed between parentheses: 

[(left_x, upper_y, width, height, )offset_x, offset_y(, flags)(, filename)(, mask)]

Unless otherwise indicated below, all parameters are numbers. They can be any expression, as long as they evaluate to a compile-time constant.

left_x, upper_y, width and height specify the location of the sprite within the file. Either all or none of them should be provided. If not specified, the whole file is used.

offset_x and offset_y are used to position the sprite. All sprites have a certain origin, e.g. for (full-length) vehicles this is the center of the vehicle. offset_x and offset_y define the position of the top-left corner of the sprite relative to this origin. Values are often negative.

flags can be a combination of the following:

Name Description
CROP (default) or NOCROP Whether to crop the sprites when the -c command line option is set.

NOCROP is required for building sprites with childsprites in sprite layouts.

ALPHA (default) or NOALPHA NML 0.4 Warn about semi-transparent pixels (1% - 99% alpha) in 32bpp sprites.

This can be used to check whether sprites have sharp edges as, for example, required for ground sprites.

NOWHITE (default) or WHITE NML 0.4 Warn about pure-white pixels in 8bpp sprites.

Usually white pixels indicate an error in the sprite coordinates.

NOANIM (default) or ANIM NML 0.4 Warn about palette-animated pixels in 8bpp sprites.

When sprites are converted to 8bpp via some external graphics program, usage of animated colours is usually unintentional.

Multiple flags are combined using '|', for example 'NOCROP | ANIM'.

filename is a literal (quoted) string that specifies the file containing the sprite. If not specified, the default filename of the block containing the real sprite is used. If this is not specified either, it is an error.

The last parameter 'mask' is available only for 32bpp sprites defined in an alternative_sprites-block. This allows specifying an 8bpp paletted sprite with the exact same size and offsets as the 32bpp sprite. This sprite is used for recolouring purposes. Palette entry 0 means to draw the 32bpp as usual, the other colours define a replacement colour where then the 32bpp sprite is interpreted as giving intensity and alpha channel information. Note that the alternative_sprites parameter <default-mask-file> can be used to assign a mask filename to all sprites in the block. There are several possible values:

Name Description
"mask-filename" Filename where the mask sprite can be found. x_left and y_upper are the same as for the normal sprite
["mask-filename"] Same as above, but the array format can prevent the mask file from being interpreted as the normal filename.
[] (an empty array) Use no mask, even if a default mask file is specified.
["mask-filename", x_left, y_upper] Filename containing the mask sprite, and the x and y-coordinates of the sprite within that file.
[x_left, y_upper] x and y-coordinates of the sprite within the mask file. The mask filename is taken from the alternative_sprites block.


Example: 

 [0, 0, 64, 31, -31, 0, NOCROP]

Empty / Dummy sprite

If a spriteset needs to have a specific amount of sprites, but not all entries are actually used, it is possible to set some entries as empty: 

 []

For example in a vehicle purchase list spriteset: 

spriteset(set_purchase, "icm.png") {
  []
  []
  []
  []
  []
  []
  [1, 1, 53, 14, -25, -10]
  []
}

Templates

NML allows to define templates to avoid repetitive declaration of the same sprite alignment (e.g. when coding different train wagons of the same size). The may be used in any place where a real sprite would be used. Templates may also be nested. Parameters may be numbers or strings (for the filename). 


template templatename([param [, param [, param...]]]) {
	list of realsprites
	...
}

To use this template, simply include the following as if it were a real sprite: 

templatename(<parameters>)

with <parameters> being a comma-seperated list of parameter values.

For an example see the spritegroup.

Retrieved from ‘https://newgrf-specs.tt-wiki.net/index.php?title=NML:Realsprites&oldid=4044’