| blob | 111474d3de44f2c87a3f687b8f9e8f71c20db95e |
1 /*
2 * This file is part of OpenTTD.
3 * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
4 * OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
5 * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
6 */
8 /**
9 * @page ai_changelog Lists all changes / additions to the API.
10 *
11 * Only new / renamed / deleted api functions will be listed here. A list of
12 * bug fixes can be found in the normal changelog. Note that removed API
13 * functions may still be available if you return an older API version
14 * in GetAPIVersion() in info.nut.
15 *
16 * \b 15.0
17 *
18 * This version is not yet released. The following changes are not set in stone yet.
19 *
20 * API additions:
21 * \li AIEventVehicleCrashed::GetVictims
22 * \li AIEventCompanyRenamed
23 * \li AIEventPresidentRenamed
24 *
25 * Other changes:
26 * \li AIBridge::GetBridgeID renamed to AIBridge::GetBridgeType
27 *
28 * \b 14.0
29 *
30 * API additions:
31 * \li AITown::ROAD_LAYOUT_RANDOM
32 * \li AIVehicle::IsPrimaryVehicle
33 * \li AITileList_StationCoverage
34 * \li AIAirport::GetAirportNumHelipads
35 *
36 * API removals:
37 * \li AIError::ERR_PRECONDITION_TOO_MANY_PARAMETERS, that error is never returned anymore.
38 * \li AIInfo::CONFIG_RANDOM, no longer used.
39 * \li AIInfo::AddSettings random_deviation is no longer used.
40 *
41 * Other changes:
42 * \li AIGroupList accepts an optional filter function
43 * \li AIIndustryList accepts an optional filter function
44 * \li AISignList accepts an optional filter function
45 * \li AISubsidyList accepts an optional filter function
46 * \li AITownList accepts an optional filter function
47 * \li AIVehicleList accepts an optional filter function
48 * \li AIInfo::AddSettings easy_value / medium_value / hard_value are replaced with default_value
49 *
50 * \b 13.0
51 *
52 * API additions:
53 * \li AICargo::GetWeight
54 * \li AIIndustryType::ResolveNewGRFID
55 * \li AIObjectType::ResolveNewGRFID
56 *
57 * Other changes:
58 * \li AIRoad::HasRoadType now correctly checks RoadType against RoadType
59 *
60 * \b 12.0
61 *
62 * API additions:
63 * \li AINewGRF
64 * \li AINewGRFList
65 * \li AIGroup::GetNumVehicles
66 * \li AIMarine::BT_LOCK
67 * \li AIMarine::BT_CANAL
68 * \li AITile::IsSeaTile
69 * \li AITile::IsRiverTile
70 * \li AITile::BT_CLEAR_WATER
71 * \li AIObjectTypeList
72 * \li AIObjectType
73 *
74 * \b 1.11.0
75 *
76 * API additions:
77 * \li AICargo::GetName
78 * \li AIPriorityQueue
79 *
80 * Other changes:
81 * \li AIVehicle::CloneVehicle now correctly returns estimate when short on cash
82 *
83 * \b 1.10.0
84 *
85 * API additions:
86 * \li AIGroup::SetPrimaryColour
87 * \li AIGroup::SetSecondaryColour
88 * \li AIGroup::GetPrimaryColour
89 * \li AIGroup::GetSecondaryColour
90 * \li AIVehicle::BuildVehicleWithRefit
91 * \li AIVehicle::GetBuildWithRefitCapacity
92 * \li AIRoad::GetName
93 * \li AIRoad::RoadVehCanRunOnRoad
94 * \li AIRoad::RoadVehHasPowerOnRoad
95 * \li AIRoad::ConvertRoadType
96 * \li AIRoad::GetMaxSpeed
97 * \li AIEngine::CanRunOnRoad
98 * \li AIEngine::HasPowerOnRoad
99 * \li AIRoadTypeList::RoadTypeList
100 * \li AIEventVehicleAutoReplaced
101 *
102 * Other changes:
103 * \li AITile::DemolishTile works without a selected company
104 *
105 * \b 1.9.0
106 *
107 * API additions:
108 * \li AIAirport::GetMonthlyMaintenanceCost
109 * \li AIGroup::SetParent
110 * \li AIGroup::GetParent
111 * \li AICompany::SetPrimaryLiveryColour
112 * \li AICompany::SetSecondaryLiveryColour
113 * \li AICompany::GetPrimaryLiveryColour
114 * \li AICompany::GetSecondaryLiveryColour
115 *
116 * Other changes:
117 * \li AIBridge::GetName takes one extra parameter to refer the vehicle type
118 * \li AIGroup::CreateGroup gains parent_group_id parameter
119 *
120 * \b 1.8.0
121 *
122 * No changes
123 *
124 * API additions:
125 * \li AIRoad::ERR_ROADTYPE_DISALLOWS_CROSSING
126 *
127 * \b 1.7.0 - 1.7.2
128 *
129 * No changes
130 *
131 * \b 1.6.1 - 1.6.0
132 *
133 * No changes
134 *
135 * \b 1.5.3 - 1.5.1
136 *
137 * No changes
138 *
139 * \b 1.5.0
140 *
141 * API additions:
142 * \li AIList::SwapList
143 * \li AIStation::GetCargoPlanned
144 * \li AIStation::GetCargoPlannedFrom
145 * \li AIStation::GetCargoPlannedFromVia
146 * \li AIStation::GetCargoPlannedVia
147 * \li AIStation::GetCargoWaitingFromVia
148 * \li AIStationList_CargoPlannedByFrom
149 * \li AIStationList_CargoPlannedByVia
150 * \li AIStationList_CargoPlannedFromByVia
151 * \li AIStationList_CargoPlannedViaByFrom
152 * \li AIStationList_CargoWaitingByFrom
153 * \li AIStationList_CargoWaitingByVia
154 * \li AIStationList_CargoWaitingFromByVia
155 * \li AIStationList_CargoWaitingViaByFrom
156 *
157 * \b 1.4.4 - 1.4.1
158 * No changes
159 *
160 * \b 1.4.0
161 *
162 * API additions:
163 * \li AICargo::GetDistributionType
164 * \li AIDate::DATE_INVALID
165 * \li AIDate::IsValidDate
166 * \li AIStation::HasCargoRating
167 * \li AIStation::GetCargoWaitingFrom
168 * \li AIStation::GetCargoWaitingVia
169 * \li AITile::GetTerrainType
170 * \li AITown::FoundTown
171 * \li AITown::GetFundBuildingsDuration
172 * \li AITown::TOWN_GROWTH_NONE
173 *
174 * Other changes:
175 * \li AIStation::GetCargoRating does return -1 for cargo-station combinations that
176 * do not have a rating yet instead of returning 69.
177 *
178 * \b 1.3.3 - 1.3.2
179 *
180 * No changes
181 *
182 * \b 1.3.1
183 *
184 * API additions:
185 * \li AITile::GetTerrainType
186 *
187 * \b 1.3.0
188 *
189 * API additions:
190 * \li AIEventExclusiveTransportRights
191 * \li AIEventRoadReconstruction
192 * \li AIIndustryType::IsProcessingIndustry
193 * \li AIStation::IsAirportClosed
194 * \li AIStation::OpenCloseAirport
195 * \li AIController::Break
196 *
197 * \b 1.2.3 - 1.2.1
198 *
199 * No changes
200 *
201 * \b 1.2.0
202 *
203 * API additions:
204 *
205 * \li AIAirport::GetMaintenanceCostFactor
206 * \li AICargo::CT_AUTO_REFIT
207 * \li AICargo::CT_NO_REFIT
208 * \li AICargo::IsValidTownEffect
209 * \li AICargoList_StationAccepting
210 * \li AICompany::GetQuarterlyIncome
211 * \li AICompany::GetQuarterlyExpenses
212 * \li AICompany::GetQuarterlyCargoDelivered
213 * \li AICompany::GetQuarterlyPerformanceRating
214 * \li AICompany::GetQuarterlyCompanyValue
215 * \li AIController::GetOpsTillSuspend
216 * \li AIEngine::GetMaximumOrderDistance
217 * \li AIEventAircraftDestTooFar
218 * \li AIInfo::CONFIG_DEVELOPER
219 * \li AIInfrastructure
220 * \li AIOrder::ERR_ORDER_AIRCRAFT_NOT_ENOUGH_RANGE
221 * \li AIOrder::GetOrderDistance
222 * \li AIOrder::GetOrderRefit
223 * \li AIOrder::IsRefitOrder
224 * \li AIOrder::SetOrderRefit
225 * \li AIRail::GetMaintenanceCostFactor
226 * \li AIRoad::GetMaintenanceCostFactor
227 * \li AITile::GetTownAuthority
228 * \li AITown::GetCargoGoal
229 * \li AITown::GetGrowthRate
230 * \li AITown::GetLastMonthReceived
231 * \li AITownEffectList (to walk over all available town effects)
232 * \li AIVehicle::ERR_VEHICLE_TOO_LONG in case vehicle length limit is reached
233 * \li AIVehicle::GetMaximumOrderDistance
234 *
235 * API renames:
236 * \li AITown::GetLastMonthTransported to AITown::GetLastMonthSupplied to better
237 * reflect what it does.
238 * \li AIInfo has all its configure settings renamed from AICONFIG to just CONFIG
239 * like CONFIG_RANDOM.
240 * \li AIEvent has all its types renamed from AI_ET_ prefix to just ET_ prefix,
241 * like ET_SUBSIDY_OFFER.
242 * \li AIOrder has all its types renamed from AIOF_ prefix to just OF_ prefix.
243 *
244 * API removals:
245 * \li AICompany::GetCompanyValue, use AICompany::GetQuarterlyCompanyValue instead.
246 *
247 * Other changes:
248 * \li AITown::GetLastMonthProduction no longer has prerequisites based on town
249 * effects.
250 * \li AITown::GetLastMonthTransported resp. AITown::GetLastMonthSupplied no longer has prerequisites based on
251 * town effects.
252 * \li AITown::GetLastMonthTransportedPercentage no longer has prerequisites
253 * based on town effects.
254 *
255 * \b 1.1.5
256 *
257 * No changes
258 *
259 * \b 1.1.4
260 *
261 * API additions:
262 * \li AIVehicle::ERR_VEHICLE_TOO_LONG in case vehicle length limit is reached.
263 *
264 * \b 1.1.3 - 1.1.1
265 *
266 * No changes
267 *
268 * \b 1.1.0
269 *
270 * API additions:
271 * \li IsEnd for all lists.
272 * \li AIEventTownFounded
273 * \li AIIndustry::GetIndustryID
274 * \li AIIndustryType::INDUSTRYTYPE_TOWN
275 * \li AIIndustryType::INDUSTRYTYPE_UNKNOWN
276 * \li AIOrder::IsVoidOrder
277 * \li AIRail::GetName
278 * \li AITown::IsCity
279 *
280 * API removals:
281 * \li HasNext for all lists.
282 * \li AIAbstractList, use AIList instead.
283 * \li AIList::ChangeItem, use AIList::SetValue instead.
284 * \li AIRail::ERR_NONUNIFORM_STATIONS_DISABLED, that error is never returned anymore.
285 *
286 * Other changes:
287 * \li AIEngine::GetMaxTractiveEffort can be used for road vehicles.
288 * \li AIEngine::GetPower can be used for road vehicles.
289 * \li AIEngine::GetWeight can be used for road vehicles.
290 * \li AIIndustry::IsCargoAccepted now returns CargoAcceptState instead of a boolean.
291 * \li AIOrder::GetOrderFlags returns AIOrder::AIOF_INVALID for void orders as well.
292 * \li AIRoad::BuildDriveThroughRoadStation now allows overbuilding.
293 * \li AIRoad::BuildRoadStation now allows overbuilding.
294 *
295 * \b 1.0.5 - 1.0.4
296 *
297 * No changes
298 *
299 * \b 1.0.3
300 *
301 * API additions:
302 * \li AIRail::ERR_RAILTYPE_DISALLOWS_CROSSING
303 *
304 * \b 1.0.2
305 *
306 * Other changes:
307 * \li AIBridge::GetPrice now returns the price of the bridge without the cost for the rail or road.
308 *
309 * \b 1.0.1
310 *
311 * API additions:
312 * \li AIRail::GetMaxSpeed
313 *
314 * \b 1.0.0
315 *
316 * API additions:
317 * \li AIBaseStation
318 * \li AIEngine::IsBuildable
319 * \li AIEventCompanyAskMerger
320 * \li AIIndustry::GetLastMonthTransportedPercentage
321 * \li AIInfo::AICONFIG_INGAME
322 * \li AIMarine::GetBuildCost
323 * \li AIOrder::AIOF_GOTO_NEAREST_DEPOT
324 * \li AIOrder::GetStopLocation
325 * \li AIOrder::SetStopLocation
326 * \li AIRail::RemoveRailStationTileRectangle
327 * \li AIRail::RemoveRailWaypointTileRectangle
328 * \li AIRail::GetBuildCost
329 * \li AIRoad::GetBuildCost
330 * \li AISubsidy::SubsidyParticipantType
331 * \li AISubsidy::GetSourceType
332 * \li AISubsidy::GetSourceIndex
333 * \li AISubsidy::GetDestinationType
334 * \li AISubsidy::GetDestinationIndex
335 * \li AITile::GetBuildCost
336 * \li AITown::GetLastMonthTransportedPercentage
337 * \li AIVehicleList_Depot
338 * \li AIWaypoint::WaypointType
339 * \li AIWaypoint::HasWaypointType
340 * \li Some error messages to AIWaypoint
341 *
342 * API removals:
343 * \li AIOrder::ChangeOrder, use AIOrder::SetOrderFlags instead
344 * \li AIRail::RemoveRailStationTileRect, use AIRail::RemoveRailStationTileRectangle instead
345 * \li AIRail::RemoveRailWaypoint, use AIRail::RemoveRailWaypointTileRectangle instead
346 * \li AISign::GetMaxSignID, use AISignList instead
347 * \li AIStation::ERR_STATION_TOO_LARGE, use AIError::ERR_STATION_TOO_SPREAD_OUT instead
348 * \li AISubsidy::SourceIsTown, use AISubsidy::GetSourceType instead
349 * \li AISubsidy::GetSource, use AISubsidy::GetSourceIndex instead
350 * \li AISubsidy::DestinationIsTown, use AISubsidy::GetDestinationType instead
351 * \li AISubsidy::GetDestination, use AISubsidy::GetDestinationIndex instead
352 * \li AITile::GetHeight, use AITile::GetMinHeight/GetMaxHeight/GetCornerHeight instead
353 * \li AITown::GetMaxProduction, use AITown::GetLastMonthProduction instead
354 * \li AIVehicle::SkipToVehicleOrder, use AIOrder::SkipToOrder instead
355 * \li AIWaypoint::WAYPOINT_INVALID, use AIBaseStation::STATION_INVALID instead
356 *
357 * Other changes:
358 * \li The GetName / SetName / GetLocation functions were moved from AIStation
359 * and AIWaypoint to AIBaseStation, but you can still use AIStation.GetName
360 * as before
361 * \li The GetConstructionDate function was moved from AIStation to
362 * AIBaseStation, but can still be used as AIStation.GetConstructionDate
363 * \li WaypointID was replaced by StationID. All WaypointIDs from previous
364 * savegames are invalid. Use STATION_INVALID instead of WAYPOINT_INVALID
365 * \li AIWaypointList constructor now needs a WaypointType similar to AIStationList,
366 * it can also handle buoys.
367 * \li AIVehicleList_Station now also works for waypoints
368 * \li Stations can be build over rail without signals that is in the right
369 * direction for the to-be built station. It will also convert the rail if
370 * the station's rail type supports the old type.
371 * \li GetAPIVersion() was added as function to info.nut. If it does not exist
372 * API version 0.7 is assumed. This function should return the major and
373 * minor number of the stable version of the API the AI is written against.
374 * For 0.7.2 that would be 0.7, for 1.1.3 it would be 1.1, etc.
375 * \li The subsidy logic has changed. Subsidy is now awarded when cargo
376 * originating from subsidy source is delivered to station that has subsidy
377 * destination it its catchment area. One industry tile or one town house
378 * is enough as long as station accepts the cargo. Awarded subsidies are no
379 * longer bound to stations used for first delivery, any station can be
380 * used for loading and unloading as long as cargo is transferred from
381 * source to destination.
382 * \li Make AIEngine:CanRefitCargo() not report refittability to mail by
383 * default for aircraft. It is not necessarily true. This means that even
384 * if the aircraft can carry mail (as secondary cargo) it does not return
385 * true if the aircraft cannot carry it as its only cargo.
386 * \li Improve behaviour of AIEngine::GetCargoType(), AIEventEnginePreview::GetCargoType()
387 * and AIEngine::CanRefitCargo() for articulated vehicles. For
388 * CanRefitCargo true is returned if at least one part can be refitted.
389 * For GetCargoType the first most used cargo type is returned.
390 * \li AIIndustryType::GetConstructionCost() now returns -1 if the industry is
391 * neither buildable nor prospectable.
392 * \li AIEngine::IsValidEngine will now return true if you have at least one
393 * vehicle of that type in your company, regardless if it's still buildable
394 * or not. AIEngine::IsBuildable returns only true when you can actually
395 * build an engine.
396 * \li AITile::GetCargoProduction will now return the number of producers,
397 * including houses instead the number of producing tiles. This means that
398 * also industries that do not have a tile within the radius, but where
399 * the search bounding box and the industry's bounding box intersect, are
400 * counted. Previously these industries (and their cargoes), although they
401 * produced cargo for a station at the given location, were not returned.
402 * \li AIRail::BuildRail will now fail completely if there is an obstacle
403 * between the begin and end, instead of building up to the obstacle and
404 * returning that everything went okay.
405 * \li Orders for buoys are now waypoint orders, i.e. instead of using the
406 * station orders for buoys one has to use waypoint orders.
407 * \li Autoreplaces can now also be set for the default group via AIGroup.
408 *
409 * \b 0.7.5 - 0.7.4
410 *
411 * No changes
412 *
413 * \b 0.7.3
414 *
415 * API additions:
416 * \li AIAbstractList::SORT_ASCENDING
417 * \li AIAbstractList::SORT_DESCENDING
418 * \li AIAirport::IsAirportInformationAvailable
419 * \li AICompany::GetPresidentGender
420 * \li AICompany::SetPresidentGender
421 * \li AIEngine::GetDesignDate
422 * \li AIStation::GetConstructionDate
423 *
424 * Other changes:
425 * \li AIs are now killed when they execute a DoCommand or Sleep at a time
426 * they are not allowed to do so.
427 * \li When the API requests a string as parameter you can give every squirrel
428 * type and it will be converted to a string
429 * \li AIs can create subclasses of API classes and use API constants as part
430 * of their own constants
431 *
432 * \b 0.7.2
433 *
434 * API additions:
435 * \li AIVehicle::GetReliability
436 *
437 * Other changes:
438 * \li DoCommands and sleeps in call, acall, pcall and valuators are disallowed
439 *
440 * \b 0.7.1
441 *
442 * API additions:
443 * \li AIAirport::GetPrice
444 * \li AIController::GetVersion
445 * \li AIOrder::AIOF_DEPOT_FLAGS
446 * \li AIOrder::AIOF_STOP_IN_DEPOT
447 * \li AIOrder::IsCurrentOrderPartOfOrderList
448 * \li AIOrder::IsGotoDepotOrder
449 * \li AIOrder::IsGotoStationOrder
450 * \li AIOrder::IsGotoWaypointOrder
451 * \li AISignList
452 * \li AITile::CORNER_[WSEN]
453 * \li AITile::ERR_AREA_ALREADY_FLAT
454 * \li AITile::ERR_EXCAVATION_WOULD_DAMAGE
455 * \li AITile::GetCornerHeight
456 * \li AITile::GetMaxHeight
457 * \li AITile::GetMinHeight
458 * \li AIVehicle::SendVehicleToDepotForServicing
459 *
460 * Other changes:
461 * \li GetURL() was added as optional function to info.nut
462 * \li UseAsRandomAI() was added as optional function to info.nut
463 * \li A limit was introduced on the time the AI spends in the constructor and Load function
464 *
465 * \b 0.7.0
466 * \li First stable release with the NoAI framework.
467 */
469 /**
470 * @mainpage
471 *
472 * What's new?
473 * \li \ref ai_changelog
474 *
475 * Main classes:
476 * \li \ref AIInfo
477 * \li \ref AIController
478 *
479 * Detail topics:
480 * \li \ref script_ids
481 */