Difference between revisions of "Action0/Objects"

From GRFSpecs
Jump to navigationJump to search
m (14 revisions)
(Attempt to fix the majority of the formatting and links.)
Line 1: Line 1:
 
 
'''''Action 0 properties for new objects'''''
 
'''''Action 0 properties for new objects'''''
   
Line 6: Line 5:
 
Defining properties of new objects.
 
Defining properties of new objects.
   
  +
==Introduction==
{maketoc}
 
   
 
Unlike vehicles or new stations, most new objects have no real equivalent in TTD.
 
Unlike vehicles or new stations, most new objects have no real equivalent in TTD.
Line 14: Line 13:
 
The property you '''must''' set for each object ID is 08 (in addition to defining an action 3 for it). Also, all object IDs must get their classes in the right order, starting from ID 00 onwards.
 
The property you '''must''' set for each object ID is 08 (in addition to defining an action 3 for it). Also, all object IDs must get their classes in the right order, starting from ID 00 onwards.
   
-=Properties=-
+
==Properties==
   
  +
{|
||Number|Version|Size|Description
 
  +
!Number!!Version!!Size!!Description
  +
|-
  +
|08||a||D||Class label, see below
  +
|-
  +
|09||a||W||Text ID for class
  +
|-
  +
|0A||a||W||Text ID for this object
  +
|-
  +
|0B||a||B||[[Action0General#Climate_availability|Climate availability]]
  +
|-
  +
|0C||a||B||Byte representing size, see below
  +
|-
  +
|0D||a||B||Object build cost factor (sets object removal cost factor as well)
  +
|-
  +
|0E||a||D||Introduction date, see below
  +
|-
  +
|0F||a||D||End of life date, see below
  +
|-
  +
|10||a||W||Object flags, see below
  +
|-
  +
|11||b||W||Animation information
  +
|-
  +
|12||b||B||Animation speed
  +
|-
  +
|13||b||W||Animation triggers
  +
|-
  +
|14||b||B||Object removal cost factor (set after object build cost factor)
  +
|-
  +
|15||b||W||Callback flags, see below
  +
|-
  +
|16||b||B||Height of the building
  +
|-
  +
|17||c||B||Number of object views
  +
|}
   
  +
Check [http://pics.lakie.net/newObject-ActionStructure.png Lakie's Graphical Representation of the newObject Specifications]
08|a|D|Class label, see below
 
 
09|a|W|Text ID for class
 
 
0A|a|W|Text ID for this object
 
 
0B|a|B|[[Action0General#Climate_availability|Climate availability]]
 
 
0C|a|B|Byte representing size, see below
 
 
0D|a|B|Object build cost factor (sets object removal cost factor as well)
 
 
0E|a|D|Introduction date, see below
 
 
0F|a|D|End of life date, see below
 
 
10|a|W|Object flags, see below
 
 
11|b|W|Animation information
 
 
12|b|B|Animation speed
 
 
13|b|W|Animation triggers
 
 
14|b|B|Object removal cost factor (set after object build cost factor)
 
 
15|b|W|Callback flags, see below
 
 
16|b|B|Height of the building
 
 
17|c|B|Number of object views
 
 
||
 
 
Check [http://pics.lakie.net/newObject-ActionStructure.png|Lakie's Graphical Representation of the newObject Specifications|nocache]
 
   
 
The specifications of NewObjects are available since OpenTTD r20670 in TTDPatch since r2340
 
The specifications of NewObjects are available since OpenTTD r20670 in TTDPatch since r2340
   
  +
===Object class (08)===
-=Comments=-
 
 
==Object class (08)==
 
   
Class labels are unique identifiers composed of the letters A-Z and/or the numbers 0-9,  analoguous to [[Action0Stations#Station_class_08_|station class labels]].
+
Class labels are unique identifiers composed of the letters A-Z and/or the numbers 0-9,  analoguous to [[Action0Stations#Station_class_.2808.29|station class labels]].
   
 
Their main use is to combine objects into classes and make them available by the top dropdown list in the object construction window.
 
Their main use is to combine objects into classes and make them available by the top dropdown list in the object construction window.
Line 68: Line 65:
 
Class IDs must be set before any other property.
 
Class IDs must be set before any other property.
   
==Object class text ID (09)==
+
===Object class text ID (09)===
   
 
The text ID for this class (word value). This textid should be either a TTD textid or a D4xx textid (set via D0xx in action4).
 
The text ID for this class (word value). This textid should be either a TTD textid or a D4xx textid (set via D0xx in action4).
Line 74: Line 71:
 
When specifying an object, you don't need to set a class name again if you already did for another one with the same class.
 
When specifying an object, you don't need to set a class name again if you already did for another one with the same class.
   
==Object text ID (0A)==
+
===Object text ID (0A)===
   
 
The text ID for the object for query and selection (word value). Same requirements as for property09.
 
The text ID for the object for query and selection (word value). Same requirements as for property09.
   
==Object size (0C)==
+
===Object size (0C)===
   
 
The object size up to 15x15 tiles.
 
The object size up to 15x15 tiles.
Line 86: Line 83:
 
Note that any value lower than 0x11 will be rejected.
 
Note that any value lower than 0x11 will be rejected.
   
==Build Cost (0D)==
+
===Build Cost (0D)===
   
 
The build cost multiplier. This is multiplied by the number of tiles for evaluation of construction and removal costs of an object.
 
The build cost multiplier. This is multiplied by the number of tiles for evaluation of construction and removal costs of an object.
   
==Introduction date (0E)==
+
===Introduction date (0E)===
   
 
Introduction date of an object, in days since the year 0. This takes account of leap years; divisible by 4, but not 100 unless 400. A start date of 1920-01-01 is obtained with a value of 701265 (51 B3 0A 00). In TTDPatch anything before 1920 is considered to be always available, and it should allow for objects to work past 2044, the date is also the very first date you can build the object.
 
Introduction date of an object, in days since the year 0. This takes account of leap years; divisible by 4, but not 100 unless 400. A start date of 1920-01-01 is obtained with a value of 701265 (51 B3 0A 00). In TTDPatch anything before 1920 is considered to be always available, and it should allow for objects to work past 2044, the date is also the very first date you can build the object.
   
==End of life date (0F)==
+
===End of life date (0F)===
   
 
Last year an object can be build, in days since the year 0. Same requirements as above. Also note that it must be a minimum of a year (365 days) after the introduction date or TTDPatch will ignore it.
 
Last year an object can be build, in days since the year 0. Same requirements as above. Also note that it must be a minimum of a year (365 days) after the introduction date or TTDPatch will ignore it.
   
==Object flags (10)==
+
===Object flags (10)===
   
 
The following flags control object behaviour and are cached for built objects, so changing these flags will have no effect on already constructed objects.
 
The following flags control object behaviour and are cached for built objects, so changing these flags will have no effect on already constructed objects.
   
  +
{|
||Bit|Value|Version|Meaning
 
  +
!Bit!!Value!!Version!!Meaning
 
  +
|-
0|1|a|Only Available in the scenario editor (1)
 
  +
|0||1||a||Only Available in the scenario editor (1)
 
  +
|-
1|2|a|Irremovable (2)
 
  +
|1||2||a||Irremovable (2)
 
  +
|-
2|4|a|Anything Can Remove (owned land behaviour)
 
  +
|2||4||a||Anything Can Remove (owned land behaviour)
 
  +
|-
3|8|a|Allow construction of the object on water
 
  +
|3||8||a||Allow construction of the object on water
 
  +
|-
4|16|a|Removal cost is actually income (owned land behaviour)
 
  +
|4||16||a||Removal cost is actually income (owned land behaviour)
 
  +
|-
5|32|a|Do not display foundations if on a slope
 
  +
|5||32||a||Do not display foundations if on a slope
 
  +
|-
6|64|a|Object has animation (3)
 
  +
|6||64||a||Object has animation (3)
 
  +
|-
7|128|a|Only available during game play (1)
 
  +
|7||128||a||Only available during game play (1)
 
  +
|-
8|256|b|Allows 2cc mapping for objects instead of the default 1cc
 
  +
|8||256||b||Allows 2cc mapping for objects instead of the default 1cc
 
  +
|-
9|512|c|Disallows construction on land (also has bit 3 behaviour)
 
  +
|9||512||c||Disallows construction on land (also has bit 3 behaviour)
 
  +
|-
10|1024|c|Draws the water under the object (4)
 
  +
|10||1024||c||Draws the water under the object (4)
 
  +
|-
11|2048|d|Allow bridge over the object taking the building height into account (5)
 
  +
|11||2048||d||Allow bridge over the object taking the building height into account (5)
 
  +
|-
12|4096|d|Random bits in the "next animation frame" callback||
 
  +
|12||4096||d||Random bits in the "next animation frame" callback
  +
|}
   
 
c - TTDPatch r2331
 
c - TTDPatch r2331
Line 142: Line 141:
 
(5) - Only applies to OpenTTD. TTDPatch does not support bridges over objects yet.
 
(5) - Only applies to OpenTTD. TTDPatch does not support bridges over objects yet.
   
==Animation information (11)==
+
===Animation information (11)===
   
 
The low byte specifies the number of animation frames minus one, so 00 means 1 frame, 01 means 2 frames etc. The maximum number of frames is 256, although you can have some problems if your animation exceeds FD (253) frames. The high byte must be 0 for non-looping animations and 01 for looping animations. Every other value is reserved for future use. In addition, if the whole word contains FFFF, animation is turned off for this object (this is the default value).
 
The low byte specifies the number of animation frames minus one, so 00 means 1 frame, 01 means 2 frames etc. The maximum number of frames is 256, although you can have some problems if your animation exceeds FD (253) frames. The high byte must be 0 for non-looping animations and 01 for looping animations. Every other value is reserved for future use. In addition, if the whole word contains FFFF, animation is turned off for this object (this is the default value).
Line 148: Line 147:
 
Since you can't have properties for individual object tiles, this property applies for every tile of the object. If you don't want to animate some tiles, you should check the current position during [[Callbacks#Animation_control_1B_25_140_|callback 159]] and return FD if the current tile doesn't need to be animated. If you also need animations of different length per tile, you'll have to use [[Callbacks#Next_animation_frame_1A_26_141_|callback 158]] for that.
 
Since you can't have properties for individual object tiles, this property applies for every tile of the object. If you don't want to animate some tiles, you should check the current position during [[Callbacks#Animation_control_1B_25_140_|callback 159]] and return FD if the current tile doesn't need to be animated. If you also need animations of different length per tile, you'll have to use [[Callbacks#Next_animation_frame_1A_26_141_|callback 158]] for that.
   
==Animation speed (12)==
+
===Animation speed (12)===
   
The meaning is the same as for [[Action0Houses#Animation_Speed_1B_|house property 1B]], but the lower limit is 0 instead of 2, so the fastest possible animation changes frames every game tick (27ms). The default value is 0.
+
The meaning is the same as for [[Action0Houses#Animation_Speed_.281B.29|house property 1B]], but the lower limit is 0 instead of 2, so the fastest possible animation changes frames every game tick (27ms). The default value is 0.
   
==Animation triggers (13)==
+
===Animation triggers (13)===
   
 
This is a bit mask of events that should trigger [[Callbacks#Animation_control_1B_25_140_|callback 159]], allowing to change the animation state
 
This is a bit mask of events that should trigger [[Callbacks#Animation_control_1B_25_140_|callback 159]], allowing to change the animation state
   
  +
{|
||Bit|Value|Meaning|Happens on
 
  +
!Bit!!Value!!Meaning!!Happens on
 
  +
|-
0|1|Object is built|all tiles
 
  +
|0||1||Object is built||all tiles
 
  +
|-
1|2|Periodic tile loop|single tile
 
  +
|1||2||Periodic tile loop||single tile
 
  +
|-
2|4|Synchronised periodic tile loop|all tiles||
 
  +
|2||4||Synchronised periodic tile loop||all tiles
  +
|}
   
 
The synchronised periodic tile loop is called directly after the (unsynchronised) periodic tile loop of the northern tile.
 
The synchronised periodic tile loop is called directly after the (unsynchronised) periodic tile loop of the northern tile.
   
==Object removal cost factor (14)==
+
===Object removal cost factor (14)===
   
 
Cost factor for the removal of an object. This must be set after property 0D (object build cost factor) as that overwrites this value.
 
Cost factor for the removal of an object. This must be set after property 0D (object build cost factor) as that overwrites this value.
   
==Callback flags (15)==
+
===Callback flags (15)===
   
 
For objects, the following [[Callbacks|callbacks]] can be defined by setting the corresponding bit in property 15:
 
For objects, the following [[Callbacks|callbacks]] can be defined by setting the corresponding bit in property 15:
   
  +
{|
||Bit|Value|Variable 0C value|Callback
 
  +
!Bit!!Value!!Variable 0C value!!Callback
 
  +
|-
0|1|157|Custom slope check
 
  +
|0||1||157||Custom slope check
 
  +
|-
1|2|158|Decide next animation frame
 
  +
|1||2||158||Decide next animation frame
 
  +
|-
2|4|15A|Decide animation speed
 
  +
|2||4||15A||Decide animation speed
 
  +
|-
3|8|15B|Decide colour of building
 
  +
|3||8||15B||Decide colour of building
 
  +
|-
4|16|15C|Show additional text in the build object window
 
  +
|4||16||15C||Show additional text in the build object window
 
  +
|-
5|32|15D|Allow/disallow autosloping||
 
  +
|5||32||15D||Allow/disallow autosloping
  +
|}
   
==Building height (16)==
+
===Building height (16)===
   
 
Set the height of the building in heightlevels (8 pixels). For example if the structure is 16 pixels high you set this property to 2.
 
Set the height of the building in heightlevels (8 pixels). For example if the structure is 16 pixels high you set this property to 2.
Line 194: Line 197:
 
In OpenTTD this property is used to determine the height of the build object window; the height for the object preview is set to 32 + "value of property 16" * 8. The property is also uses to determine how high a bridge must be if it is allowed by the bit in property 10.
 
In OpenTTD this property is used to determine the height of the build object window; the height for the object preview is set to 32 + "value of property 16" * 8. The property is also uses to determine how high a bridge must be if it is allowed by the bit in property 10.
   
==Number of views (17)==
+
===Number of views (17)===
   
 
Since TTDPatch nightly r2360 and OpenTTD r21455 objects may have "views", i.e. different graphical representations, e.g. used to show rotated views of an object. Number of views may be 1, 2, or 4. Default value is 1.
 
Since TTDPatch nightly r2360 and OpenTTD r21455 objects may have "views", i.e. different graphical representations, e.g. used to show rotated views of an object. Number of views may be 1, 2, or 4. Default value is 1.
   
For non-square objects, x and y sizes are swapped for odd views. I.e., giving an object size of &nbsp;1*2 (x = 1, y = 2), it will be displayed as 1*2 for num = <nowiki><nowiki>[</nowiki></nowiki>0,2] (x-direction) but as 2*1 for num = <nowiki><nowiki>[</nowiki></nowiki>1,3] (y-direction).
+
For non-square objects, x and y sizes are swapped for odd views. I.e., giving an object size of &nbsp;1*2 (x = 1, y = 2), it will be displayed as 1*2 for num = <nowiki>[</nowiki>0,2] (x-direction) but as 2*1 for num = <nowiki>[</nowiki>1,3] (y-direction).
   
 
Use object varaction2 48 to access particular views of an object.
 
Use object varaction2 48 to access particular views of an object.

Revision as of 20:26, 13 June 2011

Action 0 properties for new objects

Action 0 - Properties for new objects

Defining properties of new objects.

Introduction

Unlike vehicles or new stations, most new objects have no real equivalent in TTD.

The IDs are therefore free to be chosen and will in fact be allocated automatically by the patch. In action 0, you only specify IDs relative to the set, i.e. the ID of the first object type is 00, the second object type is 01 and so on. In total, each game can only have 255 object IDs for all active grf files.

The property you must set for each object ID is 08 (in addition to defining an action 3 for it). Also, all object IDs must get their classes in the right order, starting from ID 00 onwards.

Properties

Number Version Size Description
08 a D Class label, see below
09 a W Text ID for class
0A a W Text ID for this object
0B a B Climate availability
0C a B Byte representing size, see below
0D a B Object build cost factor (sets object removal cost factor as well)
0E a D Introduction date, see below
0F a D End of life date, see below
10 a W Object flags, see below
11 b W Animation information
12 b B Animation speed
13 b W Animation triggers
14 b B Object removal cost factor (set after object build cost factor)
15 b W Callback flags, see below
16 b B Height of the building
17 c B Number of object views

Check Lakie's Graphical Representation of the newObject Specifications

The specifications of NewObjects are available since OpenTTD r20670 in TTDPatch since r2340

Object class (08)

Class labels are unique identifiers composed of the letters A-Z and/or the numbers 0-9,  analoguous to station class labels.

Their main use is to combine objects into classes and make them available by the top dropdown list in the object construction window.

Unlike for stations, there is no default class for objects. Set authors have to specify their own labels, although it is strongly recommended to follow a general scheme to try to avoid confusion.

Class IDs must be set before any other property.

Object class text ID (09)

The text ID for this class (word value). This textid should be either a TTD textid or a D4xx textid (set via D0xx in action4).

When specifying an object, you don't need to set a class name again if you already did for another one with the same class.

Object text ID (0A)

The text ID for the object for query and selection (word value). Same requirements as for property09.

Object size (0C)

The object size up to 15x15 tiles.

This byte value is divided into two nibbles. The first defines the size in y direction and the second defines the size in x (i.e., stored as YX).

Note that any value lower than 0x11 will be rejected.

Build Cost (0D)

The build cost multiplier. This is multiplied by the number of tiles for evaluation of construction and removal costs of an object.

Introduction date (0E)

Introduction date of an object, in days since the year 0. This takes account of leap years; divisible by 4, but not 100 unless 400. A start date of 1920-01-01 is obtained with a value of 701265 (51 B3 0A 00). In TTDPatch anything before 1920 is considered to be always available, and it should allow for objects to work past 2044, the date is also the very first date you can build the object.

End of life date (0F)

Last year an object can be build, in days since the year 0. Same requirements as above. Also note that it must be a minimum of a year (365 days) after the introduction date or TTDPatch will ignore it.

Object flags (10)

The following flags control object behaviour and are cached for built objects, so changing these flags will have no effect on already constructed objects.

Bit Value Version Meaning
0 1 a Only Available in the scenario editor (1)
1 2 a Irremovable (2)
2 4 a Anything Can Remove (owned land behaviour)
3 8 a Allow construction of the object on water
4 16 a Removal cost is actually income (owned land behaviour)
5 32 a Do not display foundations if on a slope
6 64 a Object has animation (3)
7 128 a Only available during game play (1)
8 256 b Allows 2cc mapping for objects instead of the default 1cc
9 512 c Disallows construction on land (also has bit 3 behaviour)
10 1024 c Draws the water under the object (4)
11 2048 d Allow bridge over the object taking the building height into account (5)
12 4096 d Random bits in the "next animation frame" callback

c - TTDPatch r2331

(1) - Note that bits 0 and 7 are incompatible and setting both will make an object completely unavailable.

(2) - Object cannot be removed through normal dynamite, control must be held and the removal cost will be multiplied by 25 (this is the usual behaviour for most class A objects in TTDPatch).

(3) - Setting this flag will allow the object's animation counter to be increased, must be set if you plan to make use of animations. Like stations you must enable animation on a per tile basis by means of the "built tile" trigger and callback 159.

(4) - Only applies when built on top of a water tile, also replaces the ground tile of the object completely. (Does not work when object built on sloped water tiles).

(5) - Only applies to OpenTTD. TTDPatch does not support bridges over objects yet.

Animation information (11)

The low byte specifies the number of animation frames minus one, so 00 means 1 frame, 01 means 2 frames etc. The maximum number of frames is 256, although you can have some problems if your animation exceeds FD (253) frames. The high byte must be 0 for non-looping animations and 01 for looping animations. Every other value is reserved for future use. In addition, if the whole word contains FFFF, animation is turned off for this object (this is the default value).

Since you can't have properties for individual object tiles, this property applies for every tile of the object. If you don't want to animate some tiles, you should check the current position during callback 159 and return FD if the current tile doesn't need to be animated. If you also need animations of different length per tile, you'll have to use callback 158 for that.

Animation speed (12)

The meaning is the same as for house property 1B, but the lower limit is 0 instead of 2, so the fastest possible animation changes frames every game tick (27ms). The default value is 0.

Animation triggers (13)

This is a bit mask of events that should trigger callback 159, allowing to change the animation state

Bit Value Meaning Happens on
0 1 Object is built all tiles
1 2 Periodic tile loop single tile
2 4 Synchronised periodic tile loop all tiles

The synchronised periodic tile loop is called directly after the (unsynchronised) periodic tile loop of the northern tile.

Object removal cost factor (14)

Cost factor for the removal of an object. This must be set after property 0D (object build cost factor) as that overwrites this value.

Callback flags (15)

For objects, the following callbacks can be defined by setting the corresponding bit in property 15:

Bit Value Variable 0C value Callback
0 1 157 Custom slope check
1 2 158 Decide next animation frame
2 4 15A Decide animation speed
3 8 15B Decide colour of building
4 16 15C Show additional text in the build object window
5 32 15D Allow/disallow autosloping

Building height (16)

Set the height of the building in heightlevels (8 pixels). For example if the structure is 16 pixels high you set this property to 2.

In OpenTTD this property is used to determine the height of the build object window; the height for the object preview is set to 32 + "value of property 16" * 8. The property is also uses to determine how high a bridge must be if it is allowed by the bit in property 10.

Number of views (17)

Since TTDPatch nightly r2360 and OpenTTD r21455 objects may have "views", i.e. different graphical representations, e.g. used to show rotated views of an object. Number of views may be 1, 2, or 4. Default value is 1.

For non-square objects, x and y sizes are swapped for odd views. I.e., giving an object size of  1*2 (x = 1, y = 2), it will be displayed as 1*2 for num = [0,2] (x-direction) but as 2*1 for num = [1,3] (y-direction).

Use object varaction2 48 to access particular views of an object.