Difference between revisions of "NML:Airports"

From GRFSpecs
Jump to navigationJump to search
(some content not displayed due to wiki not liking | in normal text.)
(grf -> airport in tile check)
 
(17 intermediate revisions by 6 users not shown)
Line 3: Line 3:
 
Airports and airport tiles can only be defined in OpenTTD {{ottd|1.1|r19459}} or later.
 
Airports and airport tiles can only be defined in OpenTTD {{ottd|1.1|r19459}} or later.
   
  +
==Airport (tile) IDs==
  +
Airport and airport tile IDs are local to the NewGRF, you are free to choose any ID in the 0..255-range. For airport tiles, you should start your item definition with the 'substitute'-property, which allocates a new airport tile. The value of this property should be the ID of a [[AirportTileDefaultProps|default airport tile]], which will be used instead of your item if it is not available for whatever reason (for example, missing NewGRF).
  +
  +
Furthermore, you can set the 'override'-property, which will cause the existing airport tile to be replaced with your item. For airports, there only is an 'override'-property, which acts as a combined substitute and override.
   
 
==Airport properties==
 
==Airport properties==
   
{| class="t"
+
{| class="wikitable sortable"
 
! name
 
! name
 
! value range
 
! value range
 
! comment
 
! comment
|-
 
| name
 
| string
 
|
 
{{ottd|1.1|r19459}} Name of the airport
 
 
|-
 
|-
 
| override
 
| override
 
|
 
|
 
|
 
|
{{ottd|1.1|r19459}} the id of airport to replace / override
+
{{ottd|1.1|r19459}} The id of airport to replace / override, see [[AirportTypes]]. '''This property ''must'' be set first, before any other properties or graphics.'''
 
|-
 
|-
 
| layouts
 
| layouts
Line 25: Line 24:
 
|
 
|
 
{{ottd|1.1|r20377}}
 
{{ottd|1.1|r20377}}
 
|-
 
| name
 
| string
 
|
 
{{ottd|1.1|r19459}} Name of the airport
 
|-
 
|-
 
| years_available
 
| years_available
 
| [start year, last year]
 
| [start year, last year]
 
|
 
|
{{ottd|1.1|r19459}} list of the availablility years: first and last year it can be built
+
{{ottd|1.1|r19459}} List of the availablility years: first and last year it can be built
 
|-
 
|-
 
| ttd_airport-type
 
| ttd_airport-type
 
| 0 ... 3
 
| 0 ... 3
 
|
 
|
{{ottd|1.1|r19459}} substitute TTDPatch airport type
+
{{ottd|1.1|r19459}} Substitute TTDPatch airport type
 
|-
 
|-
 
| catchment_area
 
| catchment_area
 
|
 
|
 
|
 
|
{{ottd|1.1|r19459}} catchment area of the airport in tiles around its perimeter
+
{{ottd|1.1|r19459}} Catchment area of the airport in tiles around its perimeter
 
|-
 
|-
 
| noise_level
 
| noise_level
 
|
 
|
 
|
 
|
{{ottd|1.1|r19459}} noise generation of this airport
+
{{ottd|1.1|r19459}} Noise generation of this airport
 
|-
  +
| maintenance_cost
 
|
  +
|
  +
{{ottd|1.2|r23415}} Maintenance cost factor for this airport
 
|}
 
|}
 
   
 
==Airport tile properties==
 
==Airport tile properties==
   
