/* $Id$ */

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

#ifndef AI_VEHICLE_HPP
#define AI_VEHICLE_HPP

#include "ai_object.hpp"

/**
 * Class that handles all vehicle related functions.
 */
class AIVehicle : public AIObject {
public:
	/**
	 * Checks whether the given engine type is valid and buildable by you.
	 * @param engine_id the engine to check.
	 * @return true if and only if the engine type is valid.
	 */
	static bool IsValidEngine(EngineID engine_id);

	/**
	 * 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);

	/**
	 * Find the best road vehicle for this job, given a minimum reliability.
	 * @param cargo           the cargo the vehicle has to transport.
	 * @param min_reliability the minimum reliability of the vehicle,
	 *   between 0 and 100.
	 * @pre the tile at depot has a depot that can build the engine and
	 *   is owned by you.
	 * @pre AICargo::IsValidCargo(cargo).
	 * @pre min_reliability is between 0 and 100.
	 * @return the engine with the best characteristics, or INVALID_ENGINE
	 *   when no engine was found given the cargo and reliability.
	 */
	EngineID FindBestRoadVehicle(CargoID cargo, uint8 min_reliability);

	/**
	 * 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 true if and only if the vehicle has been build.
	 * @return the VehicleID of the new vehicle, or an invalid VehicleID when
	 *   it failed. Check the return value using IsValidVehicle.
	 */
	VehicleID BuildVehicle(TileIndex depot, EngineID vehicle_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.
	 */
	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.
	 */
	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.
	 */
	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.
	 */
	bool SendVehicleToDepot(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.
	 */
	bool StartStopVehicle(VehicleID vehicle_id);

	/**
	 * Skips the current order of the given vehicle.
	 * @param vehicle_id the vehicle to skip the order for.
	 * @pre IsValidVehicle(vehicle_id).
	 * @return true if and only if the order has been skipped.
	 */
	bool SkipVehicleOrder(VehicleID vehicle_id);
};

#ifdef DEFINE_SQUIRREL_CLASS
void SQAIVehicleRegister(Squirrel *engine) {
	DefSQClass <AIVehicle> SQAIVehicle("AIVehicle");
	SQAIVehicle.PreRegister(engine);
	SQAIVehicle.AddConstructor(engine);
	SQAIVehicle.DefSQFunction(engine, &AIVehicle::IsValidEngine,       "IsValidEngine");
	SQAIVehicle.DefSQFunction(engine, &AIVehicle::IsValidVehicle,      "IsValidVehicle");
	SQAIVehicle.DefSQFunction(engine, &AIVehicle::FindBestRoadVehicle, "FindBestRoadVehicle");
	SQAIVehicle.DefSQFunction(engine, &AIVehicle::BuildVehicle,        "BuildVehicle");
	SQAIVehicle.DefSQFunction(engine, &AIVehicle::CloneVehicle,        "CloneVehicle");
	SQAIVehicle.DefSQFunction(engine, &AIVehicle::RefitVehicle,        "RefitVehicle");
	SQAIVehicle.DefSQFunction(engine, &AIVehicle::SellVehicle,         "SellVehicle");
	SQAIVehicle.DefSQFunction(engine, &AIVehicle::SendVehicleToDepot,  "SendVehicleToDepot");
	SQAIVehicle.DefSQFunction(engine, &AIVehicle::StartStopVehicle,    "StartStopVehicle");
	SQAIVehicle.DefSQFunction(engine, &AIVehicle::SkipVehicleOrder,    "SkipVehicleOrder");
	SQAIVehicle.PostRegister(engine);
}
#endif /* DEFINE_SQUIRREL_CLASS */

#endif /* AI_VEHICLE_HPP */