Difference between revisions of "NML:Objects"
Andythenorth (talk | contribs) (→Object IDs: updated to reflect 64000 objects in OpenTTD 14.0) |
|||
Line 307: | Line 307: | ||
| 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") << 8) <nowiki>|</nowiki> CB_RESULT_NEXT_FRAME;</code>). |
| 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") << 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. |
* <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 |
||
Line 314: | Line 315: | ||
* <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">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. |
* <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 |
Latest revision as of 13:19, 2 August 2024
Vehicles, Stations, Canals, Bridges, Towns, Houses, Industries (Tiles), Cargos, Airports+Tiles, Objects, Railtypes, Roadtypes, Tramtypes, Terrain
- common props | vars | CBs
- train | roadveh | ship | aircr props
- common variables
- industry props | vars | CBs
- tile props | vars | CBs
- airport props | vars | CBs
- tile props | vars | CBs
Object IDs
OpenTTD supports 64000 object types per game, and 255 object IDs per grf file.
14.0 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) | |
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 | ||
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 | 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 | 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)
|
1.1 The view of the particular object. See also the |
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) | 1.4 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) | ||
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 |
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 |
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; ).
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.
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.
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 |
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 |
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) |