feat(natives/vehicles): Update natives about hover mode (deluxo/opres… (

#931) * feat(natives/vehicles): Update natives about hover mode (deluxo/opressor2) * Update SetDisableHoverModeFlight.md Remove double hashes (`##`) since that's reserved for native parameters/example headers. * Update SetHoverModeWingRatio.md Remove double hashes (`##`) since that's reserved for native parameters/example headers, also add a new line between the native `c` declaration and its description. --------- Co-authored-by: ammonia-cfx <[email protected]>
citizenfx · Nov 13, 2023 · cdfdfb5 · cdfdfb5
1 parent 502e93d
commit cdfdfb5
Show file tree

Hide file tree

Showing 9 changed files with 178 additions and 77 deletions.
diff --git a/VEHICLE/SetDisableHoverModeFlight.md b/VEHICLE/SetDisableHoverModeFlight.md
@@ -0,0 +1,37 @@
+---
+ns: VEHICLE
+aliases: ["_SET_VEHICLE_HOVER_TRANSFORM_ACTIVE"]
+---
+## SET_DISABLE_HOVER_MODE_FLIGHT
+
+```c
+// 0x2D55FE374D5FDB91
+void SET_DISABLE_HOVER_MODE_FLIGHT(Vehicle vehicle, BOOL toggle);
+```
+
+Disables wings for `Deluxo` and `Oppressor MK II`. For the Deluxo, it retracts the wings immediately, preventing flight. For the Oppressor Mk II, the wings retract after landing and take-off is not possible, though it can still glide if launched into the air.
+
+
+## Parameters
+* **vehicle**: The vehicle to which the toggle will be applied.
+* **toggle**: Boolean parameter where setting `true` disables the vehicle's wings, preventing flight. Setting it to `false` allows the vehicle to fly as usual.
+
+## Examples
+```lua
+-- In this case we are disabling the wings of the vehicle
+local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
+SetDisableHoverModeFlight(vehicle, true)
+```
+
+```js
+// In this case we are disabling the wings of the vehicle
+const vehicle = GetVehiclePedIsIn(PlayerPedId(), false);
+SetDisableHoverModeFlight(vehicle, true);
+```
+
+```cs
+// In this case we are disabling the wings of the vehicle
+using static CitizenFX.Core.Native.API;
+Vehicle vehicle = GetVehiclePedIsIn(PlayerPedId(), false);
+SetDisableHoverModeFlight(vehicle, true);
+```
diff --git a/VEHICLE/SetHoverModeWingRatio.md b/VEHICLE/SetHoverModeWingRatio.md
@@ -0,0 +1,39 @@
+---
+ns: VEHICLE
+aliases: ["_SET_SPECIALFLIGHT_WING_RATIO"]
+---
+## SET_HOVER_MODE_WING_RATIO
+
+```c
+// 0x70A252F60A3E036B
+void SET_HOVER_MODE_WING_RATIO(Vehicle vehicle, float ratio);
+```
+
+This native allows opening or closing the wings of the Deluxo/Oppressor. For the Deluxo, wing deployment depends on sufficient altitude.
+
+
+## Parameters
+* **vehicle**: The vehicle to which the ratio will be applied.
+* **ratio**: Between 0.0 and 1.0. 0.0 is wings closed, 1.0 is wings open.
+
+
+## Examples
+
+```lua
+-- In this case we are opening the wings of the vehicle
+local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
+SetHoverModeWingRatio(vehicle, 1.0)
+```
+
+```js
+// In this case we are opening the wings of the vehicle
+const vehicle = GetVehiclePedIsIn(PlayerPedId(), false);
+SetHoverModeWingRatio(vehicle, 1.0);
+```
+
+```cs
+// In this case we are opening the wings of the vehicle
+using static CitizenFX.Core.Native.API;
+Vehicle vehicle = GetVehiclePedIsIn(PlayerPedId(), false);
+SetHoverModeWingRatio(vehicle, 1f);
+```
diff --git a/VEHICLE/SetSpecialFlightModeAllowed.md b/VEHICLE/SetSpecialFlightModeAllowed.md
@@ -0,0 +1,39 @@
+---
+ns: VEHICLE
+aliases: ["0xF1211889DF15A763", "_SET_VEHICLE_HOVER_TRANSFORM_ENABLED"]
+---
+## SET_SPECIAL_FLIGHT_MODE_ALLOWED
+
+```c
+// 0xF1211889DF15A763
+void SET_SPECIAL_FLIGHT_MODE_ALLOWED(Vehicle vehicle, BOOL toggle);
+```
+
+Allows locking the hover/non-hover mode of a vehicle, such as the flying mode of the `Deluxo`. In the decompiled scripts, this native is used on `oppressor2` but couldn't get it to work on it.
+
+## Parameters
+* **vehicle**: The vehicle to which the locking state will be applied.
+* **toggle**: Boolean parameter where setting `false` locks the current state of the vehicle, preventing transitions such as the `Deluxo` or Oppressor switching between their flying and driving modes. Setting it to `true` allows changing the vehicle state as usual.
+
+## Examples
+```lua
+-- Checks the altitude of the Deluxo and locks its current mode when above 150 meters.
+-- If the Deluxo is in flying mode at this altitude, it will be unable to switch to driving mode, and vice versa.
+Citizen.CreateThread(function()
+    local coords -- Variable to store the vehicle's coordinates.
+    local vehicle -- Variable to store the vehicle entity.
+    
+    repeat
+        vehicle = GetVehiclePedIsIn(PlayerPedId(), false) -- Get the vehicle the player is currently in.
+        
+        if (GetEntityModel(vehicle) == joaat("deluxo")) then -- Check if the vehicle is a Deluxo.
+            coords = GetEntityCoords(vehicle) -- Get the current coordinates of the vehicle.
+        end
+        
+        Citizen.Wait(0) -- Wait for the next frame.
+        
+    until coords.z >= 150.0 -- Keep looping until the Deluxo is above 150 meters.
+    
+    SetSpecialFlightModeAllowed(vehicle, false) -- Lock the Deluxo's current mode (flying or driving).
+end)
+```
diff --git a/VEHICLE/SetSpecialFlightModeRatio.md b/VEHICLE/SetSpecialFlightModeRatio.md
@@ -0,0 +1,39 @@
+---
+ns: VEHICLE
+aliases: ["_SET_VEHICLE_HOVER_TRANSFORM_RATIO"]
+---
+## SET_SPECIAL_FLIGHT_MODE_RATIO
+
+```c
+// 0xD138FA15C9776837
+void SET_SPECIAL_FLIGHT_MODE_RATIO(Vehicle vehicle, float ratio);
+```
+
+Used alongside [`SET_SPECIAL_FLIGHT_MODE_TARGET_RATIO`](#_0x438B3D7CA026FE91), this function initiates hover transformation for vehicles with a hover mode, like the `Deluxo`, based on a specified ratio (0.0 to 1.0). Incorrect values can glitch the vehicle. Without pairing, vehicles revert to car mode. Ineffective on the `oppressor2`
+
+## Parameters
+* **vehicle**: The vehicle to which the ratio will be applied.
+* **ratio**: A value between 0.0 and 1.0 indicating the target state for the vehicle's hover mode transition. In decompiled scripts, a common usage is 0.75 - GetFrameTime(). Exceeding the maximum can cause the `Deluxo's` wheels to glitch, delaying their return to the initial position.
+
+## Examples
+```lua
+-- In this case we are enabling the hover mode for the vehicle and initiates hover transformation.
+local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
+SetSpecialFlightModeRatio(vehicle, 0.75 - GetFrameTime())
+SetVehicleHoverTransformPercentage(vehicle, 1.0)
+```
+
+```js
+// In this case we are enabling the hover mode for the vehicle and initiates hover transformation.
+const vehicle = GetVehiclePedIsIn(PlayerPedId(), false);
+SetSpecialFlightModeRatio(vehicle, 0.75 - GetFrameTime());
+SetVehicleHoverTransformPercentage(vehicle, 1.0);
+```
+
+```cs
+// In this case we are enabling the hover mode for the vehicle and initiates hover transformation.
+using static CitizenFX.Core.Native.API;
+Vehicle vehicle = GetVehiclePedIsIn(PlayerPedId(), false);
+SetSpecialFlightModeRatio(vehicle, 0.75f - GetFrameTime());
+SetVehicleHoverTransformPercentage(vehicle, 1f);
+```
diff --git a/...CLE/SetVehicleHoverTransformPercentage.md → VEHICLE/SetSpecialFlightModeTargetRatio.md b/...CLE/SetVehicleHoverTransformPercentage.md → VEHICLE/SetSpecialFlightModeTargetRatio.md
@@ -1,16 +1,16 @@
 ---
 ns: VEHICLE
-aliases: ["0x438B3D7CA026FE91","_SET_VEHICLE_TRANSFORM_STATE"]
+aliases: ["0x438B3D7CA026FE91","_SET_VEHICLE_TRANSFORM_STATE", "_SET_VEHICLE_HOVER_TRANSFORM_PERCENTAGE"]
 ---
-## _SET_VEHICLE_HOVER_TRANSFORM_PERCENTAGE
+## SET_SPECIAL_FLIGHT_MODE_TARGET_RATIO
 
 ```c
 // 0x438B3D7CA026FE91
-void _SET_VEHICLE_HOVER_TRANSFORM_PERCENTAGE(Vehicle vehicle, float state);
+void SET_SPECIAL_FLIGHT_MODE_TARGET_RATIO(Vehicle vehicle, float state);
 ```
 
 According to decompiled scripts this should work with the `deluxo` and `oppressor2` vehicles.
-I've only seen this work for `deluxo` though, can't figure out what it's supposed to do on `oppressor2`.
+Does nothing when used on `oppressor2`.
 
 For the deluxo:
 - Set `state` to `0.0`: Fully transform to a 'road' vehicle (non-hover mode).
@@ -26,3 +26,23 @@ Once this native is used then players will just be able to hit the vehicle trans
 ## Parameters
 * **vehicle**: The vehicle (a deluxo or oppressor2).
 * **state**: The transform state (value between 0.0 and 1.0).
+
+## Examples
+```lua
+-- In this case we are enabling the hover mode for the deluxo (fyling mode)
+local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
+SetSpecialFlightModeTargetRatio(vehicle, 1.0)
+```
+
+```js
+// In this case we are enabling the hover mode for the deluxo (fyling mode)
+const vehicle = GetVehiclePedIsIn(PlayerPedId(), false);
+SetSpecialFlightModeTargetRatio(vehicle, 1.0);
+```
+
+```cs
+// In this case we are enabling the hover mode for the deluxo (fyling mode)
+using static CitizenFX.Core.Native.API;
+Vehicle vehicle = GetVehiclePedIsIn(PlayerPedId(), false);
+SetSpecialFlightModeTargetRatio(vehicle, 1f);
+```
diff --git a/VEHICLE/SetSpecialflightWingRatio.md b/VEHICLE/SetSpecialflightWingRatio.md
diff --git a/VEHICLE/SetVehicleHoverTransformActive.md b/VEHICLE/SetVehicleHoverTransformActive.md
diff --git a/VEHICLE/SetVehicleHoverTransformEnabled.md b/VEHICLE/SetVehicleHoverTransformEnabled.md
diff --git a/VEHICLE/SetVehicleHoverTransformRatio.md b/VEHICLE/SetVehicleHoverTransformRatio.md