/* $Id$ */

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

#ifndef AI_VEHICLE_HPP
#define AI_VEHICLE_HPP

#include "ai_object.hpp"
#include "../../vehicle_type.h"

/**
 * Class that handles all vehicle related functions.
 */
class AIVehicle : public AIObject {
public:
	/**
	 * The type of a vehicle available in the game. Trams for example are
	 *  road vehicles, as maglev is a rail vehicle.
	 */
	enum VehicleType {
		/* Order IS important, as it now matches the internal state of the game for vehicle type */
		VEHICLE_RAIL,
		VEHICLE_ROAD,
		VEHICLE_WATER,
		VEHICLE_AIR,
		VEHICLE_INVALID = 0xFF,
	};

	/**
	 * The name of the class, needed by several sub-processes.
	 */
	static const char *GetClassName() { return "AIVehicle"; }

	/**
	 * Checks whether the given vehicle is valid and owned by you.
	 * @param vehicle_id the vehicle to check.
	 * @return true if and only if the vehicle is valid.
	 */
	static bool IsValidVehicle(VehicleID vehicle_id);

	/**
	 * Builds a vehicle with the given engine at the given depot.
	 * @param depot     the depot where the vehicle will be build.
	 * @param engine_id the engine to use for this vehicle.
	 * @pre the tile at depot has a depot that can build the engine and
	 *   is owned by you.
	 * @pre IsValidEngine(engine_id).
	 * @return the VehicleID of the new vehicle, or an invalid VehicleID when
	 *   it failed. Check the return value using IsValidVehicle. In test-mode
	 *   0 is returned if it was successful; any other value indicates failure.
	 * @note in test-mode it means you can't assign orders yet to this vehicle,
	 *   as the vehicle isn't really built yet. Build it for real first before
	 *   assigning orders.
	 */
	static VehicleID BuildVehicle(TileIndex depot, EngineID engine_id);

	/**
	 * Clones a vehicle at the given depot, copying or cloning it's orders.
	 * @param depot        the depot where the vehicle will be build.
	 * @param vehicle_id   the vehicle to use as example for the new vehicle.
	 * @param share_orders should the orders be copied or shared?
	 * @pre the tile at depot has a depot.
	 * @pre IsValidVehicle(vehicle_id).
	 * @return the VehicleID of the new vehicle, or an invalid VehicleID when
	 *   it failed. Check the return value using IsValidVehicle. In test-mode
	 *   0 is returned if it was successful; any other value indicates failure.
	 */
	static VehicleID CloneVehicle(TileIndex depot, VehicleID vehicle_id, bool share_orders);

	/**
	 * Refits a vehicle to the given cargo type
	 * @param vehicle_id the vehicle to refit
	 * @param cargo      the cargo to refit to
	 * @pre IsValidVehicle(vehicle_id).
	 * @pre AICargo::IsValidCargo(cargo)
	 * @pre you must own the vehicle
	 * @pre the vehicle must be stopped in the depot
	 * @return true if and only if the refit succeeded.
	 */
	static bool RefitVehicle(VehicleID vehicle_id, CargoID cargo);

	/**
	 * Sells the given vehicle.
	 * @param vehicle_id the vehicle to sell.
	 * @pre IsValidVehicle(vehicle_id).
	 * @pre you must own the vehicle
	 * @pre the vehicle must be stopped in the depot
	 * @return true if and only if the vehicle has been sold.
	 */
	static bool SellVehicle(VehicleID vehicle_id);

	/**
	 * Sends the given vehicle to a depot.
	 * @param vehicle_id the vehicle to send to a depot.
	 * @pre IsValidVehicle(vehicle_id).
	 * @return true if and only if the vehicle has been sent to a depot.
	 */
	static bool SendVehicleToDepot(VehicleID vehicle_id);

	/**
	 * Check if a vehicle is in a depot.
	 * @param vehicle_id the vehicle to check.
	 * @pre isValidVehicle(vehicle_id).
	 * @return true if and only if the vehicle is in a depot.
	 */
	static bool IsInDepot(VehicleID vehicle_id);

	/**
	 * Check if a vehicle is in a depot and stopped.
	 * @param vehicle_id the vehicle to check.
	 * @pre isValidVehicle(vehicle_id).
	 * @return true if and only if the vehicle is in a depot and stopped.
	 */
	static bool IsStoppedInDepot(VehicleID vehicle_id);

