1

/* $Id$ */

     2

     3

/** @file ai_vehicle.hpp Everything to query and build vehicles. */

     4

     5

#ifndef AI_VEHICLE_HPP

     6

#define AI_VEHICLE_HPP

     7

     8

#include "ai_object.hpp"

     9

#include "ai_error.hpp"

    10

#include "ai_road.hpp"

    11

#include "ai_order.hpp"

    12

    13

/**

    14

 * Class that handles all vehicle related functions.

    15

 */

    16

class AIVehicle : public AIObject {

    17

public:

    18

	static const char *GetClassName() { return "AIVehicle"; }

    19

    20

	/**

    21

	 * All vehicle related error messages.

    22

	 */

    23

	enum ErrorMessages {

    24

		/** Base for vehicle related errors */

    25

		ERR_VEHICLE_BASE = AIError::ERR_CAT_VEHICLE << AIError::ERR_CAT_BIT_SIZE,

    26

    27

		/** Too many vehicles in the game, can't build any more. */

    28

		ERR_VEHICLE_TOO_MANY,                   // [STR_00E1_TOO_MANY_VEHICLES_IN_GAME]

    29

    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]

    32

    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]

    35

    36

		/** Vehicle can't be build in the selected depot */

    37

		ERR_VEHICLE_WRONG_DEPOT,                // [STR_DEPOT_WRONG_DEPOT_TYPE]

    38

    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]

    41

    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]

    44

    45

		/** Vehicle can't turn */

    46

		ERR_VEHICLE_CANNOT_TURN,                // [STR_8869_CAN_T_REVERSE_DIRECTION, STR_9033_CAN_T_MAKE_VEHICLE_TURN]

    47

    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]

    50

    51

		/** Vehicle is destroyed */

    52

		ERR_VEHICLE_IS_DESTROYED,               // [STR_CAN_T_REFIT_DESTROYED_VEHICLE, STR_CAN_T_SELL_DESTROYED_VEHICLE]

    53

    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]

    56

    57

		/** Vehicle is flying */

    58

		ERR_VEHICLE_IN_FLIGHT,                  // [STR_A017_AIRCRAFT_IS_IN_FLIGHT]

    59

    60

		/** Vehicle is without power */

    61

		ERR_VEHCILE_NO_POWER,                   // [STR_TRAIN_START_NO_CATENARY]

    62

    63

	};

    64

    65

	/**

    66

	 * The type of a vehicle available in the game. Trams for example are

    67

	 *  road vehicles, as maglev is a rail vehicle.

    68

	 */

    69

	enum VehicleType {

    70

		/* Order IS important, as it now matches the internal state of the game for vehicle type */

    71

		VEHICLE_RAIL,           //!< Rail type vehicle.

    72

		VEHICLE_ROAD,           //!< Road type vehicle (bus / truck).

    73

		VEHICLE_WATER,          //!< Water type vehicle.

    74

		VEHICLE_AIR,            //!< Air type vehicle.

    75

		VEHICLE_INVALID = 0xFF, //!< Invalid vehicle type.

    76

	};

    77

    78

	/**

    79

	 * The different states a vehicle can be in.

    80

	 */

    81

	enum VehicleState {

    82

		VS_RUNNING,        //!< The vehicle is currently running.

    83

		VS_STOPPED,        //!< The vehicle is stopped manually.

    84

		VS_IN_DEPOT,       //!< The vehicle is stopped in the depot.

    85

		VS_AT_STATION,     //!< The vehicle is stopped at a station and is currently loading or unloading.

    86

		VS_BROKEN,         //!< The vehicle has broken down and will start running again in a while.

    87

		VS_CRASHED,        //!< The vehicle is crashed (and will never run again).

    88

    89

		VS_INVALID = 0xFF, //!< An invalid vehicle state.

    90

	};

    91

    92

	/**

    93

	 * Checks whether the given vehicle is valid and owned by you.

    94

	 * @param vehicle_id The vehicle to check.

    95

	 * @return True if and only if the vehicle is valid.

    96

	 */

    97

	static bool IsValidVehicle(VehicleID vehicle_id);

    98

    99

	/**

   100

	 * Set the name of a vehicle.

   101

	 * @param vehicle_id The vehicle to set the name for.

   102

	 * @param name The name for the vehicle.

   103

	 * @pre IsValidVehicle(vehicle_id).

   104

	 * @pre Name has to be unique.

   105

	 * @pre You have to own the vehicle.

   106

	 * @return True if and only if the name was changed.

   107

	 */

   108

	static bool SetName(VehicleID vehicle_id, const char *name);

   109

   110

	/**

   111

	 * Get the name of a vehicle.

   112

	 * @param vehicle_id The vehicle to get the name of.

   113

	 * @pre IsValidVehicle(vehicle_id).

   114

	 * @return The name the vehicle has.

   115

	 */

   116

	static char *GetName(VehicleID vehicle_id);

   117

   118

	/**

   119

	 * Get the current location of a vehicle.

   120

	 * @param vehicle_id The vehicle to get the location of.

   121

	 * @pre IsValidVehicle(vehicle_id).

   122

	 * @return The tile the vehicle is currently on.

   123

	 */

   124

	static TileIndex GetLocation(VehicleID vehicle_id);

   125

   126

	/**

   127

	 * Get the engine-type of a vehicle.

   128

	 * @param vehicle_id The vehicle to get the engine-type of.

   129

	 * @pre IsValidVehicle(vehicle_id).

   130

	 * @return The engine type the vehicle has.

   131

	 */

   132

	static EngineID GetEngineType(VehicleID vehicle_id);

   133

   134

	/**

   135

	 * Get the unitnumber of a vehicle.

   136

	 * @param vehicle_id The vehicle to get the unitnumber of.

   137

	 * @pre IsValidVehicle(vehicle_id).

   138

	 * @return The unitnumber the vehicle has.

   139

	 */

   140

	static int32 GetUnitNumber(VehicleID vehicle_id);

   141

   142

	/**

   143

	 * Get the current age of a vehicle.

   144

	 * @param vehicle_id The vehicle to get the age of.

   145

	 * @pre IsValidVehicle(vehicle_id).

   146

	 * @return The current age the vehicle has.

   147

	 * @note The age is in days.

   148

	 */

   149

	static int32 GetAge(VehicleID vehicle_id);

   150

   151

	/**

   152

	 * Get the maximum age of a vehicle.

   153

	 * @param vehicle_id The vehicle to get the age of.

   154

	 * @pre IsValidVehicle(vehicle_id).

   155

	 * @return The maximum age the vehicle has.

   156

	 * @note The age is in days.

   157

	 */

   158

	static int32 GetMaxAge(VehicleID vehicle_id);

   159

   160

	/**

   161

	 * Get the age a vehicle has left (maximum - current).

   162

	 * @param vehicle_id The vehicle to get the age of.

   163

	 * @pre IsValidVehicle(vehicle_id).

   164

	 * @return The age the vehicle has left.

   165

	 * @note The age is in days.

   166

	 */

   167

	static int32 GetAgeLeft(VehicleID vehicle_id);

   168

   169

	/**

   170

	 * Get the current speed of a vehicle.

   171

	 * @param vehicle_id The vehicle to get the age of.

   172

	 * @pre IsValidVehicle(vehicle_id).

   173

	 * @return The current speed of the vehicle.

   174

	 * @note Speed is in km/h.

   175

	 */

   176

	static int32 GetCurrentSpeed(VehicleID vehicle_id);

   177

   178

	/**

   179

	 * Get the current state of a vehicle.

   180

	 * @param vehicle_id The vehicle to get the state of.

   181

	 * @pre IsValidVehicle(vehicle_id).

   182

	 * @return The current state of the vehicle.

   183

	 */

   184

	static VehicleState GetState(VehicleID vehicle_id);

   185

   186

	/**

   187

	 * Get the running cost of this vehicle.

   188

	 * @param vehicle_id The vehicle to get the age of.

   189

	 * @pre IsValidVehicle(vehicle_id).

   190

	 * @return The running cost of the vehicle per year.

   191

	 * @note Cost is per year; divide by 364 to get per day.

   192

	 * @note This is not equal to AIEngine::GetRunningCost for Trains, because

   193

	 *   wagons and second engines can add up in the calculation too.

   194

	 */

   195

	static Money GetRunningCost(VehicleID vehicle_id);

   196

   197

	/**

   198

	 * Get the current profit of a vehicle.

   199

	 * @param vehicle_id The vehicle to get the profit of.

   200

	 * @pre IsValidVehicle(vehicle_id).

   201

	 * @return The current profit the vehicle has.

   202

	 */

   203

	static Money GetProfitThisYear(VehicleID vehicle_id);

   204

   205

	/**

   206

	 * Get the profit of last year of a vehicle.

   207

	 * @param vehicle_id The vehicle to get the profit of.

   208

	 * @pre IsValidVehicle(vehicle_id).

   209

	 * @return The profit the vehicle had last year.

   210

	 */

   211

	static Money GetProfitLastYear(VehicleID vehicle_id);

   212

   213

	/**

   214

	 * Get the type of vehicle.

   215

	 * @param vehicle_id The vehicle to get the type of.

   216

	 * @pre IsValidVehicle(vehicle_id).

   217

	 * @return The vehicle type.

   218

	 */

   219

	static AIVehicle::VehicleType GetVehicleType(VehicleID vehicle_id);

   220

   221

	/**

   222

	 * Get the RoadType of the vehicle.

   223

	 * @param vehicle_id The vhiecle to get the RoadType of.

   224

	 * @pre IsValidVehicle(vehicle_id).

   225

	 * @pre GetVehicleType(vehicle_id) == VEHICLE_ROAD.

   226

	 * @return The RoadType the vehicle has.

   227

	 */

   228

	static AIRoad::RoadType GetRoadType(VehicleID vehicle_id);

   229

   230

	/**

   231

	 * Check if a vehicle is in a depot.

   232

	 * @param vehicle_id The vehicle to check.

   233

	 * @pre IsValidVehicle(vehicle_id).

   234

	 * @return True if and only if the vehicle is in a depot.

   235

	 */

   236

	static bool IsInDepot(VehicleID vehicle_id);

   237

   238

	/**

   239

	 * Check if a vehicle is in a depot and stopped.

   240

	 * @param vehicle_id The vehicle to check.

   241

	 * @pre IsValidVehicle(vehicle_id).

   242

	 * @return True if and only if the vehicle is in a depot and stopped.

   243

	 */

   244

	static bool IsStoppedInDepot(VehicleID vehicle_id);

   245

   246

	/**

   247

	 * Builds a vehicle with the given engine at the given depot.

   248

	 * @param depot The depot where the vehicle will be build.

   249

	 * @param engine_id The engine to use for this vehicle.

   250

	 * @pre The tile at depot has a depot that can build the engine and

   251

	 *   is owned by you.

   252

	 * @pre IsValidEngine(engine_id).

   253

	 * @exception AIVehicle::ERR_VEHICLE_TOO_MANY

   254

	 * @exception AIVehicle::ERR_VEHICLE_BUILD_DISABLED

   255

	 * @exception AIVehicle::ERR_VEHICLE_WRONG_DEPOT

   256

	 * @return The VehicleID of the new vehicle, or an invalid VehicleID when

   257

	 *   it failed. Check the return value using IsValidVehicle. In test-mode

   258

	 *   0 is returned if it was successful; any other value indicates failure.

   259

	 * @note In Test Mode it means you can't assign orders yet to this vehicle,

   260

	 *   as the vehicle isn't really built yet. Build it for real first before

   261

	 *   assigning orders.

   262

	 */

   263

	static VehicleID BuildVehicle(TileIndex depot, EngineID engine_id);

   264

   265

	/**

   266

	 * Clones a vehicle at the given depot, copying or cloning it's orders.

   267

	 * @param depot The depot where the vehicle will be build.

   268

	 * @param vehicle_id The vehicle to use as example for the new vehicle.

   269

	 * @param share_orders Should the orders be copied or shared?

   270

	 * @pre The tile 'depot' has a depot on it, allowing 'vehicle_id'-type vehicles.

   271

	 * @pre IsValidVehicle(vehicle_id).

   272

	 * @exception AIVehicle::ERR_VEHICLE_TOO_MANY

   273

	 * @exception AIVehicle::ERR_VEHICLE_BUILD_DISABLED

   274

	 * @exception AIVehicle::ERR_VEHICLE_WRONG_DEPOT

   275

	 * @return The VehicleID of the new vehicle, or an invalid VehicleID when

   276

	 *   it failed. Check the return value using IsValidVehicle. In test-mode

   277

	 *   0 is returned if it was successful; any other value indicates failure.

   278

	 */

   279

	static VehicleID CloneVehicle(TileIndex depot, VehicleID vehicle_id, bool share_orders);

   280

   281

	/**

   282

	 * Refits a vehicle to the given cargo type

   283

	 * @param vehicle_id The vehicle to refit

   284

	 * @param cargo The cargo to refit to.

   285

	 * @pre IsValidVehicle(vehicle_id).

   286

	 * @pre AICargo::IsValidCargo(cargo).

   287

	 * @pre You must own the vehicle.

   288

	 * @pre The vehicle must be stopped in the depot.

   289

	 * @exception AIVehicle::ERR_VEHICLE_CANNOT_REFIT

   290

	 * @exception AIVehicle::ERR_VEHICLE_IS_DESTROYED

   291

	 * @exception AIVehicle::ERR_VEHICLE_NOT_IN_DEPOT

   292

	 * @return True if and only if the refit succeeded.

   293

	 */

   294

	static bool RefitVehicle(VehicleID vehicle_id, CargoID cargo);

   295

   296

	/**

   297

	 * Sells the given vehicle.

   298

	 * @param vehicle_id The vehicle to sell.

   299

	 * @pre IsValidVehicle(vehicle_id).

   300

	 * @pre You must own the vehicle.

   301

	 * @pre The vehicle must be stopped in the depot.

   302

	 * @exception AIVehicle::ERR_VEHICLE_IS_DESTROYED

   303

	 * @exception AIVehicle::ERR_VEHICLE_NOT_IN_DEPOT

   304

	 * @return True if and only if the vehicle has been sold.

   305

	 */

   306

	static bool SellVehicle(VehicleID vehicle_id);

   307

   308

	/**

   309

	 * Sends the given vehicle to a depot.

   310

	 * @param vehicle_id The vehicle to send to a depot.

   311

	 * @pre IsValidVehicle(vehicle_id).

   312

	 * @exception AIVehicle::ERR_VEHICLE_CANNOT_SEND_TO_DEPOT

   313

	 * @return True if and only if the vehicle has been sent to a depot.

   314

	 */

   315

	static bool SendVehicleToDepot(VehicleID vehicle_id);

   316

   317

	/**

   318

	 * Starts or stops the given vehicle depending on the current state.

   319

	 * @param vehicle_id The vehicle to start/stop.

   320

	 * @pre IsValidVehicle(vehicle_id).

   321

	 * @exception AIVehicle::ERR_VEHICLE_CANNOT_START_STOP

   322

	 * @exception (For aircraft only): AIVehicle::ERR_VEHICLE_IN_FLIGHT

   323

	 * @exception (For trains only): AIVehicle::ERR_VEHICLE_NO_POWER

   324

	 * @return True if and only if the vehicle has been started or stopped.

   325

	 */

   326

	static bool StartStopVehicle(VehicleID vehicle_id);

   327

   328

	/**

   329

	 * Skips the current order of the given vehicle.

   330

	 * @param vehicle_id The vehicle to skip the order for.

   331

	 * @param order_position The selected order to which we want to skip.

   332

	 * @pre IsValidVehicleOrder(vehicle_id, order_position).

   333

	 * @return True if and only if the order has been skipped.

   334

	 */

   335

	static bool SkipToVehicleOrder(VehicleID vehicle_id, AIOrder::OrderPosition order_position);

   336

   337

	/**

   349

	 * Get the maximum amount of a specific cargo the given vehicle can transport.

   350

	 * @param vehicle_id The vehicle to get the capacity of.

   351

	 * @param cargo The cargo to get the capacity for.

   352

	 * @pre IsValidVehicle(vehicle_id).

   353

	 * @pre AICargo::IsValidCargo(cargo).

   354

	 * @return The maximum amount of the given cargo the vehicle can transport.

   355

	 */

   356

	static int32 GetCapacity(VehicleID vehicle_id, CargoID cargo);

   357

   358

	/**

   359

	 * Get the amount of a specific cargo the given vehicle transports.

   360

	 * @param vehicle_id The vehicle to get the load amount of.

   361

	 * @param cargo The cargo to get the load amount for.

   362

	 * @pre IsValidVehicle(vehicle_id).

   363

	 * @pre AICargo::IsValidCargo(cargo).

   364

	 * @return The amount of the given cargo the vehicle currently transports.

   365

	 */

   366

	static int32 GetCargoLoad(VehicleID vehicle_id, CargoID cargo);

   367

   368

	/**

   369

	 * Get the group of a given vehicle.

   370

	 * @param vehicle_id The vehicle to get the group from.

   371

	 * @return The group of the given vehicle.

   372

	 */

   373

	static GroupID GetGroupID(VehicleID vehicle_id);

   374

};

   375

   376

#endif /* AI_VEHICLE_HPP */