feat(natives/streaming): examples and updated natives for switch tran…

…sition (#935)

* feat(natives/streaming): examples and updated natives for switch transition

* Update SwitchToMultiFirstpart.md

Moved the note out of the code block.

* Update SetCloudsAlpha.md

Nitpicking on some grammar and slight correctness on what this native actually does.

---------

Co-authored-by: ammonia-cfx <[email protected]>

MISC/SetCloudsAlpha.md

@@ -0,0 +1,43 @@
+---
+ns: MISC
+aliases: ["0xF36199225D6D8C86", "_SET_CLOUD_HAT_OPACITY"]
+---
+## SET_CLOUDS_ALPHA
+
+```c
+// 0xF36199225D6D8C86
+void SET_CLOUDS_ALPHA(float opacity);
+```
+
+Allows modification of the cloud opacity. It can also be used in other contexts, such as when the player is in a switch state [`IS_PLAYER_SWITCH_IN_PROGRESS`](#_0xD9D2CFFF49FAB35F).
+
+
+## Parameters
+* **opacity**: The opacity value to set for clouds.
+
+
+## Examples
+```lua
+-- Check if the player is in a Switch "state"
+if IsPlayerSwitchInProgress() then
+    -- If the player is in a Switch state, set the clouds opacity to 1.0
+    SetCloudsAlpha(1.0)
+end
+```
+
+```js
+// Check if the player is in a Switch "state"
+if (IsPlayerSwitchInProgress()) {
+    // If the player is in a Switch state, set the clouds opacity to 1.0
+    SetCloudsAlpha(1.0);
+}
+```
+
+```cs
+using static CitizenFX.Core.Native.API;
+// Check if the player is in a Switch "state"
+if (IsPlayerSwitchInProgress()) {
+    // If the player is in a Switch state, set the clouds opacity to 1.0
+    SetCloudsAlpha(1f);
+}
+```

STREAMING/GetPlayerSwitchState.md

@@ -8,5 +8,36 @@ ns: STREAMING
 int GET_PLAYER_SWITCH_STATE();
 ```
 
-
 ## Return value
+- Returns 5 if the player is in the air (in a state of switch).
+- Returns 12 if the player is either not in the air or if the switch is completed.
+
+## Examples
+```lua	
+local stateSwitch = GetPlayerSwitchState()
+if stateSwitch == 5 then
+    -- Player is in the air
+    elseif stateSwitch == 12 then
+    -- Player is not in the air or switch is completed
+end
+```
+
+```javascript
+const stateSwitch = GetPlayerSwitchState();
+if (stateSwitch == 5) {
+    // Player is in the air
+} else if (stateSwitch == 12) {
+    // Player is not in the air or switch is completed
+}
+```
+
+```csharp
+using static CitizenFX.Core.Native.API;
+
+int stateSwitch = GetPlayerSwitchState();
+if (stateSwitch == 5) {
+    // Player is in the air
+} else if (stateSwitch == 12) {
+    // Player is not in the air or switch is completed
+}
+```

STREAMING/SwitchToMultiFirstpart.md

@@ -0,0 +1,50 @@
+---
+ns: STREAMING
+aliases: ["0xAAB3200ED59016BC", "_SWITCH_OUT_PLAYER"]
+---
+## SWITCH_TO_MULTI_FIRSTPART
+
+```c
+// 0xAAB3200ED59016BC 0xFB4D062D
+void SWITCH_TO_MULTI_FIRSTPART(Ped ped, int flags, int switchType);
+```
+
+You can check if the player is in a Switch state with [`IS_PLAYER_SWITCH_IN_PROGRESS`](#_0xD9D2CFFF49FAB35F).
+
+_**Note:** Doesn't act normally when used on Mount Chiliad._
+
+## Parameters
+* **ped**: The Ped (player character) for which the switch is initiated.
+* **flags**: Flags control various functionalities: 0 for normal behavior, 1 for no transition, and 255 for Switch IN.
+* **switchType**: Specifies the type of switch (0 - 3): 0 for 1 step towards ped, 1 for 3 steps out from ped, 2 for 1 step out from ped, and 3 for 1 step towards ped.
+
+## Examples
+
+```lua
+-- Check if the player is in a Switch "state"
+if not IsPlayerSwitchInProgress() then
+    -- If the player is not already in a Switch state, initiate a Switch
+    SwitchToMultiFirstPart(PlayerPedId(), 0, 1)
+    -- In this case, switchType is set to 1, which means "3 steps out from ped"
+end
+```
+
+```js
+// Check if the player is in a Switch "state"
+if (!IsPlayerSwitchInProgress()) {
+    // If the player is not already in a Switch state, initiate a Switch
+    SwitchToMultiFirstPart(PlayerPedId(), 0, 1);
+    // In this case, switchType is set to 1, which means "3 steps out from ped" according to the documentation
+}
+```
+
+```csharp
+using static CitizenFX.Core.Native.API;
+
+// Check if the player is in a Switch "state"
+if (!IsPlayerSwitchInProgress()) {
+    // If the player is not already in a Switch state, initiate a Switch
+    SwitchToMultiFirstPart(API.PlayerPedId(), 0, 1);
+    // In this case, switchType is set to 1, which means "3 steps out from ped" according to the documentation
+}
+```

STREAMING/SwitchToMultiSecondpart.md

@@ -0,0 +1,48 @@
+---
+ns: STREAMING
+aliases: ["0xD8295AF639FD9CB8", "_SWITCH_IN_PLAYER"]
+---
+## SWITCH_TO_MULTI_SECONDPART
+
+```c
+// 0xD8295AF639FD9CB8 0x2349373B
+void SWITCH_TO_MULTI_SECONDPART(Ped ped);
+```
+
+After using [`SWITCH_TO_MULTI_FIRSTPART`](#_0xAAB3200ED59016BC) , use this native to smoothly return the camera to the player's character.
+
+## Parameters
+* **ped**: 
+
+## Examples
+```lua
+RegisterCommand("switchPlayer", function()
+    if IsPlayerSwitchInProgress() then return end
+    local ped = PlayerPedId()
+    SwitchToMultiFirstPart(ped, 0, 1)
+    Citizen.Wait(5000)
+    SwitchToMultiSecondPart(ped)
+end, false)
+```
+
+```javascript
+RegisterCommand("switchPlayer", () => {
+    if (IsPlayerSwitchInProgress()) return;
+    const ped = PlayerPedId();
+    SwitchToMultiFirstPart(ped, 0, 1);
+    Delay(5000); // Delay doesn't exist, you have to make it yourself
+    SwitchToMultiSecondPart(ped);
+}, false);
+```
+
+```csharp
+using static CitizenFX.Core.Native.API;
+RegisterCommand("switchPlayer", new Action<int, List<object>, string>(async (user, args, raw) =>
+{
+    if (IsPlayerSwitchInProgress()) return;
+    Ped ped = PlayerPedId();
+    SwitchToMultiFirstPart(ped, 0, 1);
+    await Delay(5000);
+    SwitchToMultiSecondPart(ped);
+}), false);
+```