	/**
	 * Starts or stops the given vehicle depending on the current state.
	 * @param vehicle_id the vehicle to start/stop.
	 * @pre IsValidVehicle(vehicle_id).
	 * @return true if and only if the vehicle has been started or stopped.
	 */
	static bool StartStopVehicle(VehicleID vehicle_id);

	/**
	 * Skips the current order of the given vehicle.
	 * @param vehicle_id the vehicle to skip the order for.
	 * @param order_id the selected order to which we want to skip.
	 * @pre IsValidVehicleOrder(vehicle_id, order_id).
	 * @return true if and only if the order has been skipped.
	 */
	static bool SkipToVehicleOrder(VehicleID vehicle_id, uint32 order_id);

	/**
	 * Set the name of a vehicle.
	 * @param vehicle_id the vehicle to set the name for.
	 * @param name the name for the vehicle.
	 * @pre IsValidVehicle(vehicle_id).
	 * @pre Name has to be unique.
	 * @pre You have to own the vehicle.
	 * @return true if and only if the name was changed.
	 */
	static bool SetName(VehicleID vehicle_id, const char *name);

	/**
	 * Get the current location of a vehicle.
	 * @param vehicle_id the vehicle to get the location of.
	 * @pre IsValidVehicle(vehicle_id).
	 * @return the tile the vehicle is currently on.
	 */
	static TileIndex GetLocation(VehicleID vehicle_id);

	/**
	 * Get the engine-type of a vehicle.
	 * @param vehicle_id the vehicle to get the engine-type of.
	 * @pre IsValidVehicle(vehicle_id).
	 * @return the engine type the vehicle has.
	 */
	static EngineID GetEngineType(VehicleID vehicle_id);

	/**
	 * Get the unitnumber of a vehicle.
	 * @param vehicle_id the vehicle to get the unitnumber of.
	 * @pre IsValidVehicle(vehicle_id).
	 * @return the unitnumber the vehicle has.
	 */
	static int32 GetUnitNumber(VehicleID vehicle_id);

	/**
	 * Get the name of a vehicle.
	 * @param vehicle_id the vehicle to get the name of.
	 * @pre IsValidVehicle(vehicle_id).
	 * @return the name the vehicle has.
	 */
	static char *GetName(VehicleID vehicle_id);

	/**
	 * Get the current age of a vehicle.
	 * @note age is in days.
	 * @param vehicle_id the vehicle to get the age of.
	 * @pre IsValidVehicle(vehicle_id).
	 * @return the current age the vehicle has.
	 */
	static int32 GetAge(VehicleID vehicle_id);

	/**
	 * Get the max age of a vehicle.
	 * @note age is in days.
	 * @param vehicle_id the vehicle to get the age of.
	 * @pre IsValidVehicle(vehicle_id).
	 * @return the max age the vehicle has.
	 */
	static int32 GetMaxAge(VehicleID vehicle_id);

	/**
	 * Get the age a vehicle has left (max - current).
	 * @note age is in days.
	 * @param vehicle_id the vehicle to get the age of.
	 * @pre IsValidVehicle(vehicle_id).
	 * @return the age the vehicle has left.
	 */
	static int32 GetAgeLeft(VehicleID vehicle_id);

	/**
	 * Get the running cost of this vehicle.
	 * @note cost is per year; divide by 364 to get per day.
	 * @note this is not equal to AIEngine::GetRunningCost for Trains, because
	 *   wagons and second engines can add up in the calculation too.
	 * @param vehicle_id the vehicle to get the age of.
	 * @pre IsValidVehicle(vehicle_id).
	 * @return The running cost of the vehicle per year.
	 */
	static Money GetRunningCost(VehicleID vehicle_id);

	/**
	 * Get the current profit of a vehicle.
	 * @param vehicle_id the vehicle to get the profit of.
	 * @pre IsValidVehicle(vehicle_id).
	 * @return the current profit the vehicle has.
	 */
	static int32 GetProfitThisYear(VehicleID vehicle_id);

	/**
	 * Get the profit of last year of a vehicle.
	 * @param vehicle_id the vehicle to get the profit of.
	 * @pre IsValidVehicle(vehicle_id).
	 * @return the profit the vehicle had last year.
	 */
	static int32 GetProfitLastYear(VehicleID vehicle_id);

	/**
	 * Get the type of vehicle.
	 * @param vehicle_id the vehicle to get the type of.
	 * @pre IsValidVehicle(vehicle_id).
	 * @return the vehicle type.
	 */
	static AIVehicle::VehicleType GetVehicleType(VehicleID vehicle_id);

};

#endif /* AI_VEHICLE_HPP */