expose Vehicle.spin_sprite to Car scripting (#22392)

* expose spinSprite to Car scripting

---------

Co-authored-by: Guy Sviry <guy@axissecurity.com>

distribution/changelog.txt

@@ -1,6 +1,7 @@
 0.4.14 (in development)
 ------------------------------------------------------------------------
 - Feature: [#15750] Allow using different types of park entrance in one park.
+- Feature: [#22392] [Plugin] Expose ride vehicle’s spin to the plugin API.
 - Feature: [#22414] Finance graphs can be resized.
 - Change: [#21659] Increase the Hybrid Roller Coaster’s maximum lift speed to 17 km/h (11 mph).
 - Change: [#22466] The Clear Scenery tool now uses a bulldozer cursor instead of a generic crosshair.

distribution/openrct2.d.ts

@@ -2562,6 +2562,14 @@ declare global {
          */
         status: VehicleStatus;
 
+
+        /**
+         * Current vehicle spin rotation.
+         * Values are 0-255. The game actually only considers the higher
+         * 5 bits when rendering.
+         */
+        spin: number;
+
         /**
          * The location and direction of where the car is on the track.
          */

src/openrct2/scripting/ScriptEngine.h

@@ -46,7 +46,7 @@ namespace OpenRCT2
 
 namespace OpenRCT2::Scripting
 {
-    static constexpr int32_t OPENRCT2_PLUGIN_API_VERSION = 97;
+    static constexpr int32_t OPENRCT2_PLUGIN_API_VERSION = 98;
 
     // Versions marking breaking changes.
     static constexpr int32_t API_VERSION_33_PEEP_DEPRECATION = 33;

src/openrct2/scripting/bindings/entity/ScVehicle.cpp

@@ -83,6 +83,7 @@ namespace OpenRCT2::Scripting
             ctx, &ScVehicle::poweredAcceleration_get, &ScVehicle::poweredAcceleration_set, "poweredAcceleration");
         dukglue_register_property(ctx, &ScVehicle::poweredMaxSpeed_get, &ScVehicle::poweredMaxSpeed_set, "poweredMaxSpeed");
         dukglue_register_property(ctx, &ScVehicle::status_get, &ScVehicle::status_set, "status");
+        dukglue_register_property(ctx, &ScVehicle::spin_get, &ScVehicle::spin_set, "spin");
         dukglue_register_property(ctx, &ScVehicle::guests_get, nullptr, "peeps");
         dukglue_register_property(ctx, &ScVehicle::guests_get, nullptr, "guests");
         dukglue_register_property(ctx, &ScVehicle::gForces_get, nullptr, "gForces");
@@ -476,6 +477,25 @@ namespace OpenRCT2::Scripting
         }
     }
 
+    uint8_t ScVehicle::spin_get() const
+    {
+        auto vehicle = GetVehicle();
+        if (vehicle != nullptr)
+        {
+            return vehicle->spin_sprite;
+        }
+        return 0;
+    }
+    void ScVehicle::spin_set(const uint8_t value)
+    {
+        ThrowIfGameStateNotMutable();
+        auto vehicle = GetVehicle();
+        if (vehicle != nullptr)
+        {
+            vehicle->spin_sprite = value;
+        }
+    }
+
     std::vector<DukValue> ScVehicle::guests_get() const
     {
         auto ctx = GetContext()->GetScriptEngine().GetContext();

src/openrct2/scripting/bindings/entity/ScVehicle.hpp

@@ -91,6 +91,9 @@ namespace OpenRCT2::Scripting
         std::string status_get() const;
         void status_set(const std::string& value);
 
+        uint8_t spin_get() const;
+        void spin_set(uint8_t value);
+
         std::vector<DukValue> guests_get() const;
 
         DukValue gForces_get() const;