Callback: AI construction/purchase selection

From GRFSpecs
Revision as of 13:22, 1 April 2012 by Frosch (talk | contribs) (use new grf templates)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

AI construction/purchase selection (18)

This generic feature callback is called for various decisions when the AI is constructing a new route. For example, normally the AI has a hardcoded list of wagons for each cargo type, but with this callback you can make the selection depend on source and destination industries as well as service distance among other things.

Since the vehicle hasn't been bought yet, you cannot use the usual 40+x or 80+x vehicle variables, instead you have the following:

Variable Size Content
80 B cargo type (climate specific, column 3, type B in the cargo type list)
81 B cargo type (climate independent, column 1, type A in the cargo type list)
82 B default selection
83 B source industry type (ID). For new industries the substitute type is returned starting with OpenTTD r20108.[1]
84 B destination industry type (ID). For new industries the substitute type is returned starting with OpenTTD r20108.[1]
85 B distance between source and destination, in (dx+dy)/2
86 B AI construction event
87 B Construction number; for wagons: number of wagon; for stations 0=source station, 1=destination station
88 B Station size in form NL; N=number of platforms, L=length
40 D xxxxxxTT, TT=cargo slot from cargo translation table or same as var.81 if no table, available since r1167/2.5b9
  1. 1.0 1.1 There are two special return values available: 0xFE which indicates an unknown industry type and 0xFF wich indicates a town

The callback will be called for following construction events, stored in variable 86:

Group Feature Var.86 Type Description
Trains 00 00 Check Regular rail engine
01 Check Electric rail engine
02 Check Monorail engine
03 Check Maglev engine
08 Get Regular rail wagon
09 Get Electric rail wagon
0A Get Monorail wagon
0B Get Maglev wagon
0F Get Track type to build
Road Vehicles 01 00 Check Road vehicle
01 Get First road vehicle ID to try
02 Get Number of road vehicles to try
Ships 02 00 Check Ship
01 Get First ship ID to try
02 Get Number of ships to try
Aircraft 03 00 Check Aircraft
Stations 04 00 Get Station ID

Notes:

  • "Check" means to check if it should try to buy this vehicle (with ID in var.82). Return 0 to disallow purchase, or 1 to allow it. If allowed, the computer will buy the highest-cost (or AI rank for train engines) vehicle it can find that is available and has high enough reliability.
  • "Get" means to find out which ID (etc.) to use. The default in var.82 is what it will use if the callback fails.
  • For train engines and aircraft, the AI always checks all available engines.
  • For road vehicles and ships, the AI has a built-in list of vehicles to try, you can use callback event 01 and 02 to change that list.
  • For trains, the track types (0=regular, 1=electric, 2=monorail, 3=maglev) are automatically mapped as appropriate depending on the electrifiedrailways/unifiedmaglev switches. For best results, assume that all four are available. The game will then use the correct one if it is not available.

This callback is "chained", i.e. if a result is not a callback result (high bit is not set), then the request is passed on to the previous generic callback handler, i.e. they are checked in reverse order. This makes it possible to leave certain decisions to the previous handler and allows some cooperation between several .grf files.

GRFv≤7 Note that GRF versions 7 and lower only distinguished zero and non-zero return values for "Check".