Neat corrections, regression fixes and additions

frontend/docs/scripting/callbacks/OnActorStreamIn.md

@@ -41,3 +41,4 @@ public OnActorStreamIn(actorid, forplayerid)
 The following callbacks might be useful, as they're related to this callback in one way or another.
 
 - [OnActorStreamOut](OnActorStreamOut): This callback is called when an actor streams out by a player's client.
+- [OnPlayerStreamIn](OnPlayerStreamIn): This callback is called when a player streams in for another player.

frontend/docs/scripting/callbacks/OnActorStreamOut.md

@@ -41,3 +41,4 @@ public OnActorStreamOut(actorid, forplayerid)
 The following callbacks might be useful, as they're related to this callback in one way or another.
 
 - [OnActorStreamIn](OnActorStreamIn): This callback is called when an actor streams in by a player's client.
+- [OnPlayerStreamOut](OnPlayerStreamOut): This callback is called when a player streams out for another player.

frontend/docs/scripting/callbacks/OnDialogResponse.md

@@ -126,13 +126,13 @@ public OnDialogResponse(playerid, dialogid, response, listitem, inputtext[])
 }
 ```
 
-**DIALOG_STYLE_TABLIST**
+**DIALOG_STYLE_TABLIST_HEADERS**
 
 ```c
 #define DIALOG_WEAPONS 3
 
 // In some command
