Newgrf Airports Documentation

From PikkaWiki
(Difference between revisions)
Jump to: navigation, search
(statemachine callback)
Line 71: Line 71:
 
==Callbacks for Airports==
 
==Callbacks for Airports==
  
===statemachine callback===
+
===state machine callback===
The statemachine callback is called when an aircraft wants to leave a node.  It returns 15 bits, with the 3rd nibble containing the following flags:
+
The state machine callback is called when an aircraft wants to leave a node.  It returns 15 bits, with the 3rd nibble containing the following flags:
  
 
*0 = fly/taxi to the node specified in the low byte
 
*0 = fly/taxi to the node specified in the low byte
Line 82: Line 82:
 
*C = throw the alert message specified in the low byte, change plan to "heading for a hangar" and reiterate
 
*C = throw the alert message specified in the low byte, change plan to "heading for a hangar" and reiterate
 
*D = throw the alert message specified in the low byte, change plan to "heading for an exit" and reiterate
 
*D = throw the alert message specified in the low byte, change plan to "heading for an exit" and reiterate
*E = throw the alert message specified in the low byte and stop the aircraft (if it's on the ground) or leave the statemachine and move to the next order (if it's in the air)
+
*E = throw the alert message specified in the low byte and stop the aircraft (if it's on the ground) or leave the state machine and move to the next order (if it's in the air)
*F = leave the statemachine and move to the next order
+
*F = leave the state machine and move to the next order
  
 
(note: stopping the aircraft is probably not a good idea unless the aircraft is in a hangar!)
 
(note: stopping the aircraft is probably not a good idea unless the aircraft is in a hangar!)

Revision as of 04:36, 10 April 2009

This is a proposed spec only

This is a proposal for a newgrf airports spec. Whereas the current spec being worked on includes a full state machine, this one attempts to cut as much "hard code" out as possible, leaving a lightweight callback system which is, hopefully, both flexible and powerful, while being as simple as possible to implement.

In many ways, you could see this as my attempt to contribute to newgrf airports, since I can't/don't write OTTD patches, but I do write newgrfs. By moving as much codewriting into newgrf as possible, hopefully we can see newgrf airports included sooner than they otherwise would be.

Premise

This spec treats airports in a similar way to industries; it divides them into "airport tiles", which are the graphical component, and an "airport", which contains the logic. The state machine consists of a list of node positions held in the airport, and a callback that is run when an aircraft interacts with them.

Contents

Airport Tiles

Airport tiles are the graphical component of the airport. They have no direct interaction or effect on the state machine on or aircraft.

Action 0 Airport Tiles

  • Land shape flags
  • Animation information
  • Animation speed

as per Properties for industry tiles 0D, 0F and 10

  • Tile Subname string (ie, clicking ? on this tile will give you "AirportName (TileSubname)")
  • Hangar #: Clicking on this tile will open the hangar window or create a hangar order.

Action 2 Airport Tiles

as per Action 2 for houses and industry tiles

Var Action 2 Airport Tiles

as per Variational Action 2 Variables for Industry Tiles, except of course "industry" -> "airport".

Callbacks for Airport Tiles

  • Next animation frame (1A/26/141)
  • Animation control (1B/25/140)
  • Custom shape check (2F)
  • Decide drawing default foundations (30)
  • Disable autosloping for industry tiles (3C)

Airports

Airports are the logical component of the airport. The airport contains the state machine.

Action 0 Airports

  • Small/Large/Helipad/Oilrig (note: for backwards compatibility with vehicle var 44)
  • Years available
  • Catchment area
  • Noise level
  • Text string to show in the build list
  • Cost per new tile when building
  • Cost per overbuilt tile when building
  • Yearly facility maintanance cost (possibly ?)
  • Station name: four text IDs to use as station names if available, otherwise defaults to the old "x Airport" or "x Anystationname".
  • Tile array similar to Industry Property 0A
  • Node array. Each node has an x,y,z position, and a flag byte (hangar, contact point, loading bay) used for overbuilding, buying/selling aircraft in the hangar and, in the case of the contact point(s), aircraft interception from outside the state machine.

Action 4 Airports

  • Name
  • Class (?)

Action 2 Airports

The icon to show in the build list.

Var Action 2 Airports

  • Airport type ID
  • Year built
  • Days since an aircraft last arrived or was loading at any node
  • Days since an aircraft last arrived or was loading at a specific node (60+)
  • Quantity of passengers waiting at the airport
  • Quantity of mail waiting at the airport
  • Quantity and ID of most common other cargo waiting at the airport
  • Variable 7C, 16 4-byte slots of persistent data

Callbacks for Airports

state machine callback

The state machine callback is called when an aircraft wants to leave a node. It returns 15 bits, with the 3rd nibble containing the following flags:

  • 0 = fly/taxi to the node specified in the low byte
  • 1 = change the movement state to the value specified in the low byte and reiterate
  • 2 = turn to the heading specified in the low byte and wait for 16 ticks before reiterating
  • 8 = begin loading/unloading
  • 9 = service the aircraft (at a non-hangar node) and reiterate
  • A = play the sound effect specified in the low byte and reiterate
  • C = throw the alert message specified in the low byte, change plan to "heading for a hangar" and reiterate
  • D = throw the alert message specified in the low byte, change plan to "heading for an exit" and reiterate
  • E = throw the alert message specified in the low byte and stop the aircraft (if it's on the ground) or leave the state machine and move to the next order (if it's in the air)
  • F = leave the state machine and move to the next order

(note: stopping the aircraft is probably not a good idea unless the aircraft is in a hangar!)

Var 10 contains the number of the node that was triggered. Var 11 (or, possibly, a new aircraft variable) contains information on the aircraft's current plan:

  • 0 = heading for a bay
  • 1 = heading for a hangar
  • 2 = heading for a hangar (for servicing only)
  • 3 = heading for an exit
  • 10 = this is a reiteration

Type 82 within the callback gets the variables of the aircraft which triggered the callback. This callback + Variable 7C completely replaces the hardcoded state machine!!

Aircraft

Aircraft gain Variable 7C, and an additional property to provide information to the airport state machine.

Action 0 Aircraft

Basic aircraft information.

A byte-sized property consisting of:

  • 01-0F = runway length required
  • 10 = large aircraft
  • 20 = seaplane (only)
  • 40 = amphibious
  • 80 = special aircraft (airport may want to send it to a special bay/apron).

This property goes into 'uu' in Vehicle Variable 42.

Overbuilding

Airports can be overbuilt like stations, even if aircraft are currently on the airport. Building a new airport tile over an existing airport tile can have a different cost from building one on empty ground (see airport action 0s above). When an airport is overbuilt, the airport's persistent data variables are reset, and the following happens to the aircraft on the airport:

  • All aircraft currently loading will abort loading, have their plan changed to "heading for a bay", will be placed in the same bay number of the new airport (if it exists) or in a random bay (if their current bay doesn't exist), and will then run the state machine callback to lock themselves in. Loading aircraft that don't fit will be moved to the first defined hangar.
  • All other aircraft on the ground will be moved to the airport's first defined hangar.
  • All aircraft in the air will move to the first defined contact point.

If the airport wants to move aircraft to a hangar but doesn't have one, the overbuilding will fail.

Example Airports

To follow. ;)

Personal tools