Fix: Some Script::IsValidVehicle checks need to be complemented with IsPrimaryVehicle

Add: [Script] ScriptVehicle.IsPrimaryVehicle

src/script/api/ai_changelog.hpp

@@ -19,6 +19,7 @@
  *
  * API additions:
  * \li AITown::ROAD_LAYOUT_RANDOM
+ * \li AIVehicle::IsPrimaryVehicle
  *
  * API removals:
  * \li AIError::ERR_PRECONDITION_TOO_MANY_PARAMETERS, that error is never returned anymore.

src/script/api/game_changelog.hpp

@@ -19,6 +19,7 @@
  *
  * API additions:
  * \li GSTown::ROAD_LAYOUT_RANDOM
+ * \li GSVehicle::IsPrimaryVehicle
  *
  * API removals:
  * \li GSError::ERR_PRECONDITION_TOO_MANY_PARAMETERS, that error is never returned anymore.

src/script/api/script_group.cpp

@@ -121,7 +121,7 @@
 /* static */ bool ScriptGroup::MoveVehicle(GroupID group_id, VehicleID vehicle_id)
 {
 	EnforcePrecondition(false, IsValidGroup(group_id) || group_id == GROUP_DEFAULT);
-	EnforcePrecondition(false, ScriptVehicle::IsValidVehicle(vehicle_id));
+	EnforcePrecondition(false, ScriptVehicle::IsPrimaryVehicle(vehicle_id));
 
 	return ScriptObject::Command<CMD_ADD_VEHICLE_GROUP>::Do(group_id, vehicle_id, false);
 }

src/script/api/script_group.hpp

@@ -147,7 +147,7 @@ public:
 	 * @param group_id The group to move the vehicle to.
 	 * @param vehicle_id The vehicle to move to the group.
 	 * @pre IsValidGroup(group_id) || group_id == GROUP_DEFAULT.
-	 * @pre ScriptVehicle::IsValidVehicle(vehicle_id).
+	 * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id).
 	 * @return True if and only if the vehicle was successfully moved to the group.
 	 * @note A vehicle can be in only one group at the same time. To remove it from
 	 *  a group, move it to another or to GROUP_DEFAULT. Moving the vehicle to the

src/script/api/script_order.cpp

