1
/* $Id: ai_vehicle.hpp 15520 2009-02-19 09:01:34Z yexo $ */
3
/** @file ai_vehicle.hpp Everything to query and build vehicles. */
8
#include "ai_object.hpp"
9
#include "ai_error.hpp"
10
#include "ai_road.hpp"
11
#include "ai_order.hpp"
14
* Class that handles all vehicle related functions.
16
class AIVehicle : public AIObject {
18
static const char *GetClassName() { return "AIVehicle"; }
21
* All vehicle related error messages.
24
/** Base for vehicle related errors */
25
ERR_VEHICLE_BASE = AIError::ERR_CAT_VEHICLE << AIError::ERR_CAT_BIT_SIZE,
27
/** Too many vehicles in the game, can't build any more. */
28
ERR_VEHICLE_TOO_MANY, // [STR_00E1_TOO_MANY_VEHICLES_IN_GAME]
30
/** Vehicle is not available */
31
ERR_VEHICLE_NOT_AVAILABLE, // [STR_AIRCRAFT_NOT_AVAILABLE, STR_ROAD_VEHICLE_NOT_AVAILABLE, STR_SHIP_NOT_AVAILABLE, STR_RAIL_VEHICLE_NOT_AVAILABLE]
33
/** Vehicle can't be build due to game settigns */
34
ERR_VEHICLE_BUILD_DISABLED, // [STR_A008_CAN_T_BUILD_AIRCRAFT, STR_980D_CAN_T_BUILD_SHIP, STR_9009_CAN_T_BUILD_ROAD_VEHICLE, STR_882B_CAN_T_BUILD_RAILROAD_VEHICLE]
36
/** Vehicle can't be build in the selected depot */
37
ERR_VEHICLE_WRONG_DEPOT, // [STR_DEPOT_WRONG_DEPOT_TYPE]
39
/** Vehicle can't return to the depot */
40
ERR_VEHICLE_CANNOT_SEND_TO_DEPOT, // [STR_8830_CAN_T_SEND_TRAIN_TO_DEPOT, STR_9018_CAN_T_SEND_VEHICLE_TO_DEPOT, STR_9819_CAN_T_SEND_SHIP_TO_DEPOT, STR_A012_CAN_T_SEND_AIRCRAFT_TO]
42
/** Vehicle can't start / stop */
43
ERR_VEHICLE_CANNOT_START_STOP, // [STR_883B_CAN_T_STOP_START_TRAIN, STR_9015_CAN_T_STOP_START_ROAD_VEHICLE, STR_9818_CAN_T_STOP_START_SHIP, STR_A016_CAN_T_STOP_START_AIRCRAFT]
45
/** Vehicle can't turn */
46
ERR_VEHICLE_CANNOT_TURN, // [STR_8869_CAN_T_REVERSE_DIRECTION, STR_9033_CAN_T_MAKE_VEHICLE_TURN]
48
/** Vehicle can't be refit */
49
ERR_VEHICLE_CANNOT_REFIT, // [STR_RAIL_CAN_T_REFIT_VEHICLE, STR_REFIT_ROAD_VEHICLE_CAN_T, STR_9841_CAN_T_REFIT_SHIP, STR_A042_CAN_T_REFIT_AIRCRAFT]
51
/** Vehicle is destroyed */
52
ERR_VEHICLE_IS_DESTROYED, // [STR_CAN_T_REFIT_DESTROYED_VEHICLE, STR_CAN_T_SELL_DESTROYED_VEHICLE]
54
/** Vehicle is not in a depot */
55
ERR_VEHICLE_NOT_IN_DEPOT, // [STR_A01B_AIRCRAFT_MUST_BE_STOPPED, STR_9013_MUST_BE_STOPPED_INSIDE, STR_TRAIN_MUST_BE_STOPPED, STR_980B_SHIP_MUST_BE_STOPPED_IN]
57
/** Vehicle is flying */
58
ERR_VEHICLE_IN_FLIGHT, // [STR_A017_AIRCRAFT_IS_IN_FLIGHT]
60
/** Vehicle is without power */
61
ERR_VEHCILE_NO_POWER, // [STR_TRAIN_START_NO_CATENARY]
66
* The type of a vehicle available in the game. Trams for example are
67
* road vehicles, as maglev is a rail vehicle.
70
/* Order IS important, as it now matches the internal state of the game for vehicle type */
71
VT_RAIL, //!< Rail type vehicle.
72
VT_ROAD, //!< Road type vehicle (bus / truck).
73
VT_WATER, //!< Water type vehicle.
74
VT_AIR, //!< Air type vehicle.
75
VT_INVALID = 0xFF, //!< Invalid vehicle type.
77
#ifdef DEFINE_SCRIPT_FILES
78
VEHICLE_INVALID = -1, //!< Invalid VehicleID.
79
#endif /* DEFINE_SCRIPT_FILES */
83
* The different states a vehicle can be in.
86
VS_RUNNING, //!< The vehicle is currently running.
87
VS_STOPPED, //!< The vehicle is stopped manually.
88
VS_IN_DEPOT, //!< The vehicle is stopped in the depot.
89
VS_AT_STATION, //!< The vehicle is stopped at a station and is currently loading or unloading.
90
VS_BROKEN, //!< The vehicle has broken down and will start running again in a while.
91
VS_CRASHED, //!< The vehicle is crashed (and will never run again).
93
VS_INVALID = 0xFF, //!< An invalid vehicle state.
97
* Checks whether the given vehicle is valid and owned by you.
98
* @param vehicle_id The vehicle to check.
99
* @return True if and only if the vehicle is valid.
101
static bool IsValidVehicle(VehicleID vehicle_id);
104
* Get the number of wagons a vehicle has.
105
* @param vehicle_id The vehicle to get the number of wagons from.
106
* @pre IsValidVehicle(vehicle_id).
107
* @return The number of wagons the vehicle has.
109
static int32 GetNumWagons(VehicleID vehicle_id);
112
* Set the name of a vehicle.
113
* @param vehicle_id The vehicle to set the name for.
114
* @param name The name for the vehicle.
115
* @pre IsValidVehicle(vehicle_id).
116
* @pre 'name' must have at least one character.
117
* @pre 'name' must have at most 30 characters.
118
* @exception AIError::ERR_NAME_IS_NOT_UNIQUE
119
* @return True if and only if the name was changed.
121
static bool SetName(VehicleID vehicle_id, const char *name);
124
* Get the name of a vehicle.
125
* @param vehicle_id The vehicle to get the name of.
126
* @pre IsValidVehicle(vehicle_id).
127
* @return The name the vehicle has.
129
static char *GetName(VehicleID vehicle_id);
132
* Get the current location of a vehicle.
133
* @param vehicle_id The vehicle to get the location of.
134
* @pre IsValidVehicle(vehicle_id).
135
* @return The tile the vehicle is currently on.
137
static TileIndex GetLocation(VehicleID vehicle_id);
140
* Get the engine-type of a vehicle.
141
* @param vehicle_id The vehicle to get the engine-type of.
142
* @pre IsValidVehicle(vehicle_id).
143
* @return The engine type the vehicle has.
145
static EngineID GetEngineType(VehicleID vehicle_id);
148
* Get the engine-type of a wagon.
149
* @param vehicle_id The vehicle to get the engine-type of.
150
* @param wagon The wagon in the vehicle to get the engine-type of.
151
* @pre IsValidVehicle(vehicle_id).
152
* @pre wagon < GetNumWagons(vehicle_id).
153
* @return The engine type the vehicle has.
155
static EngineID GetWagonEngineType(VehicleID vehicle_id, int wagon);
158
* Get the unitnumber of a vehicle.
159
* @param vehicle_id The vehicle to get the unitnumber of.
160
* @pre IsValidVehicle(vehicle_id).
161
* @return The unitnumber the vehicle has.
163
static int32 GetUnitNumber(VehicleID vehicle_id);
166
* Get the current age of a vehicle.
167
* @param vehicle_id The vehicle to get the age of.
168
* @pre IsValidVehicle(vehicle_id).
169
* @return The current age the vehicle has.
170
* @note The age is in days.
172
static int32 GetAge(VehicleID vehicle_id);
175
* Get the current age of a second (or third, etc.) engine in a train vehicle.
176
* @param vehicle_id The vehicle to get the age of.
177
* @param wagon The wagon in the vehicle to get the age of.
178
* @pre IsValidVehicle(vehicle_id).
179
* @pre wagon < GetNumWagons(vehicle_id).
180
* @return The current age the vehicle has.
181
* @note The age is in days.
183
static int32 GetWagonAge(VehicleID vehicle_id, int wagon);
186
* Get the maximum age of a vehicle.
187
* @param vehicle_id The vehicle to get the age of.
188
* @pre IsValidVehicle(vehicle_id).
189
* @return The maximum age the vehicle has.
190
* @note The age is in days.
192
static int32 GetMaxAge(VehicleID vehicle_id);
195
* Get the age a vehicle has left (maximum - current).
196
* @param vehicle_id The vehicle to get the age of.
197
* @pre IsValidVehicle(vehicle_id).
198
* @return The age the vehicle has left.
199
* @note The age is in days.
201
static int32 GetAgeLeft(VehicleID vehicle_id);
204
* Get the current speed of a vehicle.
205
* @param vehicle_id The vehicle to get the age of.
206
* @pre IsValidVehicle(vehicle_id).
207
* @return The current speed of the vehicle.
208
* @note The speed is in OpenTTD's internal speed unit.
209
* This is mph / 1.6, which is roughly km/h.
210
* To get km/h multiply this number by 1.00584.
212
static int32 GetCurrentSpeed(VehicleID vehicle_id);
215
* Get the current state of a vehicle.
216
* @param vehicle_id The vehicle to get the state of.
217
* @pre IsValidVehicle(vehicle_id).
218
* @return The current state of the vehicle.
220
static VehicleState GetState(VehicleID vehicle_id);
223
* Get the running cost of this vehicle.
224
* @param vehicle_id The vehicle to get the age of.
225
* @pre IsValidVehicle(vehicle_id).
226
* @return The running cost of the vehicle per year.
227
* @note Cost is per year; divide by 365 to get per day.
228
* @note This is not equal to AIEngine::GetRunningCost for Trains, because
229
* wagons and second engines can add up in the calculation too.
231
static Money GetRunningCost(VehicleID vehicle_id);
234
* Get the current profit of a vehicle.
235
* @param vehicle_id The vehicle to get the profit of.
236
* @pre IsValidVehicle(vehicle_id).
237
* @return The current profit the vehicle has.
239
static Money GetProfitThisYear(VehicleID vehicle_id);
242
* Get the profit of last year of a vehicle.
243
* @param vehicle_id The vehicle to get the profit of.
244
* @pre IsValidVehicle(vehicle_id).
245
* @return The profit the vehicle had last year.
247
static Money GetProfitLastYear(VehicleID vehicle_id);
251
* Get the current value of a vehicle.
252
* @param vehicle_id The vehicle to get the value of.
253
* @pre IsValidVehicle(vehicle_id).
254
* @return The value the vehicle currently has (the amount you should get
255
* when you would sell the vehicle right now).
257
static Money GetCurrentValue(VehicleID vehicle_id);
260
* Get the type of vehicle.
261
* @param vehicle_id The vehicle to get the type of.
262
* @pre IsValidVehicle(vehicle_id).
263
* @return The vehicle type.
265
static AIVehicle::VehicleType GetVehicleType(VehicleID vehicle_id);
268
* Get the RoadType of the vehicle.
269
* @param vehicle_id The vehicle to get the RoadType of.
270
* @pre IsValidVehicle(vehicle_id).
271
* @pre GetVehicleType(vehicle_id) == VT_ROAD.
272
* @return The RoadType the vehicle has.
274
static AIRoad::RoadType GetRoadType(VehicleID vehicle_id);
277
* Check if a vehicle is in a depot.
278
* @param vehicle_id The vehicle to check.
279
* @pre IsValidVehicle(vehicle_id).
280
* @return True if and only if the vehicle is in a depot.
282
static bool IsInDepot(VehicleID vehicle_id);
285
* Check if a vehicle is in a depot and stopped.
286
* @param vehicle_id The vehicle to check.
287
* @pre IsValidVehicle(vehicle_id).
288
* @return True if and only if the vehicle is in a depot and stopped.
290
static bool IsStoppedInDepot(VehicleID vehicle_id);
293
* Builds a vehicle with the given engine at the given depot.
294
* @param depot The depot where the vehicle will be build.
295
* @param engine_id The engine to use for this vehicle.
296
* @pre The tile at depot has a depot that can build the engine and
298
* @pre IsValidEngine(engine_id).
299
* @exception AIVehicle::ERR_VEHICLE_TOO_MANY
300
* @exception AIVehicle::ERR_VEHICLE_BUILD_DISABLED
301
* @exception AIVehicle::ERR_VEHICLE_WRONG_DEPOT
302
* @return The VehicleID of the new vehicle, or an invalid VehicleID when
303
* it failed. Check the return value using IsValidVehicle. In test-mode
304
* 0 is returned if it was successful; any other value indicates failure.
305
* @note In Test Mode it means you can't assign orders yet to this vehicle,
306
* as the vehicle isn't really built yet. Build it for real first before
309
static VehicleID BuildVehicle(TileIndex depot, EngineID engine_id);
312
* Clones a vehicle at the given depot, copying or cloning it's orders.
313
* @param depot The depot where the vehicle will be build.
314
* @param vehicle_id The vehicle to use as example for the new vehicle.
315
* @param share_orders Should the orders be copied or shared?
316
* @pre The tile 'depot' has a depot on it, allowing 'vehicle_id'-type vehicles.
317
* @pre IsValidVehicle(vehicle_id).
318
* @exception AIVehicle::ERR_VEHICLE_TOO_MANY
319
* @exception AIVehicle::ERR_VEHICLE_BUILD_DISABLED
320
* @exception AIVehicle::ERR_VEHICLE_WRONG_DEPOT
321
* @return The VehicleID of the new vehicle, or an invalid VehicleID when
322
* it failed. Check the return value using IsValidVehicle. In test-mode
323
* 0 is returned if it was successful; any other value indicates failure.
325
static VehicleID CloneVehicle(TileIndex depot, VehicleID vehicle_id, bool share_orders);
328
* Move a wagon after another wagon.
329
* @param source_vehicle_id The vehicle to move a wagon away from.
330
* @param source_wagon The wagon in source_vehicle to move.
331
* @param dest_vehicle_id The vehicle to move the wagon to, or -1 to create a new vehicle.
332
* @param dest_wagon The wagon in dest_vehicle to place source_wagon after.
333
* @pre IsValidVehicle(source_vehicle_id).
334
* @pre source_wagon < GetNumWagons(source_vehicle_id).
335
* @pre dest_vehicle_id == -1 || (IsValidVehicle(dest_vehicle_id) && dest_wagon < GetNumWagons(dest_vehicle_id)).
336
* @pre GetVehicleType(source_vehicle_id) == VT_RAIL.
337
* @pre dest_vehicle_id == -1 || GetVehicleType(dest_vehicle_id) == VT_RAIL.
338
* @return Whether or not moving the wagon succeeded.
340
static bool MoveWagon(VehicleID source_vehicle_id, int source_wagon, int dest_vehicle_id, int dest_wagon);
343
* Move a chain of wagons after another wagon.
344
* @param source_vehicle_id The vehicle to move a wagon away from.
345
* @param source_wagon The first wagon in source_vehicle to move.
346
* @param dest_vehicle_id The vehicle to move the wagons to, or -1 to create a new vehicle.
347
* @param dest_wagon The wagon in dest_vehicle to place source_wagon and following wagons after.
348
* @pre IsValidVehicle(source_vehicle_id).
349
* @pre source_wagon < GetNumWagons(source_vehicle_id).
350
* @pre dest_vehicle_id == -1 || (IsValidVehicle(dest_vehicle_id) && dest_wagon < GetNumWagons(dest_vehicle_id)).
351
* @pre GetVehicleType(source_vehicle_id) == VT_RAIL.
352
* @pre dest_vehicle_id == -1 || GetVehicleType(dest_vehicle_id) == VT_RAIL.
353
* @return Whether or not moving the wagons succeeded.
355
static bool MoveWagonChain(VehicleID source_vehicle_id, int source_wagon, int dest_vehicle_id, int dest_wagon);
358
* Gets the capacity of the given vehicle when refited to the given cargo type.
359
* @param vehicle_id The vehicle to refit.
360
* @param cargo The cargo to refit to.
361
* @pre IsValidVehicle(vehicle_id).
362
* @pre AICargo::IsValidCargo(cargo).
363
* @pre You must own the vehicle.
364
* @pre The vehicle must be stopped in the depot.
365
* @return The capacity the vehicle will have when refited.
367
static int GetRefitCapacity(VehicleID vehicle_id, CargoID cargo);
370
* Refits a vehicle to the given cargo type.
371
* @param vehicle_id The vehicle to refit.
372
* @param cargo The cargo to refit to.
373
* @pre IsValidVehicle(vehicle_id).
374
* @pre AICargo::IsValidCargo(cargo).
375
* @pre You must own the vehicle.
376
* @pre The vehicle must be stopped in the depot.
377
* @exception AIVehicle::ERR_VEHICLE_CANNOT_REFIT
378
* @exception AIVehicle::ERR_VEHICLE_IS_DESTROYED
379
* @exception AIVehicle::ERR_VEHICLE_NOT_IN_DEPOT
380
* @return True if and only if the refit succeeded.
382
static bool RefitVehicle(VehicleID vehicle_id, CargoID cargo);
385
* Sells the given vehicle.
386
* @param vehicle_id The vehicle to sell.
387
* @pre IsValidVehicle(vehicle_id).
388
* @pre You must own the vehicle.
389
* @pre The vehicle must be stopped in the depot.
390
* @exception AIVehicle::ERR_VEHICLE_IS_DESTROYED
391
* @exception AIVehicle::ERR_VEHICLE_NOT_IN_DEPOT
392
* @return True if and only if the vehicle has been sold.
394
static bool SellVehicle(VehicleID vehicle_id);
397
* Sells the given wagon from the vehicle.
398
* @param vehicle_id The vehicle to sell a wagon from.
399
* @param wagon The wagon to sell.
400
* @pre IsValidVehicle(vehicle_id).
401
* @pre wagon < GetNumWagons(vehicle_id).
402
* @pre You must own the vehicle.
403
* @pre The vehicle must be stopped in the depot.
404
* @exception AIVehicle::ERR_VEHICLE_IS_DESTROYED
405
* @exception AIVehicle::ERR_VEHICLE_NOT_IN_DEPOT
406
* @return True if and only if the wagon has been sold.
408
static bool SellWagon(VehicleID vehicle_id, int wagon);
411
* Sells all wagons from the vehicle starting from a given position.
412
* @param vehicle_id The vehicle to sell a wagon from.
413
* @param wagon The wagon to sell.
414
* @pre IsValidVehicle(vehicle_id).
415
* @pre wagon < GetNumWagons(vehicle_id).
416
* @pre You must own the vehicle.
417
* @pre The vehicle must be stopped in the depot.
418
* @exception AIVehicle::ERR_VEHICLE_IS_DESTROYED
419
* @exception AIVehicle::ERR_VEHICLE_NOT_IN_DEPOT
420
* @return True if and only if the wagons have been sold.
422
static bool SellWagonChain(VehicleID vehicle_id, int wagon);
425
* Sends the given vehicle to a depot.
426
* @param vehicle_id The vehicle to send to a depot.
427
* @pre IsValidVehicle(vehicle_id).
428
* @exception AIVehicle::ERR_VEHICLE_CANNOT_SEND_TO_DEPOT
429
* @return True if and only if the vehicle has been sent to a depot.
431
static bool SendVehicleToDepot(VehicleID vehicle_id);
434
* Starts or stops the given vehicle depending on the current state.
435
* @param vehicle_id The vehicle to start/stop.
436
* @pre IsValidVehicle(vehicle_id).
437
* @exception AIVehicle::ERR_VEHICLE_CANNOT_START_STOP
438
* @exception (For aircraft only): AIVehicle::ERR_VEHICLE_IN_FLIGHT
439
* @exception (For trains only): AIVehicle::ERR_VEHICLE_NO_POWER
440
* @return True if and only if the vehicle has been started or stopped.
442
static bool StartStopVehicle(VehicleID vehicle_id);
445
* Skips the current order of the given vehicle.
446
* @param vehicle_id The vehicle to skip the order for.
447
* @param order_position The selected order to which we want to skip.
448
* @pre IsValidVehicleOrder(vehicle_id, order_position).
449
* @return True if and only if the order has been skipped.
451
static bool SkipToVehicleOrder(VehicleID vehicle_id, AIOrder::OrderPosition order_position);
454
* Turn the given vehicle so it'll drive the other way.
455
* @param vehicle_id The vehicle to turn.
456
* @pre IsValidVehicle(vehicle_id).
457
* @pre GetVehicleType(vehicle_id) == VT_ROAD || GetVehicleType(vehicle_id) == VT_RAIL.
458
* @return True if and only if the vehicle has started to turn.
459
* @note Vehicles cannot always be reversed. For example busses and trucks need to be running
460
* and not be inside a depot.
462
static bool ReverseVehicle(VehicleID vehicle_id);
465
* Get the maximum amount of a specific cargo the given vehicle can transport.
466
* @param vehicle_id The vehicle to get the capacity of.
467
* @param cargo The cargo to get the capacity for.
468
* @pre IsValidVehicle(vehicle_id).
469
* @pre AICargo::IsValidCargo(cargo).
470
* @return The maximum amount of the given cargo the vehicle can transport.
472
static int32 GetCapacity(VehicleID vehicle_id, CargoID cargo);
475
* Get the length of a the total vehicle in 1/16's of a tile.
476
* @param vehicle_id The vehicle to get the length of.
477
* @pre IsValidVehicle(vehicle_id).
478
* @pre GetVehicleType(vehicle_id) == VT_ROAD || GetVehicleType(vehicle_id) == VT_RAIL.
479
* @return The length of the engine.
481
static int GetLength(VehicleID vehicle_id);
484
* Get the amount of a specific cargo the given vehicle transports.
485
* @param vehicle_id The vehicle to get the load amount of.
486
* @param cargo The cargo to get the load amount for.
487
* @pre IsValidVehicle(vehicle_id).
488
* @pre AICargo::IsValidCargo(cargo).
489
* @return The amount of the given cargo the vehicle currently transports.
491
static int32 GetCargoLoad(VehicleID vehicle_id, CargoID cargo);
494
* Get the group of a given vehicle.
495
* @param vehicle_id The vehicle to get the group from.
496
* @return The group of the given vehicle.
498
static GroupID GetGroupID(VehicleID vehicle_id);
501
* Check if the vehicle is articulated.
502
* @param vehicle_id The vehicle to check.
503
* @pre IsValidVehicle(vehicle_id).
504
* @pre GetVehicleType(vehicle_id) == VT_ROAD || GetVehicleType(vehicle_id) == VT_RAIL.
505
* @return True if the vehicle is articulated.
507
static bool IsArticulated(VehicleID vehicle_id);
510
* Check if the vehicle has shared orders.
511
* @param vehicle_id The vehicle to check.
512
* @pre IsValidVehicle(vehicle_id).
513
* @return True if the vehicle has shared orders.
515
static bool HasSharedOrders(VehicleID vehicle_id);
519
* Internal function used by SellWagon(Chain).
521
static bool _SellWagonInternal(VehicleID vehicle_id, int wagon, bool sell_attached_wagons);
524
* Internal function used by MoveWagon(Chain).
526
static bool _MoveWagonInternal(VehicleID source_vehicle_id, int source_wagon, bool move_attached_wagons, int dest_vehicle_id, int dest_wagon);
529
#endif /* AI_VEHICLE_HPP */
added
removed
src/ai/api/ai_vehicle.hpp
