feat(natives/misc): add descriptions and examples for the wind natives (

#1181)

* feat(natives/misc): Add desc, return value and examples for GET_WIND_DIRECTION

* feat(natives/misc): Add return value and examples for GET_WIND_SPEED

* fix(naitves/misc): correct math in js example for GET_WIND_DIRECTION

* feat(natives/misc): add csharp examples for GET_WIND_DIRECTION and GET_WIND_SPEED

* style(natives/misc): condense js example array for GET_WIND_SPEED

Makes it easier to read, the lua one stays as is because it would become to long horizontally since we are forced to specify the indexes.

* feat(natives/misc): add desc and examples to SET_WIND_* natives

Some very basic examples, unsure if there is any better way to write the examples without making it too complicated.

MISC/GetWindDirection.md

@@ -8,5 +8,72 @@ ns: MISC
 Vector3 GET_WIND_DIRECTION();
 ```
 
+Used for hunting in singleplayer and for golfing in both sp and online. The [`GET_HEADING_FROM_VECTOR_2D`](#_0x2FFB6B224F4B2926) native can be used to get the wind heading from the direction.
 
 ## Return value
+The wind direction
+
+## Examples
+```lua
+CreateThread(function()
+    while true do
+        local windDirection = GetWindDirection()
+
+        -- Gets the wind direction in degrees (math.atan converts the inverse tangent into radians and then math.deg converts it from radians to degrees)
+        local degrees = math.deg(math.atan(windDirection.x, windDirection.y))
+        print("wind direction in degrees:", degrees)
+
+        -- Draws an airplane marker above the player's head to show the wind direction
+        local coords = GetEntityCoords(PlayerPedId())
+        DrawMarker(7, coords.x, coords.y, coords.z + 1.0, windDirection.x, windDirection.y, 0.0, 0.0, 0.0, 0.0, 2.0, 2.0, 2.0, 255, 128, 0, 50, false, false, 2, false, nil, nil, false)
+
+        -- Get world heading from the direction
+        print("wind direction in world heading:", GetHeadingFromVector_2d(windDirection.x, windDirection.y))
+
+        Wait(0)
+    end
+end)
+```
+
+```js
+setTick(() => {
+    const [windDirectionX, windDirectionY, _windDirectionZ] = GetWindDirection();
+
+    // Gets the wind direction in degrees (Math.atan2 converts the inverse tangent into radians and then we coverte the radians to degrees)
+    const degrees = Math.atan2(windDirectionX, windDirectionY) * (180 / Math.PI);
+    console.log(`wind direction in degrees: ${degrees}`);
+
+    // Draws an airplane marker above the player's head to show the wind direction
+    const [playerX, playerY, playerZ] = GetEntityCoords(PlayerPedId());
+    DrawMarker(7, playerX, playerY, playerZ + 1.0, windDirectionX, windDirectionY, 0.0, 0.0, 0.0, 0.0, 2.0, 2.0, 2.0, 255, 128, 0, 50, false, false, 2, false, null, null, false);
+
+    // Get world heading from the direction
+    console.log(`wind direction in world heading: ${GetHeadingFromVector_2d(windDirectionX, windDirectionY)}`);
+});
+```
+
+```cs
+using static CitizenFX.Core.Native.API;
+// ...
+
+public Main() 
+{
+    Tick += OnTick;
+}
+
+private async Task OnTick()
+{
+    Vector3 windDirection = GetWindDirection();
+
+    // Gets the wind direction in degrees (Math.Atan2 converts the inverse tangent into radians and then we coverte the radians to degrees)
+    var degrees = Math.Atan2(windDirection.X, windDirection.Y) * (180 / Math.PI);
+    Debug.WriteLine($"wind direction in degrees: {degrees}");
+
+    // Draws an airplane marker above the player's head to show the wind direction
+    Vector3 playerCoords = Game.PlayerPed.Position;
+    DrawMarker(7, playerCoords.X, playerCoords.Y, playerCoords.Z + 1f, windDirection.X, windDirection.Y, 0f, 0f, 0f, 0f, 2f, 2f, 2f, 255, 128, 0, 50, false, false, 2, false, null, null, false);
+
+    // Get world heading from the direction
+    Debug.WriteLine($"wind direction in world heading: {GetHeadingFromVector_2d(windDirection.X, windDirection.Y)}");
+}
+```

MISC/GetWindSpeed.md

@@ -8,5 +8,61 @@ ns: MISC
 float GET_WIND_SPEED();
 ```
 
-
 ## Return value
+The wind speed in meters per second
+
+## Examples
+```lua
+local beaufortScale = {
+    [0] = 0.2,
+    [1] = 1.5,
+    [2] = 3.3,
+    [3] = 5.4,
+    [4] = 7.9,
+    [5] = 10.7,
+    [6] = 13.8,
+    [7] = 17.1,
+    [8] = 20.7,
+    [9] = 24.4,
+    [10] = 28.4,
+    [11] = 32.6,
+    [12] = 32.7
+}
+
+local windSpeed = GetWindSpeed()
+for i = 0, 12 do
+    if windSpeed <= beaufortScale[i] or i == 12 then
+        print(string.format("The current wind speed (%.2f m/s) is the equivalent to Beaufort number %s on the Beaufort scale", windSpeed, i))
+        break
+    end
+end
+```
+
+```js
+const beaufortScale = [ 0.2, 1.5, 3.3, 5.4, 7.9, 10.7, 13.8, 17.1, 20.7, 24.4, 28.4, 32.6, 32.7 ];
+const windSpeed = GetWindSpeed();
+
+for (let i = 0; i < beaufortScale.length; i++) {
+    if (windSpeed <= beaufortScale[i] || i == 12) {
+        console.log(`The current wind speed (${windSpeed.toFixed(2)} m/s) is the equivalent to Beaufort number ${i} on the Beaufort scale`);
+        break;
+    };
+};
+```
+
+```cs
+using static CitizenFX.Core.Native.API;
+// ...
+
+float[] beaufortScale = { 0.2f, 1.5f, 3.3f, 5.4f, 7.9f, 10.7f, 13.8f, 17.1f, 20.7f, 24.4f, 28.4f, 32.6f, 32.7f };
+var windSpeed = GetWindSpeed();
+
+for (int i = 0; i < beaufortScale.Length; i++)
+{
+    if (windSpeed <= beaufortScale[i] || i == 12)
+    {
+        Debug.WriteLine($"The current wind speed ({windSpeed} m/s) the equivalent to Beaufort number {i} on the Beaufort scale");
+        break;
+    }
+}
+```

MISC/SetWind.md

@@ -8,10 +8,41 @@ ns: MISC
 void SET_WIND(float speed);
 ```
 
+Sets the the raw wind speed value. The wind speed will stay persistent until it is reset (see examples).
+
+## Parameters
+* **speed**: The wind speed (clamped to between 0.0 and 1.0)
+
+## Examples
+```lua
+-- Stops all and any wind
+SetWind(0)
+
+-- Sets the wind to 6 m/s
+SetWind(0.5)
+
+-- Allows the game dynamically change the wind again
+SetWind(-1)
 ```
-Sets the the raw wind speed value.  
+
+```js
+// Stops all and any wind
+SetWind(0);
+
+// Sets the wind to 6 m/s
+SetWind(0.5);
+
+// Allows the game dynamically change the wind again
+SetWind(-1);
 ```
 
-## Parameters
-* **speed**: 
+```cs
+// Stops all and any wind
+SetWind(0f);
 
+// Sets the wind to 6 m/s
+SetWind(0.5f);
+
+// Allows the game dynamically change the wind again
+SetWind(-1f);
+```

MISC/SetWindDirection.md

@@ -8,7 +8,7 @@ ns: MISC
 void SET_WIND_DIRECTION(float direction);
 ```
 
-Sets the wind direction.
+Sets the wind direction. The wind direction will stay persistent until it is reset (see examples).
 
 ## Parameters
 * **direction**: the [wind direction](https://en.wikipedia.org/wiki/Wind_direction) in radians
@@ -17,9 +17,23 @@ Sets the wind direction.
 ```lua
 -- 180 degrees, wind will blow from the south
 SetWindDirection(math.rad(180.0))
+
+-- Allows the game to dynamically change the wind direction again
+SetWindDirection(-1)
+```
+
+```js
+// 180 degrees, wind will blow from the south
+SetWindDirection(180.0 * (Math.PI / 180));
+
+// Allows the game to dynamically change the wind direction again
+SetWindDirection(-1);
 ```
 
 ```cs
 // 180 degrees, wind will blow from the south
 SetWindDirection(3.1415f);
+
+// Allows the game to dynamically change the wind direction again
+SetWindDirection(-1f);
 ```

MISC/SetWindSpeed.md

@@ -8,10 +8,41 @@ ns: MISC
 void SET_WIND_SPEED(float speed);
 ```
 
+Using this native will clamp the wind speed value to a range of 0.0 - 12.0. The wind speed will stay persistent until it is reset (see examples).
+
+## Parameters
+* **speed**: wind speed in meters per second
+
+## Examples
+```lua
+-- Sets the wind speed to 0 meters per second
+SetWind(0)
+
+-- Sets the wind to 11.99 m/s
+SetWind(11.99)
+
+-- Allows the game dynamically change the wind speed again
+SetWind(-1)
 ```
-Using this native will clamp the wind speed value to a range of 0.0- 12.0. Using SET_WIND sets the same value but without the restriction.  
+
+```js
+// Sets the wind speed to 0 meters per second
+SetWind(0);
+
+// Sets the wind to 11.99 m/s
+SetWind(11.99);
+
+// Allows the game dynamically change the wind speed again
+SetWind(-1);
 ```
 
-## Parameters
-* **speed**: 
+```cs
+// Sets the wind speed to 0 meters per second
+SetWind(0f);
 
+// Sets the wind to 11.99 m/s
+SetWind(11.99f);
+
+// Allows the game dynamically change the wind speed again
+SetWind(-1f);
+```