{| class="t"
+
{| class="wikitable sortable"
 
! name
 
! name
 
! value range
 
! value range
Line 58: Line 66:
 
|
 
|
 
|
 
|
{{ottd|1.1|r19204}} the id of airport tile to override
+
{{ottd|1.1|r19204}} The id of airport tile to override, see [[AirportTypes]]. '''This property ''must'' be set first, before any other properties or graphics.'''
 
|-
 
|-
 
| substitute
 
| substitute
 
|
 
|
 
|
 
|
{{ottd|1.1|r19204}} the id of airport tile to replace
+
{{ottd|1.1|r19204}} The id of airport tile to replace
 
|-
 
|-
 
| callback_flags
 
| callback_flags
Line 71: Line 79:
 
|-
 
|-
 
| animation_info
 
| animation_info
  +
| Array [ANIMATION_XXX, frame-count]
|
 
  +
|{{ottd|1.1|r19204}} XXX = [LOOPING <nowiki>|</nowiki> NON_LOOPING], 1..253 frames
|
 
{{ottd|1.1|r19204}}
 
 
|-
 
|-
 
| animation_speed
 
| animation_speed
 
|
 
|
 
|
 
|
{{ottd|1.1|r19204}} see [[NML:Animation speed|speed settings]]
+
{{ottd|1.1|r19204}} See [[NML:Animation speed|speed settings]]
 
|-
 
|-
 
| animation_triggers
 
| animation_triggers
Line 85: Line 92:
 
{{ottd|1.1|r19204}} Bitmask of triggers that will trigger the <code style="color:darkgreen">anim_control</code> callback, see the [[#Animation triggers|table]] below.
 
{{ottd|1.1|r19204}} Bitmask of triggers that will trigger the <code style="color:darkgreen">anim_control</code> callback, see the [[#Animation triggers|table]] below.
 
|}
 
|}
 
   
 
==Airport variables==
 
==Airport variables==
  +
  +
A number of variables are shared between airports and stations. These are listed on the [[NML:Stations#Base station variables|stations]] page.
   
 
{| class="t"
 
{| class="t"
Line 99: Line 107:
 
{{ottd|1.1|r20364}} Layout number of the airport (index in the layouts array)
 
{{ottd|1.1|r20364}} Layout number of the airport (index in the layouts array)
 
|}
 
|}
 
   
 
==Airport tile variables==
 
==Airport tile variables==
   
{| class="t"
+
{| class="wikitable sortable"
 
! name
 
! name
 
! value range
 
! value range
Line 132: Line 139:
 
|
 
|
 
|
 
|
  +
|-
  +
| random_bits_station
  +
| 0..65535
  +
| 16 random bits, shared between all station parts (rail station parts, airports tiles, ...)
  +
|-
  +
| random_bits_tile
  +
| 0..15
  +
| 4 random bits, specific to this station tile.
 
|}
 
|}
   
Line 137: Line 152:
 
The following variables require a signed x,y offset as parameters. The offset is relative to the current tile. Offset 0,0 means the current tile.
 
The following variables require a signed x,y offset as parameters. The offset is relative to the current tile. Offset 0,0 means the current tile.
   
{| class="t"
+
{| class="wikitable sortable"
 
! name
 
! name
 
! value range
 
! value range
Line 178: Line 193:
 
| nearby_tile_airporttile_id
 
| nearby_tile_airporttile_id
 
| 0x00aa, 0xFFbb, 0xFFFE or 0xFFFF
 
| 0x00aa, 0xFFbb, 0xFFFE or 0xFFFF
| 0x00aa: The tile is an airport tile that is part of this GRF, the tile id is aa.<br /> 0xFFbb: The tile is an original airport tile with id bb.<br /> 0xFFFE: The tile is an airport tile defined in another GRF.<br /> 0xFFFF: The tile is not an airport tile or it belongs to another GRF.
+
| 0x00aa: The tile is an airport tile that is part of this GRF, the tile id is aa.<br /> 0xFFbb: The tile is an original airport tile with id bb.<br /> 0xFFFE: The tile is an airport tile defined in another GRF.<br /> 0xFFFF: The tile is not an airport tile or it belongs to another airport.
 
|}
 
|}
 
   
 
==Airport callbacks==
 
==Airport callbacks==
   
{| class="t"
+
{| class="wikitable sortable"
 
! callback
 
! callback
 
! return value
 
! return value
Line 207: Line 221:
 
==Airport tile callbacks==
 
==Airport tile callbacks==
   
{| class="t"
+
{| class="wikitable sortable"
 
! callback
 
! callback
 
! return value
 
! return value
Line 218: Line 232:
 
| 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. 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.
  +
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits.
 
|-
 
|-
 
| anim_control
 
| anim_control
 
| Next animation frame or CB_RESULT_XXX
 
| Next animation frame or CB_RESULT_XXX
 
|
 
|
Called whenever an 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. <code style="color:darkgreen">extra_callback_info1</code> contains random bits. Returning a sound effect in the high byte will cause that sound effect to be played. <code style="color:darkgreen">extra_callback_info2</code> contains the reason to trigger the animation, see the [[#Animation triggers|table]] below. Note that you need to enable the wanted triggers in the <code style="color:darkgreen">animation_triggers</code> property.
+
Called whenever an 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.
  +
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Reason for callback trigger, see the [[#Animation triggers|table]] below. Note that you need to enable the wanted triggers in the <code style="color:darkgreen">animation_triggers</code> property.
 
|-
 
|-
 
| anim_speed
 
| anim_speed
Line 237: Line 254:
 
===Animation triggers===
 
===Animation triggers===
   
{| class="t"
+
{| class="wikitable sortable"
 
! Animation trigger
 
! Animation trigger
 
! Description
 
! Description
Line 255: Line 272:
 
| ANIM_TRIGGER_APT_250_TICKS
 
| ANIM_TRIGGER_APT_250_TICKS
 
| Every 250 ticks (all tiles at the same time)
 
| Every 250 ticks (all tiles at the same time)
  +
|-
  +
| ANIM_TRIGGER_APT_AIRPLANE_LANDS
  +
| {{ottd|1.9}} Triggered when an airplane (not a helicopter!) lands at airport (single tile only)
 
|}
 
|}

Latest revision as of 01:34, 24 September 2023

Props, Vars and CBs

Airports and airport tiles can only be defined in OpenTTD Supported by OpenTTD 1.1 (r19459)1.1 or later.

Airport (tile) IDs

Airport and airport tile IDs are local to the NewGRF, you are free to choose any ID in the 0..255-range. For airport tiles, you should start your item definition with the 'substitute'-property, which allocates a new airport tile. The value of this property should be the ID of a default airport tile, which will be used instead of your item if it is not available for whatever reason (for example, missing NewGRF).

Furthermore, you can set the 'override'-property, which will cause the existing airport tile to be replaced with your item. For airports, there only is an 'override'-property, which acts as a combined substitute and override.

Airport properties

name value range comment
override

Supported by OpenTTD 1.1 (r19459)1.1 The id of airport to replace / override, see AirportTypes. This property must be set first, before any other properties or graphics.

layouts list of layouts

Supported by OpenTTD 1.1 (r20377)1.1

name string

Supported by OpenTTD 1.1 (r19459)1.1 Name of the airport

years_available [start year, last year]

Supported by OpenTTD 1.1 (r19459)1.1 List of the availablility years: first and last year it can be built

ttd_airport-type 0 ... 3

Supported by OpenTTD 1.1 (r19459)1.1 Substitute TTDPatch airport type

catchment_area

Supported by OpenTTD 1.1 (r19459)1.1 Catchment area of the airport in tiles around its perimeter

noise_level

Supported by OpenTTD 1.1 (r19459)1.1 Noise generation of this airport

maintenance_cost

Supported by OpenTTD 1.2 (r23415)1.2 Maintenance cost factor for this airport

Airport tile properties

name value range comment
override

Supported by OpenTTD 1.1 (r19204)1.1 The id of airport tile to override, see AirportTypes. This property must be set first, before any other properties or graphics.

substitute

Supported by OpenTTD 1.1 (r19204)1.1 The id of airport tile to replace

callback_flags bitmask

Supported by OpenTTD 1.1 (r19204)1.1 Do not set this, unless you use old-style callbacks.

animation_info Array [ANIMATION_XXX, frame-count] Supported by OpenTTD 1.1 (r19204)1.1 XXX = [LOOPING | NON_LOOPING], 1..253 frames
animation_speed

Supported by OpenTTD 1.1 (r19204)1.1 See speed settings

animation_triggers bitmask(ANIM_TRIGGER_APT_XXX, ... )

Supported by OpenTTD 1.1 (r19204)1.1 Bitmask of triggers that will trigger the anim_control callback, see the table below.

Airport variables

A number of variables are shared between airports and stations. These are listed on the stations page.

name value range comment
layout 0 .. (number of layouts - 1)

Supported by OpenTTD 1.1 (r20364)1.1 Layout number of the airport (index in the layouts array)

Airport tile variables

name value range comment
terrain_type
town_radius_group
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.

animation_frame
random_bits_station 0..65535 16 random bits, shared between all station parts (rail station parts, airports tiles, ...)
random_bits_tile 0..15 4 random bits, specific to this station tile.


The following variables require a signed x,y offset as parameters. The offset is relative to the current tile. Offset 0,0 means the current tile.

name value range comment
nearby_tile_slope SLOPE_XXX

See tile slopes for an overview of possible values

nearby_tile_is_same_airport 1 if the tile is part of the same airport, 0 otherwise
nearby_tile_is_water 1 if the tile is water, 0 otherwise
nearby_tile_terrain_type TILETYPE_XX TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
nearby_tile_water_class 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 0..120 The height of the lowest corner of the given tile.
nearby_tile_class

Tile class

nearby_tile_animation_frame 0..255 Animation frame of the given tile
nearby_tile_airporttile_id 0x00aa, 0xFFbb, 0xFFFE or 0xFFFF 0x00aa: The tile is an airport tile that is part of this GRF, the tile id is aa.
0xFFbb: The tile is an original airport tile with id bb.
0xFFFE: The tile is an airport tile defined in another GRF.
0xFFFF: The tile is not an airport tile or it belongs to another airport.

Airport callbacks

callback return value comment
default Sprite set (with 1 sprite) Preview graphics to use in the build menu. One sprite per layout may be given, use the layout to distinguish between layouts.
additional_text String Additional text to show in the buy menu. String may differ per layout, use the layout variable for this.
layout_name String Name of the airport layout in the variable layout

Note that, although the airport isn't built yet, the layout variable is always available and set to the layout the user has selected in the GUI.


Airport tile callbacks

callback return value comment
default Sprite layout Graphics for an airport tile
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.
  • extra_callback_info1: 32 random bits.
anim_control Next animation frame or CB_RESULT_XXX

Called whenever an 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.
  • getbits(extra_callback_info2, 0, 8): Reason for callback trigger, see the table below. Note that you need to enable the wanted triggers in the animation_triggers property.
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.
foundations CB_RESULT[_NO]_FOUNDATIONS Return CB_RESULT_FOUNDATIONS to draw standard foundations (default) or CB_RESULT_NO_FOUNDATIONS to not draw them.


Animation triggers

Animation trigger Description
ANIM_TRIGGER_APT_BUILT Airport is built (all tiles at the same time)
ANIM_TRIGGER_APT_TILELOOP Airport tile is processed in the tileloop (at different times for different tiles)
ANIM_TRIGGER_APT_NEW_CARGO New cargo arrives at the airport (all tiles at the same time)
ANIM_TRIGGER_APT_CARGO_TAKEN All cargo of a cargo type is removed from the airport (all tiles at the same time)
ANIM_TRIGGER_APT_250_TICKS Every 250 ticks (all tiles at the same time)
ANIM_TRIGGER_APT_AIRPLANE_LANDS Supported by OpenTTD 1.91.9 Triggered when an airplane (not a helicopter!) lands at airport (single tile only)