Difference between revisions of "NML:Realsprites"
Planetmaker (talk | contribs) m (examples should contain valid code) |
(→Real sprites: Update with all the newly added (32bpp) features) |
||
| Line 3: | Line 3: | ||
== Real sprites == |
== Real sprites == |
||
| − | Several features will need to reference actual graphics from files you created |
+ | 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. |
||
| ⚫ | |||
| + | |||
| ⚫ | |||
{| class="t" |
{| class="t" |
||
| Line 28: | Line 23: | ||
| CROP (default) or NOCROP |
| CROP (default) or NOCROP |
||
| 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. |
||
| + | |} |
||
| + | |||
| + | 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. |
||
|} |
|} |
||
| Line 36: | Line 52: | ||
[0, 0, 64, 31, -31, 0, NOCROP] |
[0, 0, 64, 31, -31, 0, NOCROP] |
||
</pre> |
</pre> |
||
| − | |||
== Templates == |
== Templates == |
||
Revision as of 20:59, 3 March 2012
Vehicles, Stations, Canals, Bridges, Towns, Houses, Industries (Tiles), Cargos, Airports+Tiles, Objects, Railtypes, Roadtypes, Tramtypes, Terrain
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.
As of NML r1654 the 'flags' have only two possible values. When omitted the default value is used.
| Name | Description |
|---|---|
| CROP (default) or NOCROP | Whether to crop the sprites when the -c command line option is set. |
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. |
Example:
[0, 0, 64, 31, -31, 0, NOCROP]
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
...
}
For an example see the spritegroup.
