Difference between revisions of "Action2/Sprite Layout"

From GRFSpecs
Jump to navigationJump to search
(version tags)
Line 3: Line 3:
 
!Feature !! Version
 
!Feature !! Version
 
|-
 
|-
|Houses || {{ottdp| |2.5|ttdprev=alpha ?}}
+
|Houses || {{ottdp|0.6|2.5}}
 
|-
 
|-
|Industry Tiles || {{ottdp|0.6| |}}
+
|Industry Tiles || {{ottdp|0.6|2.5}}
 
|-
 
|-
 
|Objects || {{ottdp|1.1|2.6|ttdprev=alpha r2023}}
 
|Objects || {{ottdp|1.1|2.6|ttdprev=alpha r2023}}
Line 54: Line 54:
 
== Extended format using multiple combined sprites ==
 
== Extended format using multiple combined sprites ==
   
Since TTDPatch 2.0.1 alpha 55 vcs 3, houses, industry (and object) tiles support an extended syntax as well, which looks as follows:
+
{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 55 vcs 3}} Since TTDPatch 2.0.1 alpha 55 vcs 3, houses, industry (and object) tiles support an extended syntax as well, which looks as follows:
   
 
<pre><nowiki>&lt;Sprite-number&gt; * &lt;Length&gt; 02 07/09/0F/11 &lt;set-id&gt; &lt;num-sprites&gt; &lt;groundsprite&gt; [&lt;buildingsprite&gt; (&lt;xoffset&gt; &lt;yoffset&gt; &lt;zoffset&gt; &lt;xextent&gt; &lt;yextent&gt; &lt;zextent&gt;) | (&lt;xpixeloffset&gt; &lt;ypixeloffset&gt; 80)] ...</nowiki></pre>
 
<pre><nowiki>&lt;Sprite-number&gt; * &lt;Length&gt; 02 07/09/0F/11 &lt;set-id&gt; &lt;num-sprites&gt; &lt;groundsprite&gt; [&lt;buildingsprite&gt; (&lt;xoffset&gt; &lt;yoffset&gt; &lt;zoffset&gt; &lt;xextent&gt; &lt;yextent&gt; &lt;zextent&gt;) | (&lt;xpixeloffset&gt; &lt;ypixeloffset&gt; 80)] ...</nowiki></pre>
Line 71: Line 71:
 
|&lt;set-id&gt;||B||ID for this definition
 
|&lt;set-id&gt;||B||ID for this definition
 
|-
 
|-
|&lt;num-sprites&gt;||B||Number of following building sprites (the groundsprite mustn't be counted). Allowed range: 1 to 63 (0x01 to 0x3F). {{ottd|1.2|r22518}} Adding 0x40 makes the layout an Advanced Spritelayout with register modifiers (to be documented).
+
|&lt;num-sprites&gt;||B||Number of following building sprites (the groundsprite mustn't be counted). Allowed range: 1 to 63 (0x01 to 0x3F). {{ottdp|1.2|no|ottdrev=r22518}} Adding 0x40 makes the layout an Advanced Spritelayout with register modifiers (to be documented).
 
|-
 
|-
 
|&lt;groundsprite&gt;||D||Ground sprite for the building (see format below)
 
|&lt;groundsprite&gt;||D||Ground sprite for the building (see format below)
Line 113: Line 113:
 
!Bits!!Version!!Content
 
!Bits!!Version!!Content
 
|-
 
|-
|0-13||{{ottdp| | }}||Sprite number, exact meaning specified by bit 31
+
|0-13||{{ottdp|0.6|2.5}}||Sprite number, exact meaning specified by bit 31
 
|-
 
|-
|14-15||{{ottdp| | }}||0: draw sprite normally, 1: draw sprite in transparent mode, 2: recolor sprite
+
|14-15||{{ottdp|0.6|2.5}}||0: draw sprite normally, 1: draw sprite in transparent mode, 2: recolor sprite
 
|-
 
|-
|16-29||{{ottdp| | }}||Color translation special sprite number, see below
+
|16-29||{{ottdp|0.6|2.5}}||Color translation special sprite number, see below
 
|-
 
|-
|30||{{ottdp| |2.5|ttdprev=alpha 57}}||If set, sprite is drawn normally even in transparent buildings mode (for building sprites only)
+
|30||{{ottdp|0.6|2.5|ttdprev=alpha 57}}||If set, sprite is drawn normally even in transparent buildings mode (for building sprites only)
 
|-
 
|-
|31||{{ottdp| | }}||Sprite type, see below
+
|31||{{ottdp|0.6|2.5}}||Sprite type, see below
 
|}
 
|}
   
