Add hook for vehicle crashes to plugin api (#15084)

* Add initial implementation of "vehicle.crash" hook for the scripting api

The hook will fire whenever a vehicle crashes, i.e. an individual car
explodes and it's status becomes "Crashed!"

* Update contributors.md

Add name to contributors list under the "Additional implementation (OpenRCT2)" section.

- If the added line needs to be changed or removed entirely let me know

- I added this based off of the Github wiki: "If it's the first time you're contributing with the project, make sure to update the contributors.md file by appending your name at the end of the respective list."

* Move hook code into function

* Rename hook function

Renamed function, "FireVehicleCrashHook" to "InvokeVehicleCrashHook"

* Wrap InvokeVehicleCrashHook in #ifdef

Move the #ifdef from inside the function body to the outside

* Update changelog and api version

- Added entry to changelog
- Increment API version

* Fix whitespace

Replace tab character with four spaces

* Update src/openrct2/scripting/HookEngine.cpp

Co-authored-by: Tulio Leao <tupaschoal@gmail.com>

src/openrct2/ride/Vehicle.cpp

@@ -24,6 +24,8 @@
 #include "../platform/platform.h"
 #include "../rct12/RCT12.h"
 #include "../scenario/Scenario.h"
+#include "../scripting/HookEngine.h"
+#include "../scripting/ScriptEngine.h"
 #include "../util/Util.h"
 #include "../windows/Intent.h"
 #include "../world/Map.h"
@@ -738,6 +740,31 @@ template<> bool SpriteBase::Is<Vehicle>() const
     return Type == EntityType::Vehicle;
 }
 
+#ifdef ENABLE_SCRIPTING
+/**
+ * Fires the "vehicle.crash" api hook
+ * @param vehicleId Entity id of the vehicle that just crashed
+ * @param crashId What the vehicle crashed into. Should be either "another_vehicle", "land", or "water"
+ */
+static void InvokeVehicleCrashHook(const uint16_t vehicleId, const std::string_view crashId)
+{
+    auto& hookEngine = OpenRCT2::GetContext()->GetScriptEngine().GetHookEngine();
+    if (hookEngine.HasSubscriptions(OpenRCT2::Scripting::HOOK_TYPE::VEHICLE_CRASH))
+    {
+        auto ctx = OpenRCT2::GetContext()->GetScriptEngine().GetContext();
+
+        // Create event args object
+        auto obj = OpenRCT2::Scripting::DukObject(ctx);
+        obj.Set("id", vehicleId);
+        obj.Set("crashIntoType", crashId);
+
+        // Call the subscriptions
+        auto e = obj.Take();
+        hookEngine.Call(OpenRCT2::Scripting::HOOK_TYPE::VEHICLE_CRASH, e, true);
+    }
+}
+#endif
+
 static bool vehicle_move_info_valid(
     VehicleTrackSubposition trackSubposition, track_type_t type, uint8_t direction, int32_t offset)
 {
@@ -3598,6 +3625,10 @@ void Vehicle::UpdateCollisionSetup()
 
         train->sub_state = 2;
 
+#ifdef ENABLE_SCRIPTING
+        InvokeVehicleCrashHook(train->sprite_index, "another_vehicle");
+#endif
+
         OpenRCT2::Audio::Play3D(OpenRCT2::Audio::SoundId::Crash, { train->x, train->y, train->z });
 
         ExplosionCloud::Create({ train->x, train->y, train->z });
@@ -5334,6 +5365,10 @@ void Vehicle::CrashOnLand()
     }
     SetState(Vehicle::Status::Crashed, sub_state);
 
+#ifdef ENABLE_SCRIPTING
+    InvokeVehicleCrashHook(sprite_index, "land");
+#endif
+
     if (!(curRide->lifecycle_flags & RIDE_LIFECYCLE_CRASHED))
     {
         auto frontVehicle = GetHead();
@@ -5396,6 +5431,10 @@ void Vehicle::CrashOnWater()
     }
     SetState(Vehicle::Status::Crashed, sub_state);
 
+#ifdef ENABLE_SCRIPTING
+    InvokeVehicleCrashHook(sprite_index, "water");
+#endif
+
     if (!(curRide->lifecycle_flags & RIDE_LIFECYCLE_CRASHED))
     {
         auto frontVehicle = GetHead();

src/openrct2/scripting/HookEngine.cpp

@@ -30,6 +30,7 @@ static const EnumMap<HOOK_TYPE> HooksLookupTable({
     { "ride.ratings.calculate", HOOK_TYPE::RIDE_RATINGS_CALCULATE },
     { "action.location", HOOK_TYPE::ACTION_LOCATION },
     { "guest.generation", HOOK_TYPE::GUEST_GENERATION },
+    { "vehicle.crash", HOOK_TYPE::VEHICLE_CRASH },
 });
 
 HOOK_TYPE OpenRCT2::Scripting::GetHookType(const std::string& name)

src/openrct2/scripting/HookEngine.h

@@ -39,6 +39,7 @@ namespace OpenRCT2::Scripting
         RIDE_RATINGS_CALCULATE,
         ACTION_LOCATION,
         GUEST_GENERATION,
+        VEHICLE_CRASH,
         COUNT,
         UNDEFINED = -1,
     };

src/openrct2/scripting/ScriptEngine.h

@@ -46,7 +46,7 @@ namespace OpenRCT2
 
 namespace OpenRCT2::Scripting
 {
-    static constexpr int32_t OPENRCT2_PLUGIN_API_VERSION = 31;
+    static constexpr int32_t OPENRCT2_PLUGIN_API_VERSION = 32;
 
 #    ifndef DISABLE_NETWORK
     class ScSocketBase;