-ShowPlayerDialog(playerid, DIALOG_WEAPONS, DIALOG_STYLE_TABLIST, "Weapons",
+ShowPlayerDialog(playerid, DIALOG_WEAPONS, DIALOG_STYLE_TABLIST_HEADERS, "Weapons",
 "Weapon\tAmmo\tPrice\n\
 M4\t120\t500\n\
 MP5\t90\t350\n\

frontend/docs/scripting/callbacks/OnGameModeExit.md

@@ -9,6 +9,12 @@ tags: []
 
 This callback is called when a gamemode ends, either through 'gmx', the server being shut down, or GameModeExit.
 
+## Returns
+
+This callback does not handle returns.
+
+It is always called first in gamemode.
+
 ## Examples
 
 ```c

frontend/docs/scripting/callbacks/OnGameModeInit.md

@@ -9,6 +9,12 @@ tags: []
 
 This callback is triggered when the gamemode starts.
 
+## Returns
+
+This callback does not handle returns.
+
+It is always called first in gamemode.
+
 ## Examples
 
 ```c

frontend/docs/scripting/callbacks/OnPlayerClickPlayer.md

@@ -39,9 +39,7 @@ public OnPlayerClickPlayer(playerid, clickedplayerid, CLICK_SOURCE:source)
 
 :::note
 
-There is currently only one 'source' (0 - `CLICK_SOURCE_SCOREBOARD`).
-
-The existence of this argument suggests that more sources may be supported in the future.
+There is currently only one 'source' (0 - `CLICK_SOURCE_SCOREBOARD`). The existence of this argument suggests that more sources may be supported in the future.
 
 :::
 

frontend/docs/scripting/callbacks/OnPlayerClickPlayerTextDraw.md

@@ -16,6 +16,8 @@ This callback is called when a player clicks on a player-textdraw. It is not cal
 
 ## Returns
 
+Returning 1 in this callback will prevent it being called in other scripts. This should be used to signal that the textdraw on which they clicked was 'found' and no further processing is needed. You should return 0 if the textdraw on which they clicked wasn't found, just like in [OnPlayerCommandText](OnPlayerCommandText).
+
 It is always called first in filterscripts so returning 1 there also blocks other scripts from processing it.
 
 ## Examples

frontend/docs/scripting/callbacks/OnPlayerClickTextDraw.md

@@ -16,6 +16,8 @@ This callback is called when a player clicks on a textdraw or cancels the select
 
 ## Returns
 
+Returning 1 in this callback will prevent it being called in other scripts. This should be used to signal that the textdraw on which they clicked was 'found' and no further processing is needed. You should return 0 if the textdraw on which they clicked wasn't found, just like in [OnPlayerCommandText](OnPlayerCommandText).
+
 It is always called first in filterscripts so returning 1 there also blocks other scripts from processing it.
 
 ## Examples
@@ -64,8 +66,7 @@ public OnPlayerClickTextDraw(playerid, Text:clickedid)
 
 :::warning
 
-- The clickable area is defined by [TextDrawTextSize](../functions/TextDrawTextSize).
-- The `x` and `y` parameters passed to that function must not be zero or negative.
+- The clickable area is defined by [TextDrawTextSize](../functions/TextDrawTextSize). The `x` and `y` parameters passed to that function must not be zero or negative.
 - Do not use [CancelSelectTextDraw](../functions/CancelSelectTextDraw) unconditionally within this callback. This results in an **infinite loop**.
 
 :::

frontend/docs/scripting/callbacks/OnPlayerCommandText.md

@@ -16,6 +16,10 @@ This callback is called when a player enters a command into the client chat wind
 
 ## Returns
 
+1 - The command was processed.
+
+0 - The command was not processed. If the command was not found both in filterscripts and in gamemode, the player will receive a `SERVER: Unknown command.` message.
+
 It is always called first in filterscripts so returning 1 there blocks other scripts from processing it.
 
 ## Examples

frontend/docs/scripting/callbacks/OnPlayerDeath.md

@@ -49,7 +49,10 @@ public OnPlayerDeath(playerid, killerid, WEAPON:reason)
 
 :::note
 
-The reason will return 37 (flame thrower) from any fire sources (e.g. molotov, 18) The reason will return 51 from any weapon that creates an explosion (e.g. RPG, grenade) You do not need to check whether killerid is valid before using it in [SendDeathMessage](../functions/SendDeathMessage). INVALID_PLAYER_ID is a valid killerid ID parameter in that function. playerid is the only one who can call the callback. (good to know for anti fake death)
+- The reason will return 37 (flame thrower) from any fire sources (e.g. molotov, 18)
+- The reason will return 51 from any weapon that creates an explosion (e.g. RPG, grenade)
+- You do not need to check whether killerid is valid before using it in [SendDeathMessage](../functions/SendDeathMessage). INVALID_PLAYER_ID is a valid killerid ID parameter in that function.
+- playerid is the only one who can call the callback. (good to know for anti fake death)
 
 :::
 

frontend/docs/scripting/callbacks/OnPlayerDisconnect.md

@@ -59,9 +59,7 @@ public OnPlayerDisconnect(playerid, reason)
 
 :::note
 
-Some functions might not work correctly when used in this callback because the player is already disconnected when the callback is called. This means that you can't get unambiguous information from functions like [GetPlayerIp](../functions/GetPlayerIp) and [GetPlayerPos](../functions/GetPlayerPos).
-
-This issue is solved in open.mp server.
+Some functions might not work correctly when used in this callback because the player is already disconnected when the callback is called. This means that you can't get unambiguous information from functions like [GetPlayerIp](../functions/GetPlayerIp) and [GetPlayerPos](../functions/GetPlayerPos). This issue is solved in open.mp server.
 
 :::
 

frontend/docs/scripting/callbacks/OnPlayerEditObject.md

@@ -100,6 +100,7 @@ The following functions might be useful, as they're related to this callback in
 - [CreateObject](../functions/CreateObject): Create an object.
 - [DestroyObject](../functions/DestroyObject): Destroy an object.
 - [MoveObject](../functions/MoveObject): Move an object.
+- [EditObject](../functions/EditObject): Edit an object.
 
 ## Related Resources
 

frontend/docs/scripting/callbacks/OnPlayerRequestClass.md

@@ -16,6 +16,8 @@ This callback is called when a player changes class at class selection (and when
 
 ## Returns
 
+Returning 0 in this callback will prevent the player from spawning. The player can be forced to spawn when [SpawnPlayer](../functions/SpawnPlayer) is used.
+
 It is always called first in filterscripts.
 
 ## Examples

frontend/docs/scripting/callbacks/OnPlayerTakeDamage.md

@@ -27,6 +27,8 @@ It is always called first in filterscripts so returning 1 there blocks other fil
 
 ## Examples
 
+**Example - Debugging**
+
 ```c
 public OnPlayerTakeDamage(playerid, issuerid, Float:amount, WEAPON:weaponid, bodypart)
 {
@@ -52,6 +54,8 @@ public OnPlayerTakeDamage(playerid, issuerid, Float:amount, WEAPON:weaponid, bod
 
 <br />
 
+**Example - One-shot-kill sniper headshots**
+
 ```c
 public OnPlayerTakeDamage(playerid, issuerid, Float:amount, WEAPON:weaponid, bodypart)
 {

frontend/docs/scripting/callbacks/OnPlayerText.md

@@ -16,6 +16,8 @@ This callback is called when a player sends a message in chat.
 
 ## Returns
 
+Returning 0 in this callback will stop the text from being sent to all players.
+
 It is always called first in filterscripts so returning 0 on it blocks other scripts from processing it.
 
 ## Examples

frontend/docs/scripting/callbacks/OnPlayerWeaponShot.md

@@ -7,7 +7,7 @@ tags: ["player"]
 
 ## Description
 
-This callback is called when a player fires a weapon. Only firearms are supported.
+This callback is called when a player fires a weapon. Only firearms are supported. Only passenger drive-by is supported (not driver drive-by, and not sea sparrow / hunter shots).
 
 | Name                    | Description                                                         |
 | ----------------------- | ------------------------------------------------------------------- |

frontend/docs/scripting/callbacks/OnRconCommand.md

@@ -15,6 +15,10 @@ This callback is called when a command is sent through the server console, RCON
 
 ## Returns
 
+0 - The command was not processed, it will be passed to another script.
+
+1 - The command was processed, it will not be passed to other scripts.
+
 It is always called first in filterscripts so returning 1 on it blocks the main script from processing it.
 
 ## Examples
@@ -25,7 +29,9 @@ public OnRconCommand(cmd[])
     printf("[RCON]: You typed '/rcon %s'!", cmd);
     return 0;
 }
+```
 
+```c
 public OnRconCommand(cmd[])
 {
     if (!strcmp(cmd, "hello", true))

frontend/docs/scripting/callbacks/OnTrailerUpdate.md

@@ -36,7 +36,8 @@ public OnTrailerUpdate(playerid, vehicleid)
 
 :::warning
 
-This callback is called very frequently per second per trailer. You should refrain from implementing intensive calculations or intensive file writing/reading operations in this callback.
+- This callback is called very frequently per second per trailer. You should refrain from implementing intensive calculations or intensive file writing/reading operations in this callback.
+- This callback is not called for trains.
 
 :::
 

frontend/docs/scripting/callbacks/OnUnoccupiedVehicleUpdate.md

@@ -23,6 +23,8 @@ This callback is called when a player's client updates/syncs the position of a v
 
 ## Returns
 
+Returning 0 in this callback will stop the vehicle's position being synced to other players. Update is still sent to the updating player.
+
 It is always called first in filterscripts so returning 0 there also blocks other scripts from processing it.
 
 ## Examples
@@ -47,6 +49,7 @@ public OnUnoccupiedVehicleUpdate(vehicleid, playerid, passenger_seat, Float:new_
 
 - This callback is called very frequently per second per unoccupied vehicle. You should refrain from implementing intensive calculations or intensive file writing/reading operations in this callback.
 - [GetVehiclePos](../functions/GetVehiclePos) will return the old coordinates of the vehicle before this update.
+- This callback is not called for trains.
 
 :::
 

frontend/docs/scripting/callbacks/OnVehicleDeath.md

@@ -34,8 +34,7 @@ public OnVehicleDeath(vehicleid, killerid)
 
 :::note
 
-- This callback will also be called when a vehicle enters water, but the vehicle can be saved from destruction by teleportation or driving out (if only partially submerged).
-- The callback won't be called a second time, and the vehicle may disappear when the driver exits, or after a short time.
+This callback will also be called when a vehicle enters water, but the vehicle can be saved from destruction by teleportation or driving out (if only partially submerged). The callback won't be called a second time, and the vehicle may disappear when the driver exits, or after a short time.
 
 :::
 

frontend/docs/scripting/callbacks/OnVehicleMod.md

@@ -17,6 +17,8 @@ This callback is called when a vehicle is modded.
 
 ## Returns
 
+Return 0 to desync the mod from propagating.
+
 It is always called first in gamemode so returning 0 there also blocks other filterscripts from processing it.
 
 ## Examples

frontend/docs/scripting/callbacks/OnVehicleRespray.md

@@ -18,6 +18,8 @@ This callback is called when a player exits a mod shop, even if the colors weren
 
 ## Returns
 
+Returning 0 in this callback will deny the colour change. Returning 1 will allow it.
+
 It is always called first in gamemode so returning 0 there also blocks other filterscripts from processing it.
 
 ## Examples

frontend/docs/scripting/functions/AddCharModel.md

@@ -35,11 +35,6 @@ public OnGameModeInit()
 }
 ```
 
-```c
-AddCharModel(305, 20001, "lvpdpc2.dff", "lvpdpc2.txd");
-AddCharModel(305, 20002, "lapdpd2.dff", "lapdpd2.txd");
-```
-
 ## Notes
 
 :::note

frontend/docs/scripting/functions/AddSimpleModel.md

@@ -35,10 +35,6 @@ public OnGameModeInit()
 }
 ```
 
-```c
-AddSimpleModel(-1, 19379, -2000, "wallzzz.dff", "wallzzz.txd");
-```
-
 ## Notes
 
 :::note

frontend/docs/scripting/functions/AddStaticPickup.md

@@ -52,6 +52,10 @@ This function doesn't return a pickup ID that you can use in, for example, OnPla
 - [CreatePickup](CreatePickup): Create a pickup.
 - [DestroyPickup](DestroyPickup): Destroy a pickup.
 
+## Related Callbacks
+
+- [OnPlayerPickUpPickup](../callbacks/OnPlayerPickUpPickup): Called when a player picks up a pickup.
+
 ## Related Resources
 
 - [Pickup IDs](../resources/pickupids)

frontend/docs/scripting/functions/BanEx.md

@@ -42,6 +42,8 @@ public OnPlayerCommandText( playerid, cmdtext[] )
 
 <br />
 
+The following code snippet shows a way of displaying a message for the player before they are banned:
+
 ```c
 // In order to display a message (eg. reason) for the player before the connection is closed
 // you have to use a timer to create a delay. This delay needs only to be a few milliseconds long,

frontend/docs/scripting/functions/CancelSelectTextDraw.md

@@ -36,9 +36,7 @@ public OnPlayerCommandText(playerid, cmdtext[])
 
 :::warning
 
-This function calls [OnPlayerClickTextDraw](../callbacks/OnPlayerClickTextDraw) with INVALID_TEXT_DRAW (65535).
-
-Using this function inside OnPlayerClickTextDraw without catching this case will cause clients to go into an infinite loop.
+This function calls [OnPlayerClickTextDraw](../callbacks/OnPlayerClickTextDraw) with INVALID_TEXT_DRAW (65535). Using this function inside OnPlayerClickTextDraw without catching this case will cause clients to go into an infinite loop.
 
 :::
 

frontend/docs/scripting/functions/Create3DTextLabel.md

@@ -63,7 +63,8 @@ drawDistance seems to be a lot smaller when spectating.
 
 :::tip
 
-Use colour embedding for multiple colours in the text.
+- Use colour embedding for multiple colours in the text.
+- To remove the background use colour with transparency less than 0xFF.
 
 :::
 

frontend/docs/scripting/functions/CreateObject.md

@@ -20,6 +20,10 @@ Creates an object at specified coordinates in the game world.
 | Float:rotationZ    | The Z rotation of the object.                                                                                             |
 | Float:drawDistance | (optional) The distance that San Andreas renders objects at. 0.0 will cause objects to render at their default distances. |
 
+## Returns
+
+The ID of the object that was created, or INVALID_OBJECT_ID if the object limit (MAX_OBJECTS) was reached.
+
 ## Examples
 
 ```c
@@ -35,7 +39,9 @@ public OnGameModeInit()
 
 :::note
 
-There is a limit of 1000 objects (MAX_OBJECTS). To circumvent this limit, you can use the [streamer](https://github.com/samp-incognito/samp-streamer-plugin) plugin.
+- Objects that emit light (lampposts, police lights, bollard lights, neons etc.) that have a greater rotation than 16.26 degrees (or -16.26) on either the X or Y axis will stop shining. This effect also applies to light objects attached to other objects, players and vehicles. If a light object is attached to a car and the car is rotated over 16.26 degrees (like in a rollover), the object will also stop emitting light. This is a GTA:SA issue, not a server bug.
+- In case the light is attached to another object, one fix for this is to set `syncRotation` to `false` in [AttachObjectToObject](AttachObjectToObject). This will ensure the light stays at 0 rotation. This would only really work for objects that consist ONLY of light, so it wouldn't work for the police light for example.
+- There is a limit of 1000 objects (MAX_OBJECTS). To circumvent this limit, you can use the [streamer](https://github.com/samp-incognito/samp-streamer-plugin) plugin.
 
 :::
 

frontend/docs/scripting/functions/CreatePlayerTextDraw.md

@@ -43,7 +43,16 @@ public OnPlayerConnect(playerid)
 
 :::note
 
-Player-textdraws are automatically destroyed when a player disconnects.
+- The `x, y` coordinate is the top left coordinate for the text draw area based on a 640x480 "canvas" (irrespective of screen resolution).
+- If you plan on using [PlayerTextDrawAlignment](PlayerTextDrawAlignment) with alignment 3 (`TEXT_DRAW_ALIGN_RIGHT`), the `x, y` coordinate is the top right coordinate for the text draw.
+- This function merely CREATES the textdraw, you must use [PlayerTextDrawShow](PlayerTextDrawShow) to show it to a player.
+- Player-textdraws are automatically destroyed when a player disconnects.
+
+:::
+
+:::tip
+
+It is recommended to use WHOLE numbers instead of decimal positions when creating player textdraws to ensure resolution friendly design.
 
 :::
 

frontend/docs/scripting/functions/DisableInteriorEnterExits.md

@@ -9,6 +9,10 @@ tags: ["interior"]
 
 Disable all the interior entrances and exits in the game (the yellow arrows at doors).
 
+## Returns
+
+This function always returns **true**.
+
 ## Examples
 
 ```c

frontend/docs/scripting/functions/DisableMenuRow.md

@@ -57,8 +57,7 @@ Crashes when passed an invalid menu ID. (Fixed in open.mp)
 :::note
 
 - This function disabled the specified menu row for all players.
-- There is no function to disable a menu row for a specific player.
-- You'd have to create two menus - one with a row disabled, and one without. Or one per player.
+- There is no function to disable a menu row for a specific player. You'd have to create two menus - one with a row disabled, and one without. Or one per player.
 
 :::
 

frontend/docs/scripting/functions/DisableNameTagLOS.md

@@ -9,6 +9,10 @@ tags: []
 
 Disables the nametag Line-Of-Sight checking so that players can see nametags through objects.
 
+## Returns
+
+This function does not return any specific values.
+
 ## Examples
 
 ```c