@@ -50,7 +50,7 @@ static OrderType GetOrderTypeByTile(TileIndex t)
 
 /* static */ bool ScriptOrder::IsValidVehicleOrder(VehicleID vehicle_id, OrderPosition order_position)
 {
-	return ScriptVehicle::IsValidVehicle(vehicle_id) && order_position >= 0 && (order_position < ::Vehicle::Get(vehicle_id)->GetNumManualOrders() || order_position == ORDER_CURRENT);
+	return ScriptVehicle::IsPrimaryVehicle(vehicle_id) && order_position >= 0 && (order_position < ::Vehicle::Get(vehicle_id)->GetNumManualOrders() || order_position == ORDER_CURRENT);
 }
 
 /**
@@ -158,7 +158,7 @@ static int ScriptOrderPositionToRealOrderPosition(VehicleID vehicle_id, ScriptOr
 
 /* static */ bool ScriptOrder::IsCurrentOrderPartOfOrderList(VehicleID vehicle_id)
 {
-	if (!ScriptVehicle::IsValidVehicle(vehicle_id)) return false;
+	if (!ScriptVehicle::IsPrimaryVehicle(vehicle_id)) return false;
 	if (GetOrderCount(vehicle_id) == 0) return false;
 
 	const Order *order = &::Vehicle::Get(vehicle_id)->current_order;
@@ -168,7 +168,7 @@ static int ScriptOrderPositionToRealOrderPosition(VehicleID vehicle_id, ScriptOr
 
 /* static */ ScriptOrder::OrderPosition ScriptOrder::ResolveOrderPosition(VehicleID vehicle_id, OrderPosition order_position)
 {
-	if (!ScriptVehicle::IsValidVehicle(vehicle_id)) return ORDER_INVALID;
+	if (!ScriptVehicle::IsPrimaryVehicle(vehicle_id)) return ORDER_INVALID;
 
 	int num_manual_orders = ::Vehicle::Get(vehicle_id)->GetNumManualOrders();
 	if (num_manual_orders == 0) return ORDER_INVALID;
@@ -236,7 +236,7 @@ static int ScriptOrderPositionToRealOrderPosition(VehicleID vehicle_id, ScriptOr
 
 /* static */ int32 ScriptOrder::GetOrderCount(VehicleID vehicle_id)
 {
-	return ScriptVehicle::IsValidVehicle(vehicle_id) ? ::Vehicle::Get(vehicle_id)->GetNumManualOrders() : -1;
+	return ScriptVehicle::IsPrimaryVehicle(vehicle_id) ? ::Vehicle::Get(vehicle_id)->GetNumManualOrders() : -1;
 }
 
 /* static */ TileIndex ScriptOrder::GetOrderDestination(VehicleID vehicle_id, OrderPosition order_position)
@@ -443,7 +443,7 @@ static int ScriptOrderPositionToRealOrderPosition(VehicleID vehicle_id, ScriptOr
 
 /* static */ bool ScriptOrder::AppendOrder(VehicleID vehicle_id, TileIndex destination, ScriptOrderFlags order_flags)
 {
-	EnforcePrecondition(false, ScriptVehicle::IsValidVehicle(vehicle_id));
+	EnforcePrecondition(false, ScriptVehicle::IsPrimaryVehicle(vehicle_id));
 	EnforcePrecondition(false, AreOrderFlagsValid(destination, order_flags));
 
 	return InsertOrder(vehicle_id, (ScriptOrder::OrderPosition)::Vehicle::Get(vehicle_id)->GetNumManualOrders(), destination, order_flags);
@@ -451,7 +451,7 @@ static int ScriptOrderPositionToRealOrderPosition(VehicleID vehicle_id, ScriptOr
 
 /* static */ bool ScriptOrder::AppendConditionalOrder(VehicleID vehicle_id, OrderPosition jump_to)
 {
-	EnforcePrecondition(false, ScriptVehicle::IsValidVehicle(vehicle_id));
+	EnforcePrecondition(false, ScriptVehicle::IsPrimaryVehicle(vehicle_id));
 	EnforcePrecondition(false, IsValidVehicleOrder(vehicle_id, jump_to));
 
 	return InsertConditionalOrder(vehicle_id, (ScriptOrder::OrderPosition)::Vehicle::Get(vehicle_id)->GetNumManualOrders(), jump_to);
@@ -462,7 +462,7 @@ static int ScriptOrderPositionToRealOrderPosition(VehicleID vehicle_id, ScriptOr
 	/* IsValidVehicleOrder is not good enough because it does not allow appending. */
 	if (order_position == ORDER_CURRENT) order_position = ScriptOrder::ResolveOrderPosition(vehicle_id, order_position);
 
-	EnforcePrecondition(false, ScriptVehicle::IsValidVehicle(vehicle_id));
+	EnforcePrecondition(false, ScriptVehicle::IsPrimaryVehicle(vehicle_id));
 	EnforcePrecondition(false, order_position >= 0 && order_position <= ::Vehicle::Get(vehicle_id)->GetNumManualOrders());
 	EnforcePrecondition(false, AreOrderFlagsValid(destination, order_flags));
 
@@ -516,7 +516,7 @@ static int ScriptOrderPositionToRealOrderPosition(VehicleID vehicle_id, ScriptOr
 	/* IsValidVehicleOrder is not good enough because it does not allow appending. */
 	if (order_position == ORDER_CURRENT) order_position = ScriptOrder::ResolveOrderPosition(vehicle_id, order_position);
 
-	EnforcePrecondition(false, ScriptVehicle::IsValidVehicle(vehicle_id));
+	EnforcePrecondition(false, ScriptVehicle::IsPrimaryVehicle(vehicle_id));
 	EnforcePrecondition(false, order_position >= 0 && order_position <= ::Vehicle::Get(vehicle_id)->GetNumManualOrders());
 	EnforcePrecondition(false, IsValidVehicleOrder(vehicle_id, jump_to) && jump_to != ORDER_CURRENT);
 
@@ -645,23 +645,23 @@ static void _DoCommandReturnSetOrderFlags(class ScriptInstance *instance)
 
 /* static */ bool ScriptOrder::CopyOrders(VehicleID vehicle_id, VehicleID main_vehicle_id)
 {
-	EnforcePrecondition(false, ScriptVehicle::IsValidVehicle(vehicle_id));
-	EnforcePrecondition(false, ScriptVehicle::IsValidVehicle(main_vehicle_id));
+	EnforcePrecondition(false, ScriptVehicle::IsPrimaryVehicle(vehicle_id));
+	EnforcePrecondition(false, ScriptVehicle::IsPrimaryVehicle(main_vehicle_id));
 
 	return ScriptObject::Command<CMD_CLONE_ORDER>::Do(0, CO_COPY, vehicle_id, main_vehicle_id);
 }
 
 /* static */ bool ScriptOrder::ShareOrders(VehicleID vehicle_id, VehicleID main_vehicle_id)
 {
-	EnforcePrecondition(false, ScriptVehicle::IsValidVehicle(vehicle_id));
-	EnforcePrecondition(false, ScriptVehicle::IsValidVehicle(main_vehicle_id));
+	EnforcePrecondition(false, ScriptVehicle::IsPrimaryVehicle(vehicle_id));
+	EnforcePrecondition(false, ScriptVehicle::IsPrimaryVehicle(main_vehicle_id));
 
 	return ScriptObject::Command<CMD_CLONE_ORDER>::Do(0, CO_SHARE, vehicle_id, main_vehicle_id);
 }
 
 /* static */ bool ScriptOrder::UnshareOrders(VehicleID vehicle_id)
 {
-	EnforcePrecondition(false, ScriptVehicle::IsValidVehicle(vehicle_id));
+	EnforcePrecondition(false, ScriptVehicle::IsPrimaryVehicle(vehicle_id));
 
 	return ScriptObject::Command<CMD_CLONE_ORDER>::Do(0, CO_UNSHARE, vehicle_id, 0);
 }

src/script/api/script_order.hpp

@@ -142,7 +142,7 @@ public:
 	 * Checks whether the given order id is valid for the given vehicle.
 	 * @param vehicle_id The vehicle to check the order index for.
 	 * @param order_position The order index to check.
-	 * @pre ScriptVehicle::IsValidVehicle(vehicle_id).
+	 * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id).
 	 * @return True if and only if the order_position is valid for the given vehicle.
 	 */
 	static bool IsValidVehicleOrder(VehicleID vehicle_id, OrderPosition order_position);
@@ -207,7 +207,7 @@ public:
 	/**
 	 * Checks whether the current order is part of the orderlist.
 	 * @param vehicle_id The vehicle to check.
-	 * @pre ScriptVehicle::IsValidVehicle(vehicle_id).
+	 * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id).
 	 * @return True if and only if the current order is part of the order list.
 	 * @note If the order is a non-'non-stop' order, and the vehicle is currently
 	 * (un)loading at a station that is not the final destination, this function
@@ -222,7 +222,7 @@ public:
 	 *  given index does not exist it will return ORDER_INVALID.
 	 * @param vehicle_id The vehicle to check the order index for.
 	 * @param order_position The order index to resolve.
-	 * @pre ScriptVehicle::IsValidVehicle(vehicle_id).
+	 * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id).
 	 * @return The resolved order index.
 	 */
 	static OrderPosition ResolveOrderPosition(VehicleID vehicle_id, OrderPosition order_position);
@@ -246,7 +246,7 @@ public:
 	/**
 	 * Returns the number of orders for the given vehicle.
 	 * @param vehicle_id The vehicle to get the order count of.
-	 * @pre ScriptVehicle::IsValidVehicle(vehicle_id).
+	 * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id).
 	 * @return The number of orders for the given vehicle or a negative
 	 *   value when the vehicle does not exist.
 	 */
@@ -432,7 +432,7 @@ public:
 	 * @param vehicle_id The vehicle to append the order to.
 	 * @param destination The destination of the order.
 	 * @param order_flags The flags given to the order.
-	 * @pre ScriptVehicle::IsValidVehicle(vehicle_id).
+	 * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id).
 	 * @pre AreOrderFlagsValid(destination, order_flags).
 	 * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
 	 * @exception ScriptOrder::ERR_ORDER_TOO_MANY
@@ -446,7 +446,7 @@ public:
 	 * Appends a conditional order to the end of the vehicle's order list.
 	 * @param vehicle_id The vehicle to append the order to.
 	 * @param jump_to The OrderPosition to jump to if the condition is true.
-	 * @pre ScriptVehicle::IsValidVehicle(vehicle_id).
+	 * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id).
 	 * @pre IsValidVehicleOrder(vehicle_id, jump_to).
 	 * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
 	 * @exception ScriptOrder::ERR_ORDER_TOO_MANY
@@ -461,6 +461,7 @@ public:
 	 * @param order_position The order to place the new order before.
 	 * @param destination The destination of the order.
 	 * @param order_flags The flags given to the order.
+	 * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id)
 	 * @pre IsValidVehicleOrder(vehicle_id, order_position).
 	 * @pre AreOrderFlagsValid(destination, order_flags).
 	 * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
@@ -476,6 +477,7 @@ public:
 	 * @param vehicle_id The vehicle to add the order to.
 	 * @param order_position The order to place the new order before.
 	 * @param jump_to The OrderPosition to jump to if the condition is true.
+	 * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id).
 	 * @pre IsValidVehicleOrder(vehicle_id, order_position).
 	 * @pre IsValidVehicleOrder(vehicle_id, jump_to).
 	 * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
@@ -550,8 +552,8 @@ public:
 	 *  are going to be the orders of the changed vehicle.
 	 * @param vehicle_id The vehicle to copy the orders to.
 	 * @param main_vehicle_id The vehicle to copy the orders from.
-	 * @pre ScriptVehicle::IsValidVehicle(vehicle_id).
-	 * @pre ScriptVehicle::IsValidVehicle(main_vehicle_id).
+	 * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id).
+	 * @pre ScriptVehicle::IsPrimaryVehicle(main_vehicle_id).
 	 * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
 	 * @exception ScriptOrder::ERR_ORDER_TOO_MANY
 	 * @exception ScriptOrder::ERR_ORDER_AIRCRAFT_NOT_ENOUGH_RANGE
@@ -565,8 +567,8 @@ public:
 	 * vehicle are going to be the orders of the changed vehicle.
 	 * @param vehicle_id The vehicle to add to the shared order list.
 	 * @param main_vehicle_id The vehicle to share the orders with.
-	 * @pre ScriptVehicle::IsValidVehicle(vehicle_id).
-	 * @pre ScriptVehicle::IsValidVehicle(main_vehicle_id).
+	 * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id).
+	 * @pre ScriptVehicle::IsPrimaryVehicle(main_vehicle_id).
 	 * @exception ScriptError::ERR_OWNED_BY_ANOTHER_COMPANY
 	 * @exception ScriptOrder::ERR_ORDER_AIRCRAFT_NOT_ENOUGH_RANGE
 	 * @return True if and only if the sharing succeeded.
@@ -578,7 +580,7 @@ public:
 	 * Removes the given vehicle from a shared orders list.
 	 * After unsharing orders, the orders list of the vehicle is empty.
 	 * @param vehicle_id The vehicle to remove from the shared order list.
-	 * @pre ScriptVehicle::IsValidVehicle(vehicle_id).
+	 * @pre ScriptVehicle::IsPrimaryVehicle(vehicle_id).
 	 * @return True if and only if the unsharing succeeded.
 	 * @api -game
 	 */

src/script/api/script_stationlist.cpp

@@ -25,7 +25,7 @@ ScriptStationList::ScriptStationList(ScriptStation::StationType station_type)
 
 ScriptStationList_Vehicle::ScriptStationList_Vehicle(VehicleID vehicle_id)
 {
-	if (!ScriptVehicle::IsValidVehicle(vehicle_id)) return;
+	if (!ScriptVehicle::IsPrimaryVehicle(vehicle_id)) return;
 
 	Vehicle *v = ::Vehicle::Get(vehicle_id);
 

src/script/api/script_vehicle.cpp

@@ -34,6 +34,13 @@
 	return v != nullptr && (v->owner == ScriptObject::GetCompany() || ScriptObject::GetCompany() == OWNER_DEITY) && (v->IsPrimaryVehicle() || (v->type == VEH_TRAIN && ::Train::From(v)->IsFreeWagon()));
 }
 
+/* static */ bool ScriptVehicle::IsPrimaryVehicle(VehicleID vehicle_id)
+{
+	if (!IsValidVehicle(vehicle_id)) return false;
+
+	return ::Vehicle::Get(vehicle_id)->IsPrimaryVehicle();
+}
+
 /* static */ ScriptCompany::CompanyID ScriptVehicle::GetOwner(VehicleID vehicle_id)
 {
 	if (!IsValidVehicle(vehicle_id)) return ScriptCompany::COMPANY_INVALID;
@@ -102,7 +109,7 @@
 /* static */ VehicleID ScriptVehicle::CloneVehicle(TileIndex depot, VehicleID vehicle_id, bool share_orders)
 {
 	EnforcePrecondition(false, ScriptObject::GetCompany() != OWNER_DEITY);
-	EnforcePrecondition(false, IsValidVehicle(vehicle_id));
+	EnforcePrecondition(false, IsPrimaryVehicle(vehicle_id));
 
 	if (!ScriptObject::Command<CMD_CLONE_VEHICLE>::Do(&ScriptInstance::DoCommandReturnVehicleID, depot, vehicle_id, share_orders)) return VEHICLE_INVALID;
 
@@ -191,7 +198,7 @@
 /* static */ bool ScriptVehicle::SendVehicleToDepot(VehicleID vehicle_id)
 {
 	EnforcePrecondition(false, ScriptObject::GetCompany() != OWNER_DEITY);
-	EnforcePrecondition(false, IsValidVehicle(vehicle_id));
+	EnforcePrecondition(false, IsPrimaryVehicle(vehicle_id));
 
 	return ScriptObject::Command<CMD_SEND_VEHICLE_TO_DEPOT>::Do(vehicle_id, DepotCommand::None, {});
 }
@@ -199,7 +206,7 @@
 /* static */ bool ScriptVehicle::SendVehicleToDepotForServicing(VehicleID vehicle_id)
 {
 	EnforcePrecondition(false, ScriptObject::GetCompany() != OWNER_DEITY);
-	EnforcePrecondition(false, IsValidVehicle(vehicle_id));
+	EnforcePrecondition(false, IsPrimaryVehicle(vehicle_id));
 
 	return ScriptObject::Command<CMD_SEND_VEHICLE_TO_DEPOT>::Do(vehicle_id, DepotCommand::Service, {});
 }
@@ -219,7 +226,7 @@
 /* static */ bool ScriptVehicle::StartStopVehicle(VehicleID vehicle_id)
 {
 	EnforcePrecondition(false, ScriptObject::GetCompany() != OWNER_DEITY);
-	EnforcePrecondition(false, IsValidVehicle(vehicle_id));
+	EnforcePrecondition(false, IsPrimaryVehicle(vehicle_id));
 
 	return ScriptObject::Command<CMD_START_STOP_VEHICLE>::Do(vehicle_id, false);
 }
@@ -227,7 +234,7 @@
 /* static */ bool ScriptVehicle::ReverseVehicle(VehicleID vehicle_id)
 {
 	EnforcePrecondition(false, ScriptObject::GetCompany() != OWNER_DEITY);
-	EnforcePrecondition(false, IsValidVehicle(vehicle_id));
+	EnforcePrecondition(false, IsPrimaryVehicle(vehicle_id));
 	EnforcePrecondition(false, ::Vehicle::Get(vehicle_id)->type == VEH_ROAD || ::Vehicle::Get(vehicle_id)->type == VEH_TRAIN);
 
 	switch (::Vehicle::Get(vehicle_id)->type) {
@@ -242,7 +249,7 @@
 	CCountedPtr<Text> counter(name);
 
 	EnforcePrecondition(false, ScriptObject::GetCompany() != OWNER_DEITY);
-	EnforcePrecondition(false, IsValidVehicle(vehicle_id));
+	EnforcePrecondition(false, IsPrimaryVehicle(vehicle_id));
 	EnforcePrecondition(false, name != nullptr);
 	const std::string &text = name->GetDecodedText();
 	EnforcePreconditionEncodedText(false, text);
@@ -286,14 +293,14 @@
 
 /* static */ int32 ScriptVehicle::GetUnitNumber(VehicleID vehicle_id)
 {
-	if (!IsValidVehicle(vehicle_id)) return -1;
+	if (!IsPrimaryVehicle(vehicle_id)) return -1;
 
 	return ::Vehicle::Get(vehicle_id)->unitnumber;
 }
 
 /* static */ char *ScriptVehicle::GetName(VehicleID vehicle_id)
 {
-	if (!IsValidVehicle(vehicle_id)) return nullptr;
+	if (!IsPrimaryVehicle(vehicle_id)) return nullptr;
 
 	::SetDParam(0, vehicle_id);
 	return GetString(STR_VEHICLE_NAME);
@@ -320,21 +327,21 @@
 
 /* static */ int32 ScriptVehicle::GetMaxAge(VehicleID vehicle_id)
 {
-	if (!IsValidVehicle(vehicle_id)) return -1;
+	if (!IsPrimaryVehicle(vehicle_id)) return -1;
 
 	return ::Vehicle::Get(vehicle_id)->max_age;
 }
 
 /* static */ int32 ScriptVehicle::GetAgeLeft(VehicleID vehicle_id)
 {
-	if (!IsValidVehicle(vehicle_id)) return -1;
+	if (!IsPrimaryVehicle(vehicle_id)) return -1;
 
 	return ::Vehicle::Get(vehicle_id)->max_age - ::Vehicle::Get(vehicle_id)->age;
 }
 
 /* static */ int32 ScriptVehicle::GetCurrentSpeed(VehicleID vehicle_id)
 {
-	if (!IsValidVehicle(vehicle_id)) return -1;
+	if (!IsPrimaryVehicle(vehicle_id)) return -1;
 
 	const ::Vehicle *v = ::Vehicle::Get(vehicle_id);
 	return (v->vehstatus & (::VS_STOPPED | ::VS_CRASHED)) == 0 ? v->GetDisplaySpeed() : 0; // km-ish/h
@@ -357,21 +364,21 @@
 
 /* static */ Money ScriptVehicle::GetRunningCost(VehicleID vehicle_id)
 {
-	if (!IsValidVehicle(vehicle_id)) return -1;
+	if (!IsPrimaryVehicle(vehicle_id)) return -1;
 
 	return ::Vehicle::Get(vehicle_id)->GetRunningCost() >> 8;
 }
 
 /* static */ Money ScriptVehicle::GetProfitThisYear(VehicleID vehicle_id)
 {
-	if (!IsValidVehicle(vehicle_id)) return -1;
+	if (!IsPrimaryVehicle(vehicle_id)) return -1;
 
 	return ::Vehicle::Get(vehicle_id)->GetDisplayProfitThisYear();
 }
 
 /* static */ Money ScriptVehicle::GetProfitLastYear(VehicleID vehicle_id)
 {
-	if (!IsValidVehicle(vehicle_id)) return -1;
+	if (!IsPrimaryVehicle(vehicle_id)) return -1;
 
 	return ::Vehicle::Get(vehicle_id)->GetDisplayProfitLastYear();
 }
@@ -432,7 +439,7 @@
 
 /* static */ GroupID ScriptVehicle::GetGroupID(VehicleID vehicle_id)
 {
-	if (!IsValidVehicle(vehicle_id)) return ScriptGroup::GROUP_INVALID;
+	if (!IsPrimaryVehicle(vehicle_id)) return ScriptGroup::GROUP_INVALID;
 
 	return ::Vehicle::Get(vehicle_id)->group_id;
 }
@@ -452,7 +459,7 @@
 
 /* static */ bool ScriptVehicle::HasSharedOrders(VehicleID vehicle_id)
 {
-	if (!IsValidVehicle(vehicle_id)) return false;
+	if (!IsPrimaryVehicle(vehicle_id)) return false;
 
 	Vehicle *v = ::Vehicle::Get(vehicle_id);
 	return v->orders != nullptr && v->orders->GetNumVehicles() > 1;
@@ -460,7 +467,7 @@
 
 /* static */ int ScriptVehicle::GetReliability(VehicleID vehicle_id)
 {
-	if (!IsValidVehicle(vehicle_id)) return -1;
+	if (!IsPrimaryVehicle(vehicle_id)) return -1;
 
 	const Vehicle *v = ::Vehicle::Get(vehicle_id);
 	return ::ToPercent16(v->reliability);
@@ -468,7 +475,7 @@
 
 /* static */ uint ScriptVehicle::GetMaximumOrderDistance(VehicleID vehicle_id)
 {
-	if (!IsValidVehicle(vehicle_id)) return 0;
+	if (!IsPrimaryVehicle(vehicle_id)) return 0;
 
 	const ::Vehicle *v = ::Vehicle::Get(vehicle_id);
 	switch (v->type) {

src/script/api/script_vehicle.hpp

@@ -97,9 +97,20 @@ public:
 	 * 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.
+	 * @note Also returns true when the leading part of the vehicle is a wagon.
+	 *       Use IsPrimaryVehicle() to check for a valid vehicle with a leading engine.
 	 */
 	static bool IsValidVehicle(VehicleID vehicle_id);
 
+	/**
+	 * Checks whether this is a primary vehicle.
+	 * @param vehicle_id The vehicle to check.
+	 * @pre IsValidVehicle(vehicle_id).
+	 * @return True if the vehicle is a primary vehicle.
+	 * @note Returns false when the leading part of the vehicle is a wagon.
+	 */
+	static bool IsPrimaryVehicle(VehicleID vehicle_id);
+
 	/**
 	 * Get the number of wagons a vehicle has.
 	 * @param vehicle_id The vehicle to get the number of wagons from.
@@ -112,7 +123,7 @@ public:
 	 * Set the name of a vehicle.
 	 * @param vehicle_id The vehicle to set the name for.
 	 * @param name The name for the vehicle (can be either a raw string, or a ScriptText object).
-	 * @pre IsValidVehicle(vehicle_id).
+	 * @pre IsPrimaryVehicle(vehicle_id).
 	 * @pre name != null && len(name) != 0.
 	 * @game @pre Valid ScriptCompanyMode active in scope.
 	 * @exception ScriptError::ERR_NAME_IS_NOT_UNIQUE
@@ -123,7 +134,7 @@ public:
 	/**
 	 * Get the name of a vehicle.
 	 * @param vehicle_id The vehicle to get the name of.
-	 * @pre IsValidVehicle(vehicle_id).
+	 * @pre IsPrimaryVehicle(vehicle_id).
 	 * @return The name the vehicle has.
 	 */
 	static char *GetName(VehicleID vehicle_id);
@@ -166,7 +177,7 @@ public:
 	/**
 	 * Get the unitnumber of a vehicle.
 	 * @param vehicle_id The vehicle to get the unitnumber of.
-	 * @pre IsValidVehicle(vehicle_id).
+	 * @pre IsPrimaryVehicle(vehicle_id).
 	 * @return The unitnumber the vehicle has.
 	 */
 	static int32 GetUnitNumber(VehicleID vehicle_id);
@@ -194,7 +205,7 @@ public:
 	/**
 	 * Get the maximum age of a vehicle.
 	 * @param vehicle_id The vehicle to get the age of.
-	 * @pre IsValidVehicle(vehicle_id).
+	 * @pre IsPrimaryVehicle(vehicle_id).
 	 * @return The maximum age the vehicle has.
 	 * @note The age is in days.
 	 */
@@ -203,7 +214,7 @@ public:
 	/**
 	 * Get the age a vehicle has left (maximum - current).
 	 * @param vehicle_id The vehicle to get the age of.
-	 * @pre IsValidVehicle(vehicle_id).
+	 * @pre IsPrimaryVehicle(vehicle_id).
 	 * @return The age the vehicle has left.
 	 * @note The age is in days.
 	 */
@@ -212,7 +223,7 @@ public:
 	/**
 	 * Get the current speed of a vehicle.
 	 * @param vehicle_id The vehicle to get the speed of.
-	 * @pre IsValidVehicle(vehicle_id).
+	 * @pre IsPrimaryVehicle(vehicle_id).
 	 * @return The current speed of the vehicle.
 	 * @note The speed is in OpenTTD's internal speed unit.
 	 *       This is mph / 1.6, which is roughly km/h.
@@ -231,7 +242,7 @@ public:
 	/**
 	 * Get the running cost of this vehicle.
 	 * @param vehicle_id The vehicle to get the running cost of.
-	 * @pre IsValidVehicle(vehicle_id).
+	 * @pre IsPrimaryVehicle(vehicle_id).
 	 * @return The running cost of the vehicle per year.
 	 * @note Cost is per year; divide by 365 to get per day.
 	 * @note This is not equal to ScriptEngine::GetRunningCost for Trains, because
@@ -242,7 +253,7 @@ public:
 	/**
 	 * Get the current profit of a vehicle.
 	 * @param vehicle_id The vehicle to get the profit of.
-	 * @pre IsValidVehicle(vehicle_id).
+	 * @pre IsPrimaryVehicle(vehicle_id).
 	 * @return The current profit the vehicle has.
 	 */
 	static Money GetProfitThisYear(VehicleID vehicle_id);
@@ -250,7 +261,7 @@ public:
 	/**
 	 * Get the profit of last year of a vehicle.
 	 * @param vehicle_id The vehicle to get the profit of.
-	 * @pre IsValidVehicle(vehicle_id).
+	 * @pre IsPrimaryVehicle(vehicle_id).
 	 * @return The profit the vehicle had last year.
 	 */
 	static Money GetProfitLastYear(VehicleID vehicle_id);
@@ -363,7 +374,7 @@ public:
 	 * @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 'depot' has a depot on it, allowing 'vehicle_id'-type vehicles.
-	 * @pre IsValidVehicle(vehicle_id).
+	 * @pre IsPrimaryVehicle(vehicle_id).
 	 * @game @pre Valid ScriptCompanyMode active in scope.
 	 * @exception ScriptVehicle::ERR_VEHICLE_TOO_MANY
 	 * @exception ScriptVehicle::ERR_VEHICLE_BUILD_DISABLED
@@ -481,7 +492,7 @@ public:
 	 * Sends the given vehicle to a depot. If the vehicle has already been
 	 * sent to a depot it continues with its normal orders instead.
 	 * @param vehicle_id The vehicle to send to a depot.
-	 * @pre IsValidVehicle(vehicle_id).
+	 * @pre IsPrimaryVehicle(vehicle_id).
 	 * @game @pre Valid ScriptCompanyMode active in scope.
 	 * @exception ScriptVehicle::ERR_VEHICLE_CANNOT_SEND_TO_DEPOT
 	 * @return True if the current order was changed.
@@ -492,7 +503,7 @@ public:
 	 * Sends the given vehicle to a depot for servicing. If the vehicle has
 	 * already been sent to a depot it continues with its normal orders instead.
 	 * @param vehicle_id The vehicle to send to a depot for servicing.
-	 * @pre IsValidVehicle(vehicle_id).
+	 * @pre IsPrimaryVehicle(vehicle_id).
 	 * @game @pre Valid ScriptCompanyMode active in scope.
 	 * @exception ScriptVehicle::ERR_VEHICLE_CANNOT_SEND_TO_DEPOT
 	 * @return True if the current order was changed.
@@ -502,7 +513,7 @@ public:
 	/**
 	 * Starts or stops the given vehicle depending on the current state.
 	 * @param vehicle_id The vehicle to start/stop.
-	 * @pre IsValidVehicle(vehicle_id).
+	 * @pre IsPrimaryVehicle(vehicle_id).
 	 * @game @pre Valid ScriptCompanyMode active in scope.
 	 * @exception ScriptVehicle::ERR_VEHICLE_CANNOT_START_STOP
 	 * @exception (For aircraft only): ScriptVehicle::ERR_VEHICLE_IN_FLIGHT
@@ -514,7 +525,7 @@ public:
 	/**
 	 * Turn the given vehicle so it'll drive the other way.
 	 * @param vehicle_id The vehicle to turn.
-	 * @pre IsValidVehicle(vehicle_id).
+	 * @pre IsPrimaryVehicle(vehicle_id).
 	 * @pre GetVehicleType(vehicle_id) == VT_ROAD || GetVehicleType(vehicle_id) == VT_RAIL.
 	 * @game @pre Valid ScriptCompanyMode active in scope.
 	 * @return True if and only if the vehicle has started to turn.
@@ -555,6 +566,7 @@ public:
 	/**
 	 * Get the group of a given vehicle.
 	 * @param vehicle_id The vehicle to get the group from.
+	 * @pre IsPrimaryVehicle(vehicle_id).
 	 * @return The group of the given vehicle.
 	 */
 	static GroupID GetGroupID(VehicleID vehicle_id);
@@ -571,7 +583,7 @@ public:
 	/**
 	 * Check if the vehicle has shared orders.
 	 * @param vehicle_id The vehicle to check.
-	 * @pre IsValidVehicle(vehicle_id).
+	 * @pre IsPrimaryVehicle(vehicle_id).
 	 * @return True if the vehicle has shared orders.
 	 */
 	static bool HasSharedOrders(VehicleID vehicle_id);
@@ -579,7 +591,7 @@ public:
 	/**
 	 * Get the current reliability of a vehicle.
 	 * @param vehicle_id The vehicle to check.
-	 * @pre IsValidVehicle(vehicle_id).
+	 * @pre IsPrimaryVehicle(vehicle_id).
 	 * @return The current reliability (0-100%).
 	 */
 	static int GetReliability(VehicleID vehicle_id);
@@ -590,7 +602,7 @@ public:
 	 * map distances, you may use the result of this function to compare it
 	 * with the result of ScriptOrder::GetOrderDistance.
 	 * @param vehicle_id The vehicle to get the distance for.
-	 * @pre IsValidVehicle(vehicle_id).
+	 * @pre IsPrimaryVehicle(vehicle_id).
 	 * @return The maximum distance between two orders for this vehicle
 	 *         or 0 if the distance is unlimited.
 	 * @note   The unit of the order distances is unspecified and should

src/script/api/script_vehiclelist.cpp

@@ -91,7 +91,7 @@ ScriptVehicleList_Depot::ScriptVehicleList_Depot(TileIndex tile)
 
 ScriptVehicleList_SharedOrders::ScriptVehicleList_SharedOrders(VehicleID vehicle_id)
 {
-	if (!ScriptVehicle::IsValidVehicle(vehicle_id)) return;
+	if (!ScriptVehicle::IsPrimaryVehicle(vehicle_id)) return;
 
 	for (const Vehicle *v = Vehicle::Get(vehicle_id)->FirstShared(); v != nullptr; v = v->NextShared()) {
 		this->AddItem(v->index);

src/script/api/script_waypointlist.cpp

@@ -25,7 +25,7 @@ ScriptWaypointList::ScriptWaypointList(ScriptWaypoint::WaypointType waypoint_typ
 
 ScriptWaypointList_Vehicle::ScriptWaypointList_Vehicle(VehicleID vehicle_id)
 {
-	if (!ScriptVehicle::IsValidVehicle(vehicle_id)) return;
+	if (!ScriptVehicle::IsPrimaryVehicle(vehicle_id)) return;
 
 	const Vehicle *v = ::Vehicle::Get(vehicle_id);