Difference between revisions of "NML:Objects"

From GRFSpecs
Jump to navigationJump to search
(add nav template)
 
(26 intermediate revisions by 10 users not shown)
Line 1: Line 1:
 
{{NMLNavPropVarCB}}
  
{{NMLNavPropVarCB}}
  +
  +
==Object IDs==
  +
OpenTTD supports 64000 object types per game, and 255 object IDs per grf file.
  +
  +
{{ottdp|14.0|no}} 64000 object IDs per grf file are supported since OpenTTD 14.0.
  +
  +
Object IDs are NewGRF-local and can therefore freely be chosen within the ID ranges.
  +
  +
An object is allocated by setting the 'class'-property, which should therefore be set first.
  +
  +
Overriding the default objects (e.g. transmitter, lighthouse) is not (yet) possible.
   
 
==Object properties==
  
==Object properties==
   
−
{| class="t"
 +
{| class="wikitable sortable"
 
! property
  
! property
 
! value range
  
! value range
Line 11: Line 22:
 
| String literal of length 4
  
| String literal of length 4
 
|
  
|
−
Unlike station classes, there is currently no default yet. You have to set the class ID before any other property or graphics. Characters allowed in the IDs are A-Z, 0-9. While you are technically free to chose your own class, it's highly recommended you stick to one of the [[#Default object classes|default classes]].
 +
Unlike station classes, there is currently no default yet. '''This property ''must'' be set first, before any other properties or graphics.''' Characters allowed in the IDs are A-Z, 0-9. While you are technically free to chose your own class, it's highly recommended you stick to one of the [[#Default object classes|default classes]].
 
|-
  
|-
 
| classname
  
| classname
Line 23: Line 34:
 
| climates_available
  
| climates_available
 
| bitmask(CLIMATE_XXX, CLIMATE_YYY, ...)
  
| bitmask(CLIMATE_XXX, CLIMATE_YYY, ...)
−
| XXX = [TEMPERATE | ARCTIC | TROPICAL | TOYLAND], alternatively NO_CLIMATE or ALL_CLIMATES
 +
| XXX = [TEMPERATE <nowiki>|</nowiki> ARCTIC <nowiki>|</nowiki> TROPICAL <nowiki>|</nowiki> TOYLAND], alternatively NO_CLIMATE or ALL_CLIMATES
 
|-
  
|-
 
| size
  
| size
Line 52: Line 63:
 
| animation_info
  
| animation_info
 
| Array [ANIMATION_XXX, frame-count]
  
| Array [ANIMATION_XXX, frame-count]
−
| XXX = [LOOPING | NON_LOOPING], 1..253 frames
 +
| XXX = [LOOPING <nowiki>|</nowiki> NON_LOOPING], 1..253 frames
 
|-
  
|-
 
| animation_speed
  
| animation_speed
Line 62: Line 73:
 
|
  
|
 
|
  
|
  +
See [[#Animation_triggers|list of animation triggers]]
 
|-
  
|-
 
| callback_flags
  
| callback_flags
Line 75: Line 87:
 
| 1, 2 or 4
  
| 1, 2 or 4
 
| 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. Use variable <code style="color:darkgreen">view</code> to determine the view of a built object.
  
| 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. Use variable <code style="color:darkgreen">view</code> to determine the view of a built object.
  ⚫
|-
  +
| count_per_map256
  +
| 0..255
  +
| {{ottd|1.4|r25878}} Measure for the amount of objects placed on a map of 256^2 tiles. (Comparison: there are 15 transmitter)
 
|}
  
|}
   
 
===Default object classes===
  
===Default object classes===
   
−
Note: the class names listed below are recommended, you still need to set the class name for at least one object in every class or you risk to end up with objects in a class without a name. If multiple NewGRFs define objects for the same class the name defined in the last NewGRF will be used.
 +
Please refer to the [[ObjectLabels|list of object labels]] in the NewGRF Specs. The default class names listed there are recommended, you still need to set the class name for at least one object in every class or you risk to end up with objects in a class without a name. If multiple NewGRFs define objects for the same class the name defined in the last NewGRF will be used.
−  
−
{| class="t"
  
−
! Class
  
−
! Name of the class
  
−
! Description
  
⚫
|-
  
−
| STRU
  
−
| Structures
  
−
| Multitile engineered objects that don't quite fit in as industries, houses or stations - dams etc.
  
⚫
|-
  
−
| INFR
  
−
| Infrastructure
  
−
| lightpoles, communication towers, transmission towers, road signs, etc.
  
⚫
|-
  
−
| BLDG
  
−
| Buildings
  
−
| Normally accomodated by industries, houses or stations but the author feels there are limiting circumstances.
  
⚫
|-
  
−
| NATR
  
−
| Natural objects
  
−
| caves, coral reefs, swamps, etc.
  
⚫
|-
  
−
| PARK
  
−
| Public areas
  
−
| Normally accomodated by towns or industries (tourist stuff ...) but the author feels there are limiting circumstances - Parks, statues, etc.
  
⚫
|-
  
−
| ARTF
  
−
| Artifacts
  
−
| They really don't fit under any of the above - shipwrecks, etc.
  
−
|-
  
−
| MISC
  
−
| Miscellaneous
  
−
| For the author who is unable to accommodate his/her object under any of the previous labels.
  
−
|}
  
   
 
===List of object flags===
  
===List of object flags===
   
−
{| class="t"
 +
{| class="wikitable sortable"
 
! Name
  
! Name
 
! Meaning
  
! Meaning
 
|-
  
|-
 
| OBJ_FLAG_ONLY_SE
  
| OBJ_FLAG_ONLY_SE
−
| Only available in the scenario editor (incompatible with OBJ_FLAG_ONLY_INGAME)
 +
| Only available in the scenario editor (incompatible with OBJ_FLAG_ONLY_INGAME).
 
|-
  
|-
 
| OBJ_FLAG_IRREMOVABLE
  
| OBJ_FLAG_IRREMOVABLE
Line 128: Line 110:
 
|-
  
|-
 
| OBJ_FLAG_ANYTHING_REMOVE
  
| OBJ_FLAG_ANYTHING_REMOVE
−
| Anything can remove this object (owned land behavior)
 +
| Anything can remove this object (owned land behavior).
 
|-
  
|-
 
| OBJ_FLAG_ON_WATER
  
| OBJ_FLAG_ON_WATER
−
| Allow construction of the object on water
 +
| Allow construction of the object on water. Note that if an object is allowed to be built both on land and on water, then it will resist being flooded and will not flood adjacent tiles.
 
|-
  
|-
 
| OBJ_FLAG_REMOVE_IS_INCOME
  
| OBJ_FLAG_REMOVE_IS_INCOME
−
| Removal cost is actually income (owned land behaviour)
 +
| Removal cost is actually income (owned land behaviour).
 
|-
  
|-
 
| OBJ_FLAG_NO_FOUNDATIONS
  
| OBJ_FLAG_NO_FOUNDATIONS
−
| Do not display foundations if on a slope
 +
| Do not display foundations if on a slope.
 
|-
  
|-
 
| OBJ_FLAG_ANIMATED
  
| OBJ_FLAG_ANIMATED
Line 143: Line 125:
 
|-
  
|-
 
| OBJ_FLAG_ONLY_INGAME
  
| OBJ_FLAG_ONLY_INGAME
−
| Only available during game play (incompatible with OBJ_FLAG_ONLY_SE)
 +
| Only available during game play (incompatible with OBJ_FLAG_ONLY_SE).
 
|-
  
|-
 
| OBJ_FLAG_2CC
  
| OBJ_FLAG_2CC
−
| Allows 2cc mapping for objects instead of the default 1cc
 +
| Allows 2cc mapping for objects instead of the default 1cc.
 
|-
  
|-
 
| OBJ_FLAG_NOT_ON_LAND
  
| OBJ_FLAG_NOT_ON_LAND
−
| Disallows construction on land (implies OBJ_FLAG_ON_WATER)
 +
| Disallows construction on land (implies OBJ_FLAG_ON_WATER).
 
|-
  
|-
 
| OBJ_FLAG_DRAW_WATER
  
| OBJ_FLAG_DRAW_WATER
Line 158: Line 140:
 
|-
  
|-
 
| OBJ_FLAG_RANDOM_ANIMATION
  
| OBJ_FLAG_RANDOM_ANIMATION
−
| Random bits in the "next animation frame" callback
 +
| Random bits in the "next animation frame" callback.
  ⚫
|-
  +
| OBJ_FLAG_SCALE_BY_WATER
  +
| Scale amount of objects placed on map generation not by map area, but roughly by the length of the coastline
 
|}
  
|}
−  
   
 
==Object variables==
  
==Object variables==
   
−
{| class="t"
 +
{| class="wikitable sortable"
 
! name
  
! name
 
! value range
  
! value range
Line 196: Line 180:
 
|-
  
|-
 
| animation_frame
  
| animation_frame
−
| 0..255
 +
| 0 .. (frame_count - 1)
  +
| Current animation frame, with the maximum defined in the object's <code style="color:darkgreen">animation_info</code> property.
−
| Current animation frame
  
 
|-
  
|-
  +
| colour
−
| company_colour
  
 
| COLOUR_XXX
  
| COLOUR_XXX
 
|
  
|
Line 222: Line 206:
 
|-
  
|-
 
| view
  
| view
−
| 0 .. <code style="color:darkgreen">num_views</code> - 1
 +
| 0 .. (<code style="color:darkgreen">num_views</code> - 1)
 
|
  
|
 
{{ottd|1.1|r21455}} The view of the particular object. See also the <code style="color:darkgreen">num_views</code> property.
  
{{ottd|1.1|r21455}} The view of the particular object. See also the <code style="color:darkgreen">num_views</code> property.
Line 229: Line 213:
 
Variables that require one or more parameters:
  
Variables that require one or more parameters:
   
−
{| class="t"
 +
{| class="wikitable sortable"
 
! name
  
! name
 
! arguments
  
! arguments
Line 239: Line 223:
 
|
  
|
 
| ID of the object on a nearby tile, if defined by the same grf. OBJECT_TYPE_OTHER_GRF if the object is defined by a different grf (or none at all). OBJECT_TYPE_NO_OBJECT if the tile does not contain an object.
  
| ID of the object on a nearby tile, if defined by the same grf. OBJECT_TYPE_OTHER_GRF if the object is defined by a different grf (or none at all). OBJECT_TYPE_NO_OBJECT if the tile does not contain an object.
  ⚫
|-
  +
| nearby_tile_object_view
  +
| x, y offset (-8..7)
  ⚫
|
  +
| {{ottdp|1.4|no|ottdrev=r26316}} View of the object on a nearby tile, if defined by the same grf.
 
|-
  
|-
 
| nearby_tile_random_bits
  
| nearby_tile_random_bits
 
| x, y offset (-8..7)
  
| x, y offset (-8..7)
 
|
  
|
−
| Random bits of the given tile
 +
| Random bits of the given tile. Only valid for tiles of the same object.
 
|-
  
|-
 
| nearby_tile_slope
  
| nearby_tile_slope
Line 268: Line 257:
 
| x, y offset (-8..7)
  
| x, y offset (-8..7)
 
| WATER_CLASS_XXX
  
| WATER_CLASS_XXX
−
| XXX = [NONE | SEA | CANAL | RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> is 0 may still have a water class, e.g. industry tiles with water beneath them.
 +
| XXX = [NONE <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> is 0 may still have a water class, e.g. industry tiles with water beneath them.
 
|-
  
|-
 
| nearby_tile_height
  
| nearby_tile_height
Line 284: Line 273:
 
| x, y offset (-8..7)
  
| x, y offset (-8..7)
 
|
  
|
−
| See animation_frame
 +
| See animation_frame. Only valid for tiles of the same object.
 
|-
  
|-
 
| object_count
  
| object_count
Line 298: Line 287:
 
Manhattan distance to the closest object of the given type. Grfid is the grfid of the newgrf you want to check the minimum object distance of (default is current grf). Use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">str2number()</code> to convert a grfid to its numeric representation. If the given object type is not yet built, this will return 0xFFFF
  
Manhattan distance to the closest object of the given type. Grfid is the grfid of the newgrf you want to check the minimum object distance of (default is current grf). Use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">str2number()</code> to convert a grfid to its numeric representation. If the given object type is not yet built, this will return 0xFFFF
 
|}
  
|}
−  
   
 
==Object callbacks==
  
==Object callbacks==
   
−
{| class="t"
 +
{| class="wikitable sortable"
 
! callback
  
! callback
 
! return value
  
! return value
Line 311: Line 299:
 
| Normal graphics for an object placed on the map
  
| Normal graphics for an object placed on the map
 
|-
  
|-
  ⚫
| purchase <ref name="notyetbuilt">These callbacks are called when the object is not yet built, so object- specific variables cannot be accessed. Trying to do so will result in undefined behaviour.</ref>
−
| purchase*
  
 
| Sprite layout
  
| Sprite layout
 
| Graphics shown in the build menu
  
| Graphics shown in the build menu
Line 317: Line 305:
 
| anim_next_frame
  
| anim_next_frame
 
| Next animation frame or CB_RESULT_XXX
  
| Next animation frame or CB_RESULT_XXX
−
| Called for every animation frame, returns the next frame to display. Alternatively, return CB_RESULT_NEXT_FRAME or CB_RESULT_STOP_ANIMATION to show the next frame or stop animation, respectively. <code style="color:darkgreen">extra_callback_info1</code> contains random bits if the object flag OBJ_FLAG_RANDOM_ANIMATION is set. Returning a sound effect in the high byte will cause that sound effect to be played.
 +
| Called for every animation frame, returns the next frame to display. Alternatively, return CB_RESULT_NEXT_FRAME or CB_RESULT_STOP_ANIMATION to show the next frame or stop animation, respectively. Returning a sound effect in the high byte will cause that sound effect to be played (e.g. <code>return (sound("mysound.wav") &lt;&lt; 8) <nowiki>|</nowiki> CB_RESULT_NEXT_FRAME;</code>).
  +
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits, if the object flag OBJ_FLAG_RANDOM_ANIMATION is set.
  +
Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.
 
|-
  
|-
 
| anim_control
  
| anim_control
 
| Next animation frame or CB_RESULT_XXX
  
| Next animation frame or CB_RESULT_XXX
 
|
  
|
−
Called whenever an object animation trigger happens. Return the animation frame to show, or CB_RESULT_XXX with XXX = [CB_RESULT_START_ANIMATION | STOP_ANIMATION | DO_NOTHING] to respectively start the animation in its current frame, stop the animation or do nothing. <code style="color:darkgreen">extra_callback_info1</code> contains random bits if the object flag OBJ_FLAG_RANDOM_ANIMATION is set. <code style="color:darkgreen">extra_callback_info2</code> contains the reason to trigger the animation, see the [[#Animation triggers| table]] below. Returning a sound effect in the high byte will cause that sound effect to be played.
 +
Called whenever an object animation trigger happens. Return the animation frame to show, or CB_RESULT_XXX with XXX = [CB_RESULT_START_ANIMATION <nowiki>|</nowiki> STOP_ANIMATION <nowiki>|</nowiki> DO_NOTHING] to respectively start the animation in its current frame, stop the animation or do nothing. Returning a sound effect in the high byte will cause that sound effect to be played.
  +
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits, if the object flag OBJ_FLAG_RANDOM_ANIMATION is set.
  +
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Reason for the callback trigger, see the [[#Animation triggers| table]] below.
  +
Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.
 
|-
  
|-
 
| anim_speed
  
| anim_speed
Line 331: Line 324:
 
| colour2*16 + colour1
  
| colour2*16 + colour1
 
|
  
|
  +
Called once, just after construction.
−
Called once, just after construction. Variable <code style="color:darkgreen">extra_callback_info1</code> contains the colour scheme of the constructing company in the same format as the return value, or random colours if not available (scenario editor). If OBJ_FLAG_2CC is not set, colour2 is zero. This callback can be used to alter the colour scheme of an object. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible colour values.
 +
* <code style="color:darkgreen">getbits(extra_callback_info1, 0, 8)</code>: Colour scheme of the constructing company in the same format as the return value, or random colours if not available (scenario editor). If OBJ_FLAG_2CC is not set, colour2 is zero.
  +
This callback can be used to alter the colour scheme of an object. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible colour values.
 
|-
  
|-
 
| autoslope
  
| autoslope
Line 337: Line 332:
 
| Return CB_RESULT_AUTOSLOPE to allow autoslope (altering the ground below a tile) or CB_RESULT_NO_AUTOSLOPE to disallow it.
  
| Return CB_RESULT_AUTOSLOPE to allow autoslope (altering the ground below a tile) or CB_RESULT_NO_AUTOSLOPE to disallow it.
 
|-
  
|-
−
| tile_check*
 +
| tile_check <ref name="notyetbuilt"/>
  ⚫
|
−
| 0 or 1
  
  +
See the [[#Location check results|table]] below
−
| Return 0 to allow construction or 1 to disallow. Parameters: <code style="color:darkgreen">extra_callback_info1</code> contains the slope in bits 0..3 (see below), all other bits are reserved and should be and-masked out. <code style="color:darkgreen">extra_callback_info2</code> contains the location of the tile within the object as 16*y + x. Note: NFO allows more specific error messages, NML does not yet support this.
  
  ⚫
|
  +
* <code style="color:darkgreen">getbits(extra_callback_info1, 0, 5)</code>: Tile slope, see below
  +
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: The location of the tile within the object as 16*y + x.
  +
If this callback is not implemented or fails, the default behaviour is to allow building the object if it can be placed on a flat surface. This means that steep slopes are not allowed and that the highest corner of each tile of a multi-tile object should have the same height. Additionally, all tiles must be flat if "build on slopes" is disabled.
 
|-
  
|-
−
| additional_text*
 +
| additional_text <ref name="notyetbuilt"/>
 
| String
  
| String
 
| Additional text to show in the purchase menu
  
| Additional text to show in the purchase menu
 
|}
  
|}
   
  +
<references/>
⚫
<nowiki>* These callbacks are called when the object is not yet built, so object- specific variables cannot be accessed. Trying to do so will result in undefined behaviour.</nowiki>
  
  +
  +
{{NML:LocationCheckResults}}
   
 
===Animation triggers===
  
===Animation triggers===
   
−
{| class="t"
 +
{| class="wikitable sortable"
 
! Animation trigger
  
! Animation trigger
 
! Description
  
! Description

Latest revision as of 13:19, 2 August 2024

Props, Vars and CBs

Object IDs

OpenTTD supports 64000 object types per game, and 255 object IDs per grf file.

Supported by OpenTTD 14.014.0 Not supported by TTDPatch 64000 object IDs per grf file are supported since OpenTTD 14.0.

Object IDs are NewGRF-local and can therefore freely be chosen within the ID ranges.

An object is allocated by setting the 'class'-property, which should therefore be set first.

Overriding the default objects (e.g. transmitter, lighthouse) is not (yet) possible.

Object properties

property value range comment
class String literal of length 4

Unlike station classes, there is currently no default yet. This property must be set first, before any other properties or graphics. Characters allowed in the IDs are A-Z, 0-9. While you are technically free to chose your own class, it's highly recommended you stick to one of the default classes.

classname string You only need to set this for one object in every class.
name string
climates_available bitmask(CLIMATE_XXX, CLIMATE_YYY, ...) XXX = [TEMPERATE | ARCTIC | TROPICAL | TOYLAND], alternatively NO_CLIMATE or ALL_CLIMATES
size [x, y] Size in x and y direction. Both x and y must be compiletime constants
build_cost_multiplier multiplicator to the base purchase cost
remove_cost_multiplier multiplicator to the base removal cost
introduction_date date The date this object becomes available to build.
end_of_life_date date The last date this object is buildable. Must be at least 365 days after introduction_date
object_flags bitmask(OBJ_FLAG_XXX, OBJ_FLAG_YYY)

See list of object flags

animation_info Array [ANIMATION_XXX, frame-count] XXX = [LOOPING | NON_LOOPING], 1..253 frames
animation_speed 0..16

Speed of animation, see animation speed table for the meaning of the values.

animation_triggers

See list of animation triggers

callback_flags bitmask(OBJ_CBF_XXX, OBJ_CBF_YYY)

Do not set this, unless you use old-style callbacks.

height 0..255 Height of the object / 8. For example if your object is 16 pixels height you should set height 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" * 8. The property is also used to determine how high a bridge must be if it is allowed by the bit in object_flags.
num_views 1, 2 or 4 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. Use variable view to determine the view of a built object.
count_per_map256 0..255 Supported by OpenTTD 1.4 (r25878)1.4 Measure for the amount of objects placed on a map of 256^2 tiles. (Comparison: there are 15 transmitter)

Default object classes

Please refer to the list of object labels in the NewGRF Specs. The default class names listed there are recommended, you still need to set the class name for at least one object in every class or you risk to end up with objects in a class without a name. If multiple NewGRFs define objects for the same class the name defined in the last NewGRF will be used.

List of object flags

Name Meaning
OBJ_FLAG_ONLY_SE Only available in the scenario editor (incompatible with OBJ_FLAG_ONLY_INGAME).
OBJ_FLAG_IRREMOVABLE Object cannot be removed with the normal dynamite tool. In OpenTTD you can only remove the object with the magic bulldozer cheat, in TTDPatch you can remove it by holding ctrl while using the bulldozer tool. The cost of removing this object is multiplied by 25.
OBJ_FLAG_ANYTHING_REMOVE Anything can remove this object (owned land behavior).
OBJ_FLAG_ON_WATER Allow construction of the object on water. Note that if an object is allowed to be built both on land and on water, then it will resist being flooded and will not flood adjacent tiles.
OBJ_FLAG_REMOVE_IS_INCOME Removal cost is actually income (owned land behaviour).
OBJ_FLAG_NO_FOUNDATIONS Do not display foundations if on a slope.
OBJ_FLAG_ANIMATED Setting this flag will allow the object's animation counter to be increased, must be set if you plan to make use of animations.
OBJ_FLAG_ONLY_INGAME Only available during game play (incompatible with OBJ_FLAG_ONLY_SE).
OBJ_FLAG_2CC Allows 2cc mapping for objects instead of the default 1cc.
OBJ_FLAG_NOT_ON_LAND Disallows construction on land (implies OBJ_FLAG_ON_WATER).
OBJ_FLAG_DRAW_WATER Draws the water under the object. 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.
OBJ_FLAG_ALLOW_BRIDGE Allow bridge over the object taking the building height into account.
OBJ_FLAG_RANDOM_ANIMATION Random bits in the "next animation frame" callback.
OBJ_FLAG_SCALE_BY_WATER Scale amount of objects placed on map generation not by map area, but roughly by the length of the coastline

Object variables

name value range comment
relative_x 0..255 X-coordinate (top right -> bottom left) of the tile relative to the northernmost tile.
relative_y 0..255 Y-coordinate (top left -> bottom right) of the tile relative to the northernmost tile.
relative_pos 0xYYXX

A combination of relative_x and relative_y in the format 0xYYXX. Useful if you want to check for a single position. The builtin function relative_coord(x, y) may be useful when making comparisons.

terrain_type TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
tile_slope SLOPE_XXX

See tile slopes for an overview of possible values

build_date The date this object was build.
animation_frame 0 .. (frame_count - 1) Current animation frame, with the maximum defined in the object's animation_info property.
colour COLOUR_XXX

Colour used for the company colour mask. Refer to the table here for possible values.

owner 0..0x10 CompanyID of the owner of the object or 0x10 if it was build in the scenario editor
town_manhattan_dist Manhattan distance to the nearest town
town_euclidean_dist Euclidean distance to the nearest town
town_zone

town zone

The town zone of the current tile. The town zone from the closest town (measured in manhattan distance) is used.
view 0 .. (num_views - 1)

Supported by OpenTTD 1.1 (r21455)1.1 The view of the particular object. See also the num_views property.

Variables that require one or more parameters:

name arguments value range comment
nearby_tile_object_type x, y offset (-8..7) ID of the object on a nearby tile, if defined by the same grf. OBJECT_TYPE_OTHER_GRF if the object is defined by a different grf (or none at all). OBJECT_TYPE_NO_OBJECT if the tile does not contain an object.
nearby_tile_object_view x, y offset (-8..7) Supported by OpenTTD 1.4 (r26316)1.4 Not supported by TTDPatch View of the object on a nearby tile, if defined by the same grf.
nearby_tile_random_bits x, y offset (-8..7) Random bits of the given tile. Only valid for tiles of the same object.
nearby_tile_slope x, y offset (-8..7) See tile_slope
nearby_tile_is_same_object x, y offset (-8..7) 0 .. 1 Is the given tile part of the same object?
nearby_tile_is_water x, y offset (-8..7) 0 .. 1 Is the given tile a water tile?
nearby_tile_terrain_type x, y offset (-8..7) See terrain_type
nearby_tile_water_class x, y offset (-8..7) WATER_CLASS_XXX XXX = [NONE | SEA | CANAL | RIVER] Note that tiles for which nearby_tile_is_water is 0 may still have a water class, e.g. industry tiles with water beneath them.
nearby_tile_height x, y offset (-8..7) 0 .. 120 The minimum height of the given tile. 8 units correspond to one height level
nearby_tile_class x, y offset (-8..7)

Tile class

nearby_tile_animation_frame x, y offset (-8..7) See animation_frame. Only valid for tiles of the same object.
object_count object id [, grfid] 0..0xFFFF

Number of objects with the given object id currently on the map. Grfid is the grfid of the newgrf you want to check the object count of (default is current grf). Use the builtin function str2number() to convert a grfid to its numeric representation.

object_distance object id [, grfid] 0..0xFFFF

Manhattan distance to the closest object of the given type. Grfid is the grfid of the newgrf you want to check the minimum object distance of (default is current grf). Use the builtin function str2number() to convert a grfid to its numeric representation. If the given object type is not yet built, this will return 0xFFFF

Object callbacks

callback return value comment
default Sprite layout Normal graphics for an object placed on the map
purchase [1] Sprite layout Graphics shown in the build menu
anim_next_frame Next animation frame or CB_RESULT_XXX Called for every animation frame, returns the next frame to display. Alternatively, return CB_RESULT_NEXT_FRAME or CB_RESULT_STOP_ANIMATION to show the next frame or stop animation, respectively. Returning a sound effect in the high byte will cause that sound effect to be played (e.g. return (sound("mysound.wav") << 8) | CB_RESULT_NEXT_FRAME;).
  • extra_callback_info1: 32 random bits, if the object flag OBJ_FLAG_RANDOM_ANIMATION is set.

Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.

anim_control Next animation frame or CB_RESULT_XXX

Called whenever an object animation trigger happens. Return the animation frame to show, or CB_RESULT_XXX with XXX = [CB_RESULT_START_ANIMATION | STOP_ANIMATION | DO_NOTHING] to respectively start the animation in its current frame, stop the animation or do nothing. Returning a sound effect in the high byte will cause that sound effect to be played.

  • extra_callback_info1: 32 random bits, if the object flag OBJ_FLAG_RANDOM_ANIMATION is set.
  • getbits(extra_callback_info2, 0, 8): Reason for the callback trigger, see the table below.

Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.

anim_speed 0 .. 16 Decide the time an animation frame should last. Return value is interpreted as (num_ticks = 2^anim_speed), which each tick lasting 30 ms. Avoid using this callback if possible, since it has to be called each tick for every animated tile. This can be used to create animation frames that last between 30 ms and 33 minutes.
colour colour2*16 + colour1

Called once, just after construction.

  • getbits(extra_callback_info1, 0, 8): Colour scheme of the constructing company in the same format as the return value, or random colours if not available (scenario editor). If OBJ_FLAG_2CC is not set, colour2 is zero.

This callback can be used to alter the colour scheme of an object. Refer to the table here for possible colour values.

autoslope CB_RESULT[_NO]_AUTOSLOPE Return CB_RESULT_AUTOSLOPE to allow autoslope (altering the ground below a tile) or CB_RESULT_NO_AUTOSLOPE to disallow it.
tile_check [1]

See the table below

  • getbits(extra_callback_info1, 0, 5): Tile slope, see below
  • getbits(extra_callback_info2, 0, 8): The location of the tile within the object as 16*y + x.

If this callback is not implemented or fails, the default behaviour is to allow building the object if it can be placed on a flat surface. This means that steep slopes are not allowed and that the highest corner of each tile of a multi-tile object should have the same height. Additionally, all tiles must be flat if "build on slopes" is disabled.

additional_text [1] String Additional text to show in the purchase menu
  1. ↑ 1.0 1.1 1.2 These callbacks are called when the object is not yet built, so object- specific variables cannot be accessed. Trying to do so will result in undefined behaviour.

Location check results

The following values can be used as return values for the location_check callback for industries and the tile_check callback for industry tiles and objects.

return value meaning
string(..) Item can't be built, show the string as error message.
CB_RESULT_LOCATION_ALLOW Item can be built.
CB_RESULT_LOCATION_DISALLOW Item can't be built, display the default error message. This is "site unsuitable" for industries and industry tiles, and "land sloped in wrong direction" for objects.
CB_RESULT_LOCATION_DISALLOW_ONLY_RAINFOREST Item can't be built, display the "...can only be built in rainforest areas" error message.
CB_RESULT_LOCATION_DISALLOW_ONLY_DESERT Item can't be built, display the "...can only be built in desert areas" error message.
CB_RESULT_LOCATION_DISALLOW_ONLY_ABOVE_SNOWLINE Item can't be built, display the "...can only be built above the snow-line" error message.
CB_RESULT_LOCATION_DISALLOW_ONLY_BELOW_SNOWLINE Item can't be built, display the "...can only be built below the snow-line" error message.
CB_RESULT_LOCATION_DISALLOW_NOT_ON_OPEN_SEA Item can't be built, display the "...can't build on open sea" error message.
CB_RESULT_LOCATION_DISALLOW_NOT_ON_CANAL Item can't be built, display the "...can't build on canal" error message
CB_RESULT_LOCATION_DISALLOW_NOT_ON_RIVER Item can't be built, display the "...can't build on river" error message.

Animation triggers

Animation trigger Description
ANIM_TRIGGER_OBJ_BUILT Object is built (all tiles at the same time)
ANIM_TRIGGER_OBJ_TILELOOP Object tile is processed in the tileloop (at different times for different tiles)
ANIM_TRIGGER_OBJ_256_TICKS Every 256 ticks (all tiles at the same time)
Retrieved from ‘https://newgrf-specs.tt-wiki.net/index.php?title=NML:Objects&oldid=4816’