{{ottdp| |2.5|ttdprev=alpha 57}} Since TTDPatch 2.0.1 alpha 57, the groundsprite value can be zero if no ground sprite is needed (this is useful if you need to draw custom foundations, see [[Callbacks#Decide drawing default foundations 30 14E 150|example]]). Ground sprites are always drawn normally, so bit 30 is ignored for them. Bit 30 may get a different meaning for ground sprites in a later version of TTDPatch, so please leave it zero for now. This does not apply to additional groundsprites using the "&lt;xpixeloffset&gt; &lt;ypixeloffset&gt; 80"-syntax (see above); for these bit 30 has the same meaning as for building sprites.
+
{{ottdp|0.6|2.5|ttdprev=alpha 57}} Since TTDPatch 2.0.1 alpha 57, the groundsprite value can be zero if no ground sprite is needed (this is useful if you need to draw custom foundations, see [[Callbacks#Decide drawing default foundations 30 14E 150|example]]). Ground sprites are always drawn normally, so bit 30 is ignored for them. Bit 30 may get a different meaning for ground sprites in a later version of TTDPatch, so please leave it zero for now. This does not apply to additional groundsprites using the "&lt;xpixeloffset&gt; &lt;ypixeloffset&gt; 80"-syntax (see above); for these bit 30 has the same meaning as for building sprites.
   
 
=== Colour translation special sprite number ===
 
=== Colour translation special sprite number ===

Revision as of 15:10, 15 August 2011

Action2 Sprite Layout

Feature Version
Houses Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5
Industry Tiles Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5
Objects Supported by OpenTTD 1.11.1 Supported by TTDPatch 2.6 (alpha r2023)2.6
Airport Tiles Supported by OpenTTD 1.11.1 Not supported by TTDPatch

This Action2 defines a spritelayout for a tile. There are two formats available:

  • Basic format for a single groundsprite and a single building sprite.
  • Extended format for combining multiple sprites.

Basic format for tiles with a single building sprite

 <Sprite-number> * <Length> 02 07/09/0F/11 <set-id> 00 <groundsprite> <buildingsprite> <xoffset> <yoffset> <xextent> <yextent> <zextent>
Element Size Description
<Sprite-number> dec A sequential sprite number
<length> dec The total number of bytes used in this action
02 B Defines action 02
07/09/0F B feature 7=town buildings, 9=industry tiles, 0F = objects, or 11 airport tiles
<set-id> B ID for this definition
00 B Literal 0 (to distinguish this definition from random/variational lists)
<groundsprite> D Ground sprite for the building (see format below)
<buildingsprite> D The sprite of the building (see format below), can be zero to indicate that no building sprite should be displayed (useful for early building stages)
<xofs> B x-offset from northern tile corner (as a signed byte)
<yofs> B y-offset from northern tile corner (as a signed byte)
<xextent> B size of sprite in x direction
<yextent> B size of sprite in y direction
<zextent> B size of sprite in z direction

In the above, xofs, yofs, xextent, yextent and zextent define the 3D bounding box of the building sprite not including the ground sprite. The z-offset is always zero for buildings (TTD doesn't support floating buildings). Please note that xofs/xextent and yofs/yextent pairs that place the bounding box off the tile are not recommended.

Extended format using multiple combined sprites

Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.5 (2.0.1 alpha 55 vcs 3)2.5 Since TTDPatch 2.0.1 alpha 55 vcs 3, houses, industry (and object) tiles support an extended syntax as well, which looks as follows:

<Sprite-number> * <Length> 02 07/09/0F/11 <set-id> <num-sprites> <groundsprite> [<buildingsprite> (<xoffset> <yoffset> <zoffset> <xextent> <yextent> <zextent>) | (<xpixeloffset> <ypixeloffset> 80)] ...
Element Size Description
<Sprite-number> dec A sequential sprite number
<length> dec The total number of bytes used in this action
02 B Defines action 02
07/09/0F B feature 7=town buildings, 9=industry tiles, 0F = objects, or 11 = airport tiles
<set-id> B ID for this definition
<num-sprites> B Number of following building sprites (the groundsprite mustn't be counted). Allowed range: 1 to 63 (0x01 to 0x3F). Supported by OpenTTD 1.2 (r22518)1.2 Not supported by TTDPatch Adding 0x40 makes the layout an Advanced Spritelayout with register modifiers (to be documented).
<groundsprite> D Ground sprite for the building (see format below)
<buildingsprite> D The sprite to be drawn. Unlike the basic format, zero isn't allowed here.
-- for sprites defining a new bounding box --
<xofs> B x-offset from northern tile corner (as a signed byte)
<yofs> B y-offset from northern tile corner (as a signed byte)
<zofs> B z-offset from the ground
<xextent> B size of sprite in x direction
<yextent> B size of sprite in y direction
<zextent> B size of sprite in z direction
-- for sprites sharing their bounding box with the previous sprite --
<xpixeloffset> B x offset from the top left corner of the previous sprite
<ypixeloffset> B y offset from the top left corner of the previous sprite
80 B a literal 80h byte to distinguish from new-bounding-box definitions

Note: restrictions for sprites sharing their bounding box are the same as explained for station tiles.

Supported by OpenTTD 0.7 (r18959)0.7 Since OpenTTD r18959 you can draw multiple ground sprites for a tile, which is useful if you want to use the usual grass/water/concrete groundtile, but still need to add features to it without using a new bounding box. To do so use the syntax of sprites sharing the previous bounding box, but use it before the first bounding box definition. xpixeloffset and ypixeloffset refer to the usual spot of groundtiles.

Supported by TTDPatch 2.6 (r2313)2.6 The same feature is also partially supported in TTDPatch since TTDPatch 2.6 r2313: TTDPatch ignores the xpixeloffset and ypixeloffset fields and always uses (0,0) for the offset. If you are developing a GRF that needs to be compatible with both OpenTTD and TTDPatch, you should always keep xpixeloffset and ypixeloffset zero to get the same effect in both games.

Sprite definition

The ground and building sprite fields have the following format:

Bits Version Content
0-13 Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5 Sprite number, exact meaning specified by bit 31
14-15 Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5 0: draw sprite normally, 1: draw sprite in transparent mode, 2: recolor sprite
16-29 Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5 Color translation special sprite number, see below
30 Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.5 (alpha 57)2.5 If set, sprite is drawn normally even in transparent buildings mode (for building sprites only)
31 Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5 Sprite type, see below

Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.5 (alpha 57)2.5 Since TTDPatch 2.0.1 alpha 57, the groundsprite value can be zero if no ground sprite is needed (this is useful if you need to draw custom foundations, see example). Ground sprites are always drawn normally, so bit 30 is ignored for them. Bit 30 may get a different meaning for ground sprites in a later version of TTDPatch, so please leave it zero for now. This does not apply to additional groundsprites using the "<xpixeloffset> <ypixeloffset> 80"-syntax (see above); for these bit 30 has the same meaning as for building sprites.

Colour translation special sprite number

This is used only if bits 14 or 15 are nonzero. Bits 16-29 must be the number of a regular TTD sprite containing a colour translation table (see below for available translation tables). For transparent mode, a suitable translation table is needed, e.g. that of TTD´s sprite number 802 (s.b.). See RecolorSprites for more information on the usage of transparent and recolouring sprites.

For houses, if no recolour sprite is given but recolouring is turned on in bits 14-15, there are two possibilities:

  • If you have callback 1E enabled, it is called to determine the colour mapping.
  • If callback 1E is disabled or fails, one of the colours specified in property 17 will be chosen randomly.

See RecolorSprites for a list of available colour translations.

For industry tiles, if this field is zero, but recolouring is turned on in bits 14 or 15, the colour of the containing industry will automatically be applied.

The ground sprite should be exactly the same size and shape as TTD's flat tile. In general, it shouldn't contain anything that has a z-dimension because any non-ground sprite will cover it.

Useful values for ground sprites:

Sprite number (decimal) Contents
3924 bare land
3981 grass
4061 water
4550 snow or desert (depending on climate)
1420 concrete

Please note that all the ground sprite becomes visible in "transparent buildings" mode, so you should draw parts that seem to be hidden as well.

Sprite type

If bit 31 is clear, the bottom 14 bits contain a regular TTD sprite number.

If bit 31 is set, the bottom 14 bits contain a number of a sprite set in the most recent action 1, and the used sprite is decided according to the current construction state and the number of sprites in the set:

  • if there's only one sprite, it's used always
  • if there are two sprites, the first is used during construction (stages 0-2), and the second is used for the finished building (stage 3)
  • if there are three sprites, the first will be used in the beginning of the construction (stage 0), the second will be used during the rest of the construction (stages 1 and 2) and the third will be used for the complete building (stage 3)
  • if there are four or more sprites, the first four will be used for the four construction stages. Sprites after the first four are always ignored.