Feature: GS method to control engine availability for a specific company (#7791)

* Feature: GS method to allow company to use an engine before its introduction date

* Feature: GS method to retire an engine early for a specific company

7 files changed, 122 insertions, 9 deletions

diff --git a/src/command.cpp b/src/command.cpp
index ed4c457bc..ac1ac2552 100644
--- a/src/command.cpp
+++ b/src/command.cpp
@@ -105,6 +105,7 @@ CommandProc CmdIncreaseLoan;
 CommandProc CmdDecreaseLoan;
 
 CommandProc CmdWantEnginePreview;
+CommandProc CmdEngineCtrl;
 
 CommandProc CmdRenameVehicle;
 CommandProc CmdRenameEngine;
@@ -270,6 +271,7 @@ static const Command _command_proc_table[] = {
 	DEF_CMD(CmdDecreaseLoan,                                   0, CMDT_MONEY_MANAGEMENT      ), // CMD_DECREASE_LOAN
 
 	DEF_CMD(CmdWantEnginePreview,                              0, CMDT_VEHICLE_MANAGEMENT    ), // CMD_WANT_ENGINE_PREVIEW
+	DEF_CMD(CmdEngineCtrl,                             CMD_DEITY, CMDT_VEHICLE_MANAGEMENT    ), // CMD_ENGINE_CTRL
 
 	DEF_CMD(CmdRenameVehicle,                                  0, CMDT_OTHER_MANAGEMENT      ), // CMD_RENAME_VEHICLE
 	DEF_CMD(CmdRenameEngine,                          CMD_SERVER, CMDT_OTHER_MANAGEMENT      ), // CMD_RENAME_ENGINE
diff --git a/src/command_type.h b/src/command_type.h
index d03639367..2e026a63d 100644
--- a/src/command_type.h
+++ b/src/command_type.h
@@ -238,6 +238,7 @@ enum Commands {
 	CMD_DECREASE_LOAN,                ///< decrease the loan from the bank
 
 	CMD_WANT_ENGINE_PREVIEW,          ///< confirm the preview of an engine
+	CMD_ENGINE_CTRL,                  ///< control availability of the engine for companies
 
 	CMD_RENAME_VEHICLE,               ///< rename a whole vehicle
 	CMD_RENAME_ENGINE,                ///< rename a engine (in the engine list)
diff --git a/src/engine.cpp b/src/engine.cpp
index 66e68fd3c..c3e9329fb 100644
--- a/src/engine.cpp
+++ b/src/engine.cpp
@@ -710,11 +710,11 @@ void StartupEngines()
 }
 
 /**
- * Company \a company accepts engine \a eid for preview.
- * @param eid Engine being accepted (is under preview).
- * @param company Current company previewing the engine.
+ * Allows engine \a eid to be used by a company \a company.
+ * @param eid The engine to enable.
+ * @param company The company to allow using the engine.
  */
-static void AcceptEnginePreview(EngineID eid, CompanyID company)
+static void EnableEngineForCompany(EngineID eid, CompanyID company)
 {
 	Engine *e = Engine::Get(eid);
 	Company *c = Company::Get(company);
@@ -728,15 +728,45 @@ static void AcceptEnginePreview(EngineID eid, CompanyID company)
 		c->avail_roadtypes = AddDateIntroducedRoadTypes(c->avail_roadtypes | GetRoadTypeInfo(e->u.road.roadtype)->introduces_roadtypes, _date);
 	}
 
-	e->preview_company = INVALID_COMPANY;
-	e->preview_asked = (CompanyMask)-1;
 	if (company == _local_company) {
 		AddRemoveEngineFromAutoreplaceAndBuildWindows(e->type);
+
+		/* Update the toolbar. */
+		InvalidateWindowData(WC_MAIN_TOOLBAR, 0);
+		if (e->type == VEH_ROAD) InvalidateWindowData(WC_BUILD_TOOLBAR, TRANSPORT_ROAD);
+		if (e->type == VEH_SHIP) InvalidateWindowData(WC_BUILD_TOOLBAR, TRANSPORT_WATER);
 	}
+}
 
-	/* Update the toolbar. */
-	if (e->type == VEH_ROAD) InvalidateWindowData(WC_BUILD_TOOLBAR, TRANSPORT_ROAD);
-	if (e->type == VEH_SHIP) InvalidateWindowData(WC_BUILD_TOOLBAR, TRANSPORT_WATER);
+/**
+ * Forbids engine \a eid to be used by a company \a company.
+ * @param eid The engine to disable.
+ * @param company The company to forbid using the engine.
+ */
+static void DisableEngineForCompany(EngineID eid, CompanyID company)
+{
+	Engine *e = Engine::Get(eid);
+
+	ClrBit(e->company_avail, company);
+
+	if (company == _local_company) {
+		AddRemoveEngineFromAutoreplaceAndBuildWindows(e->type);
+	}
+}
+
+/**
+ * Company \a company accepts engine \a eid for preview.
+ * @param eid Engine being accepted (is under preview).
+ * @param company Current company previewing the engine.
+ */
+static void AcceptEnginePreview(EngineID eid, CompanyID company)
+{
+	Engine *e = Engine::Get(eid);
+
+	e->preview_company = INVALID_COMPANY;
+	e->preview_asked = (CompanyMask)-1;
+
+	EnableEngineForCompany(eid, company);
 
 	/* Notify preview window, that it might want to close.
 	 * Note: We cannot directly close the window.
@@ -892,6 +922,37 @@ CommandCost CmdWantEnginePreview(TileIndex tile, DoCommandFlag flags, uint32 p1,
 }
 
 /**
+ * Allow or forbid a specific company to use an engine
+ * @param tile unused
+ * @param flags operation to perform
+ * @param p1 engine id
+ * @param p2 various bitstuffed elements
+ * - p2 = (bit  0 - 7) - Company to allow/forbid the use of an engine.
+ * - p2 = (bit 31) - 0 to forbid, 1 to allow.
+ * @param text unused
+ * @return the cost of this operation or an error
+ */
+CommandCost CmdEngineCtrl(TileIndex tile, DoCommandFlag flags, uint32 p1, uint32 p2, const char *text)
+{
+	if (_current_company != OWNER_DEITY) return CMD_ERROR;
+	EngineID engine_id = (EngineID)p1;
+	CompanyID company_id = (CompanyID)GB(p2, 0, 8);
+	bool allow = HasBit(p2, 31);
+
+	if (!Engine::IsValidID(engine_id) || !Company::IsValidID(company_id)) return CMD_ERROR;
+
+	if (flags & DC_EXEC) {
+		if (allow) {
+			EnableEngineForCompany(engine_id, company_id);
+		} else {
+			DisableEngineForCompany(engine_id, company_id);
+		}
+	}
+
+	return CommandCost();
+}
+
+/**
  * An engine has become available for general use.
  * Also handle the exclusive engine preview contract.
  * @param e Engine generally available as of now.
diff --git a/src/script/api/game/game_engine.hpp.sq b/src/script/api/game/game_engine.hpp.sq
index fdef599c3..2efa1414a 100644
--- a/src/script/api/game/game_engine.hpp.sq
+++ b/src/script/api/game/game_engine.hpp.sq
@@ -46,6 +46,8 @@ void SQGSEngine_Register(Squirrel *engine)
 	SQGSEngine.DefSQStaticMethod(engine, &ScriptEngine::IsArticulated,           "IsArticulated",           2, ".i");
 	SQGSEngine.DefSQStaticMethod(engine, &ScriptEngine::GetPlaneType,            "GetPlaneType",            2, ".i");
 	SQGSEngine.DefSQStaticMethod(engine, &ScriptEngine::GetMaximumOrderDistance, "GetMaximumOrderDistance", 2, ".i");
+	SQGSEngine.DefSQStaticMethod(engine, &ScriptEngine::EnableForCompany,        "EnableForCompany",        3, ".ii");
+	SQGSEngine.DefSQStaticMethod(engine, &ScriptEngine::DisableForCompany,       "DisableForCompany",       3, ".ii");
 
 	SQGSEngine.PostRegister(engine);
 }
diff --git a/src/script/api/game_changelog.hpp b/src/script/api/game_changelog.hpp
index 74fdb6423..235dcee98 100644
--- a/src/script/api/game_changelog.hpp
+++ b/src/script/api/game_changelog.hpp
@@ -25,6 +25,8 @@
  * \li GSRoad::RoadVehHasPowerOnRoad
  * \li GSRoad::ConvertRoadType
  * \li GSRoad::GetMaxSpeed
+ * \li GSEngine::EnableForCompany
+ * \li GSEngine::DisableForCompany
  *
  * \b 1.9.0
  *
diff --git a/src/script/api/script_engine.cpp b/src/script/api/script_engine.cpp
index 6b1e267ff..1ec1b23a8 100644
--- a/src/script/api/script_engine.cpp
+++ b/src/script/api/script_engine.cpp
@@ -276,3 +276,25 @@
 			return 0;
 	}
 }
+
+/* static */ bool ScriptEngine::EnableForCompany(EngineID engine_id, ScriptCompany::CompanyID company)
+{
+	company = ScriptCompany::ResolveCompanyID(company);
+
+	EnforcePrecondition(false, ScriptObject::GetCompany() == OWNER_DEITY);
+	EnforcePrecondition(false, IsValidEngine(engine_id));
+	EnforcePrecondition(false, company != ScriptCompany::COMPANY_INVALID);
+
+	return ScriptObject::DoCommand(0, engine_id, (uint32)company | (1 << 31), CMD_ENGINE_CTRL);
+}
+
+/* static */ bool ScriptEngine::DisableForCompany(EngineID engine_id, ScriptCompany::CompanyID company)
+{
+	company = ScriptCompany::ResolveCompanyID(company);
+
+	EnforcePrecondition(false, ScriptObject::GetCompany() == OWNER_DEITY);
+	EnforcePrecondition(false, IsValidEngine(engine_id));
+	EnforcePrecondition(false, company != ScriptCompany::COMPANY_INVALID);
+
+	return ScriptObject::DoCommand(0, engine_id, company, CMD_ENGINE_CTRL);
+}
diff --git a/src/script/api/script_engine.hpp b/src/script/api/script_engine.hpp
index 4a570fb9c..f6bdbedbf 100644
--- a/src/script/api/script_engine.hpp
+++ b/src/script/api/script_engine.hpp
@@ -287,6 +287,29 @@ public:
 	 * @see ScriptOrder::GetOrderDistance
 	 */
 	static uint GetMaximumOrderDistance(EngineID engine_id);
+
+	/**
+	 * Allows a company to use an engine before its intro date or after retirement.
+	 * @param engine_id The engine to enable.
+	 * @param company_id The company to allow using the engine.
+	 * @pre IsValidEngine(engine_id).
+	 * @pre ScriptCompany.ResolveCompanyID(company_id) != ScriptCompany::COMPANY_INVALID.
+	 * @return True if the action succeeded.
+	 * @api -ai
+	 */
+	static bool EnableForCompany(EngineID engine_id, ScriptCompany::CompanyID company_id);
+
+	/**
+	 * Forbids a company to use an engine before its natural retirement.
+	 * @param engine_id The engine to disable.
+	 * @param company_id The company to forbid using the engine.
+	 * @pre IsValidEngine(engine_id).
+	 * @pre ScriptCompany.ResolveCompanyID(company_id) != ScriptCompany::COMPANY_INVALID.
+	 * @return True if the action succeeded.
+	 * @api -ai
+	 */
+	static bool DisableForCompany(EngineID engine_id, ScriptCompany::CompanyID company_id);
+
 };
 
 #endif /* SCRIPT_ENGINE_HPP */