From f2a2b1b21e32e9b42560398c69cbe44677fa5086 Mon Sep 17 00:00:00 2001 From: 5DROR5 <5dror55@gmail.com> Date: Fri, 10 Apr 2026 15:22:04 +0300 Subject: [PATCH 1/3] Create Client-Side.md --- docs/en/API documentation/Client-Side.md | 1299 ++++++++++++++++++++++ 1 file changed, 1299 insertions(+) create mode 100644 docs/en/API documentation/Client-Side.md diff --git a/docs/en/API documentation/Client-Side.md b/docs/en/API documentation/Client-Side.md new file mode 100644 index 000000000..cf6d2dcee --- /dev/null +++ b/docs/en/API documentation/Client-Side.md @@ -0,0 +1,1299 @@ +# BeamMP Client-Side API Documentation + +## Table of Contents + +### MPVehicleGE +- [Vehicle Functions](#vehicle-functions) +- [Player Functions](#player-functions) +- [Nametag Functions](#nametag-functions) +- [Role Functions](#role-functions) +- [Navigation Functions](#navigation-functions) +- [Object Methods](#object-methods) +- [Event Hooks](#event-hooks) + +### MPConfig +- [MPConfig Functions](#mpconfig-functions) + +### MPCoreNetwork +- [MPCoreNetwork Functions](#mpcorenetwork-functions) + +### MPGameNetwork +- [Event System Functions](#event-system-functions) +- [Keypress Functions](#keypress-functions) +- [UI Functions](#ui-functions) +- [MPGameNetwork Callbacks](#mpgamenetwork-callbacks) + +### MPHelpers +- [Encoding Functions](#encoding-functions) +- [Color Functions](#color-functions) +- [String Functions](#string-functions) +- [Table Functions](#table-functions) +- [Debug Functions](#debug-functions) + +--- + +## Vehicle Functions + +### `getGameVehicleID(serverVehicleID)` +Resolves a serverVehicleID into the gameVehicleID + +**Parameters:** +- `serverVehicleID` (string) - Format: "X-Y" where X is PlayerID and Y is VehicleID + +**Returns:** +- (number) - The game's internal vehicle ID +- (number) `-1` - If vehicle is unknown + +**Usage:** +```lua +local gameID = extensions.MPVehicleGE.getGameVehicleID("0-0") +``` + +--- + +### `getServerVehicleID(gameVehicleID)` +Resolves a gameVehicleID into the serverVehicleID + +**Parameters:** +- `gameVehicleID` (number) - The game's internal vehicle ID + +**Returns:** +- (string) - Server vehicle ID (e.g., "0-0") +- (nil) - If gameVehicleID is unknown + +**Usage:** +```lua +local serverID = extensions.MPVehicleGE.getServerVehicleID(11171) +``` + +--- + +### `getVehicleByServerID(serverVehicleID)` +Returns the complete vehicle table for this vehicle + +**Parameters:** +- `serverVehicleID` (string) - Format: "X-Y" + +**Returns:** +- (table) - Vehicle information (name, gameVehicleID, jbeam, ownerID, ownerName, isLocal, isSpawned, etc.) +- (nil) - If serverVehicleID is invalid + +**Usage:** +```lua +local vehicle = extensions.MPVehicleGE.getVehicleByServerID("0-0") +if vehicle then + print("Owner: " .. vehicle.ownerName) +end +``` + +--- + +### `getVehicleByGameID(gameVehicleID)` +Returns the complete vehicle table for this vehicle + +**Parameters:** +- `gameVehicleID` (number) - The game's internal vehicle ID + +**Returns:** +- (table) - Vehicle information +- (nil) - If gameVehicleID is invalid + +**Usage:** +```lua +local vehicle = extensions.MPVehicleGE.getVehicleByGameID(11171) +``` + +--- + +### `isOwn(gameVehicleID)` +Checks if the given vehicle belongs to this client + +**Parameters:** +- `gameVehicleID` (number) - The game's internal vehicle ID + +**Returns:** +- (boolean) - True if vehicle belongs to this client + +**Usage:** +```lua +if extensions.MPVehicleGE.isOwn(11171) then + print("This is my vehicle") +end +``` + +--- + +### `getOwnMap()` +Returns a table containing all vehicles owned by this client + +**Parameters:** +- None + +**Returns:** +- (table) - Map of owned vehicles `{[gameVehicleID] = vehicles_subtable}` + +**Usage:** +```lua +local myVehicles = extensions.MPVehicleGE.getOwnMap() +``` + +--- + +### `getVehicleMap()` +Returns a table of all known multiplayer vehicles + +**Parameters:** +- None + +**Returns:** +- (table) - Map of all vehicles `{[serverVehicleID] = gameVehicleID}` + +**Usage:** +```lua +local allVehicles = extensions.MPVehicleGE.getVehicleMap() +``` + +--- + +### `getDistanceMap()` +Returns the distance from each multiplayer vehicle to this client's point of view + +**Parameters:** +- None + +**Returns:** +- (table) - Map of distances `{[gameVehicleID] = distanceInMeters}` + +**Usage:** +```lua +local distances = extensions.MPVehicleGE.getDistanceMap() +``` + +--- + +### `getNicknameMap()` +Returns all multiplayer gameVehicleIDs with their owner names + +**Parameters:** +- None + +**Returns:** +- (table) - Map of nicknames `{[gameVehicleID] = ownerName}` + +**Usage:** +```lua +local nicknameMap = extensions.MPVehicleGE.getNicknameMap() +``` + +--- + +### `getVehicles()` +Returns the complete vehicles table + +**Parameters:** +- None + +**Returns:** +- (table) - All vehicles `{[serverVehicleID] = vehicles_subtable}` + +**Usage:** +```lua +local vehicles = extensions.MPVehicleGE.getVehicles() +for serverID, vehicle in pairs(vehicles) do + print("Vehicle: " .. vehicle.jbeam) +end +``` + +--- + +## Player Functions + +### `getPlayerByName(name)` +Returns this player's table and ID + +**Parameters:** +- `name` (string) - The player's name + +**Returns:** +- (table) - Player information (name, playerID, role, vehicles, etc.) +- (number) - The player's ID +- (nil) - If player not found + +**Usage:** +```lua +local player, playerID = extensions.MPVehicleGE.getPlayerByName("John") +if player then + print("Player ID: " .. playerID) +end +``` + +--- + +### `getPlayers()` +Returns the complete players table + +**Parameters:** +- None + +**Returns:** +- (table) - All players `{[playerID] = players_subtable}` + +**Usage:** +```lua +local players = extensions.MPVehicleGE.getPlayers() +for playerID, player in pairs(players) do + print("Player: " .. player.name) +end +``` + +--- + +## Nametag Functions + +### `setPlayerNickPrefix(targetName, tagSource, text)` +Adds a prefix to a player's nametag (displayed before the name) + +**Parameters:** +- `targetName` (string) - The player's name +- `tagSource` (string) - Unique identifier for this prefix +- `text` (string) - Text to display before the name + +**Usage:** +```lua +extensions.MPVehicleGE.setPlayerNickPrefix("John", "RANK", "1st.") +-- Result: "1st. John" +``` + +--- + +### `setPlayerNickSuffix(targetName, tagSource, text)` +Adds a suffix to a player's nametag (displayed after the name) + +**Parameters:** +- `targetName` (string) - The player's name +- `tagSource` (string) - Unique identifier for this suffix +- `text` (string) - Text to display after the name + +**Usage:** +```lua +extensions.MPVehicleGE.setPlayerNickSuffix("John", "STATUS", "[AFK]") +-- Result: "John [AFK]" +``` + +--- + +### `hideNicknames(hide)` +Turns on or off the nametag drawing from BeamMP + +**Parameters:** +- `hide` (boolean) - True to hide nametags, false to show them + +**Usage:** +```lua +extensions.MPVehicleGE.hideNicknames(true) -- Hide +extensions.MPVehicleGE.hideNicknames(false) -- Show +``` + +--- + +### `toggleNicknames()` +Toggles the displaying of nametags + +**Parameters:** +- None + +**Usage:** +```lua +extensions.MPVehicleGE.toggleNicknames() +``` + +--- + +## Role Functions + +### `setPlayerRole(playerID, tag, shorttag, red, green, blue)` +Sets a custom role for a player + +**Parameters:** +- `playerID` (number) - ID of the player +- `tag` (string) - Role tag (e.g., "VIP") +- `shorttag` (string) - Short version (e.g., "V") +- `red` (number) - Red channel (0-255) +- `green` (number) - Green channel (0-255) +- `blue` (number) - Blue channel (0-255) + +**Returns:** +- (boolean, string) - `false, "player not found"` if player doesn't exist +- (boolean, string) - `false, error` if invalid arguments +- (nil) - Nothing on success + +**Usage:** +```lua +local success, error = extensions.MPVehicleGE.setPlayerRole(0, "VIP", "V", 255, 215, 0) +if success == false then + print("Error: " .. error) +end +``` + +--- + +### `clearPlayerRole(playerID)` +Clears a custom role for a player + +**Parameters:** +- `playerID` (number) - ID of the player + +**Returns:** +- (boolean) - Always returns `false` (implementation quirk - use to check if player exists) + +**Usage:** +```lua +extensions.MPVehicleGE.clearPlayerRole(0) +``` + +--- + +### `setVehicleRole(playerIDVehicleID, tag, shorttag, red, green, blue)` +Sets a custom role for a specific vehicle + +**Parameters:** +- `playerIDVehicleID` (string) - Vehicle ID (format: "0-0") +- `tag` (string) - Role tag +- `shorttag` (string) - Short version +- `red` (number) - Red (0-255) +- `green` (number) - Green (0-255) +- `blue` (number) - Blue (0-255) + +**Returns:** +- (boolean, string) - `false, "vehicle not found"` if vehicle doesn't exist +- (boolean, string) - `false, error` if invalid arguments +- (nil) - Nothing on success + +**Usage:** +```lua +local success, error = extensions.MPVehicleGE.setVehicleRole("0-0", "Police", "POL", 0, 0, 255) +if success == false then + print("Error: " .. error) +end +``` + +--- + +### `clearVehicleRole(playerIDVehicleID)` +Clears a custom role for a vehicle + +**Parameters:** +- `playerIDVehicleID` (string) - Vehicle ID (format: "0-0") + +**Returns:** +- (boolean) - Always returns `false` (implementation quirk - use to check if vehicle exists) + +**Usage:** +```lua +extensions.MPVehicleGE.clearVehicleRole("0-0") +``` + +--- + +## Navigation Functions + +### `groundmarkerToPlayer(targetName)` +Sets a ground marker route to target player's position (static) + +**Parameters:** +- `targetName` (string) - Player's name, or nil to clear + +**Usage:** +```lua +extensions.MPVehicleGE.groundmarkerToPlayer("John") -- Set +extensions.MPVehicleGE.groundmarkerToPlayer(nil) -- Clear +``` + +--- + +### `groundmarkerFollowPlayer(targetName, dontfollow)` +Sets a ground marker route that follows target player + +**Parameters:** +- `targetName` (string) - Player's name, or nil to stop +- `dontfollow` (boolean) - If true, creates static marker + +**Usage:** +```lua +extensions.MPVehicleGE.groundmarkerFollowPlayer("John") -- Follow +extensions.MPVehicleGE.groundmarkerFollowPlayer("John", true) -- Static +extensions.MPVehicleGE.groundmarkerFollowPlayer(nil) -- Stop +``` + +--- + +### `queryRoadNodeToPosition(targetPosition, owner)` +Finds the closest road nodes to a target position + +**Parameters:** +- `targetPosition` (vec3 or table) - Target position with x, y, z +- `owner` (string) - Optional identifier (default: "target") + +**Returns:** +- (boolean) - Success status +- (number) - nodeID (if successful) + +**Usage:** +```lua +local pos = vec3(100, 200, 50) +local success, nodeID = extensions.MPVehicleGE.queryRoadNodeToPosition(pos) +``` + +--- + +## Object Methods + +### Player Object Methods + +#### `player:setNickPrefix(tagSource, text)` +Sets a prefix for this player's nametag + +**Parameters:** +- `tagSource` (string) - Unique identifier +- `text` (string) - Text to display (or nil to remove) + +**Usage:** +```lua +local player = extensions.MPVehicleGE.getPlayerByName("John") +if player then + player:setNickPrefix("STATUS", "[AFK]") +end +``` + +--- + +#### `player:setNickSuffix(tagSource, text)` +Sets a suffix for this player's nametag + +**Parameters:** +- `tagSource` (string) - Unique identifier +- `text` (string) - Text to display (or nil to remove) + +**Usage:** +```lua +local player = extensions.MPVehicleGE.getPlayerByName("John") +if player then + player:setNickSuffix("MISSION", "[In Mission]") +end +``` + +--- + +#### `player:setCustomRole(role)` +Sets a custom role for this player + +**Parameters:** +- `role` (table) - Role table: `{backcolor = {r, g, b}, tag = string, shorttag = string}` + +**Usage:** +```lua +local player = extensions.MPVehicleGE.getPlayerByName("John") +if player then + player:setCustomRole({ + backcolor = {r = 255, g = 0, b = 0}, + tag = " [VIP]", + shorttag = " [V]" + }) +end +``` + +--- + +#### `player:clearCustomRole()` +Clears the custom role for this player + +**Usage:** +```lua +local player = extensions.MPVehicleGE.getPlayerByName("John") +if player then + player:clearCustomRole() +end +``` + +--- + +### Vehicle Object Methods + +#### `vehicle:getOwner()` +Returns the owner of this vehicle + +**Returns:** +- (table) - Player object +- (number) - Player's ID + +**Usage:** +```lua +local vehicle = extensions.MPVehicleGE.getVehicleByServerID("0-0") +if vehicle then + local owner, ownerID = vehicle:getOwner() + print("Owner: " .. owner.name) +end +``` + +--- + +#### `vehicle:setCustomRole(role)` +Sets a custom role for this vehicle + +**Parameters:** +- `role` (table) - Role table: `{backcolor = {r, g, b}, tag = string, shorttag = string}` + +**Usage:** +```lua +local vehicle = extensions.MPVehicleGE.getVehicleByServerID("0-0") +if vehicle then + vehicle:setCustomRole({ + backcolor = {r = 0, g = 0, b = 255}, + tag = " [Police]", + shorttag = " [POL]" + }) +end +``` + +--- + +#### `vehicle:clearCustomRole()` +Clears the custom role for this vehicle + +**Usage:** +```lua +local vehicle = extensions.MPVehicleGE.getVehicleByServerID("0-0") +if vehicle then + vehicle:clearCustomRole() +end +``` + +--- + +#### `vehicle:setDisplayName(displayName)` +Sets a custom display name for this vehicle + +**Parameters:** +- `displayName` (string) - Custom name to display + +**Usage:** +```lua +local vehicle = extensions.MPVehicleGE.getVehicleByServerID("0-0") +if vehicle then + vehicle:setDisplayName("Patrol Car #1") +end +``` + +--- + +## Event Hooks + +BeamMP provides event hooks that you can override to execute custom code when specific events occur. **Do not call these functions directly** - instead, override them while preserving the original functionality. + +### Hook Pattern + +Always preserve the original function when overriding: + +```lua +-- Save the original function +local originalCallback = MPVehicleGE.onVehicleSpawned + +-- Override with your custom logic +MPVehicleGE.onVehicleSpawned = function(gameVehicleID) + -- Call the original first + originalCallback(gameVehicleID) + + -- Your custom code here + print("Vehicle spawned: " .. gameVehicleID) +end +``` + +--- + +### Available Event Hooks + +#### `onUpdate(dt)` +Called every frame while connected to multiplayer + +**Parameters:** +- `dt` (number) - Delta time in seconds since last frame + +**Usage:** +```lua +local originalOnUpdate = MPVehicleGE.onUpdate +MPVehicleGE.onUpdate = function(dt) + originalOnUpdate(dt) + -- Your frame-by-frame logic here +end +``` + +--- + +#### `onPreRender(dt)` +Called every frame before rendering + +**Parameters:** +- `dt` (number) - Delta time in seconds + +**Note:** +This handles nametag rendering, distance calculations, and ground markers internally. + +**Usage:** +```lua +local originalOnPreRender = MPVehicleGE.onPreRender +MPVehicleGE.onPreRender = function(dt) + originalOnPreRender(dt) + -- Your pre-render logic here +end +``` + +--- + +#### `onVehicleSpawned(gameVehicleID)` +Called when a vehicle spawns (both local and remote) + +**Parameters:** +- `gameVehicleID` (number) - The game's internal vehicle ID + +**Usage:** +```lua +local originalOnVehicleSpawned = MPVehicleGE.onVehicleSpawned +MPVehicleGE.onVehicleSpawned = function(gameVehicleID) + originalOnVehicleSpawned(gameVehicleID) + + local vehicle = extensions.MPVehicleGE.getVehicleByGameID(gameVehicleID) + if vehicle then + print(vehicle.ownerName .. " spawned a " .. vehicle.jbeam) + end +end +``` + +--- + +#### `onVehicleDestroyed(gameVehicleID)` +Called when a vehicle is destroyed/removed + +**Parameters:** +- `gameVehicleID` (number) - The game's internal vehicle ID + +**Usage:** +```lua +local originalOnVehicleDestroyed = MPVehicleGE.onVehicleDestroyed +MPVehicleGE.onVehicleDestroyed = function(gameVehicleID) + local vehicle = extensions.MPVehicleGE.getVehicleByGameID(gameVehicleID) + if vehicle then + print("Vehicle " .. vehicle.jbeam .. " was destroyed") + end + + originalOnVehicleDestroyed(gameVehicleID) +end +``` + +--- + +#### `onVehicleSwitched(oldGameVehicleID, newGameVehicleID)` +Called when player switches between vehicles + +**Parameters:** +- `oldGameVehicleID` (number) - Previous vehicle ID (or -1) +- `newGameVehicleID` (number) - New vehicle ID (or -1) + +**Usage:** +```lua +local originalOnVehicleSwitched = MPVehicleGE.onVehicleSwitched +MPVehicleGE.onVehicleSwitched = function(oldID, newID) + originalOnVehicleSwitched(oldID, newID) + + print("Switched from vehicle " .. oldID .. " to " .. newID) +end +``` + +--- + +#### `onVehicleResetted(gameVehicleID)` +Called when a vehicle is reset (local vehicles only) + +**Parameters:** +- `gameVehicleID` (number) - The game's internal vehicle ID + +**Usage:** +```lua +local originalOnVehicleResetted = MPVehicleGE.onVehicleResetted +MPVehicleGE.onVehicleResetted = function(gameVehicleID) + originalOnVehicleResetted(gameVehicleID) + + print("Vehicle " .. gameVehicleID .. " was reset") +end +``` + +--- + +#### `onVehicleColorChanged(gameVehicleID, index, paint)` +Called when a vehicle's paint color is changed + +**Parameters:** +- `gameVehicleID` (number) - The game's internal vehicle ID +- `index` (number) - Paint slot index (0, 1, or 2) +- `paint` (table) - Paint data with color information + +**Usage:** +```lua +local originalOnVehicleColorChanged = MPVehicleGE.onVehicleColorChanged +MPVehicleGE.onVehicleColorChanged = function(gameVehicleID, index, paint) + originalOnVehicleColorChanged(gameVehicleID, index, paint) + + print("Vehicle " .. gameVehicleID .. " changed paint slot " .. index) +end +``` + +--- + +#### `onVehicleReady(gameVehicleID)` +Called when a vehicle's extensions have loaded and the vehicle is fully ready + +**Parameters:** +- `gameVehicleID` (number) - The game's internal vehicle ID + +**Note:** +Use this instead of `onVehicleSpawned` if you need vehicle extensions to be loaded. + +**Usage:** +```lua +local originalOnVehicleReady = MPVehicleGE.onVehicleReady +MPVehicleGE.onVehicleReady = function(gameVehicleID) + originalOnVehicleReady(gameVehicleID) + + -- Safe to interact with vehicle extensions here + local veh = be:getObjectByID(gameVehicleID) + if veh then + veh:queueLuaCommand("print('Vehicle is ready!')") + end +end +``` + +--- + +#### `onUIInitialised()` +Called when the BeamMP UI is initialized + +**Usage:** +```lua +local originalOnUIInitialised = MPVehicleGE.onUIInitialised +MPVehicleGE.onUIInitialised = function() + originalOnUIInitialised() + + print("BeamMP UI initialized") +end +``` + +--- + +#### `onSettingsChanged()` +Called when BeamMP settings are changed + +**Usage:** +```lua +local originalOnSettingsChanged = MPVehicleGE.onSettingsChanged +MPVehicleGE.onSettingsChanged = function() + originalOnSettingsChanged() + + print("BeamMP settings changed") +end +``` + +--- + +## MPConfig Functions + +### `MPConfig.getPlayerServerID()` +Returns the local player's server-assigned ID + +**Returns:** +- (number) - The player's server ID (-1 if not set) + +**Usage:** +```lua +local myID = extensions.MPConfig.getPlayerServerID() +``` + +--- + +### `MPConfig.getNickname()` +Returns the local player's nickname + +**Returns:** +- (string) - The player's current nickname + +**Usage:** +```lua +local name = extensions.MPConfig.getNickname() +``` + +--- + +### `MPConfig.getConfig()` +Returns the BeamMP configuration settings + +**Returns:** +- (table) - Configuration table with all BeamMP settings +- (nil) - If config file doesn't exist + +**Usage:** +```lua +local config = extensions.MPConfig.getConfig() +``` + +--- + +### `MPConfig.setConfig(settingName, settingVal)` +Sets a specific configuration value + +**Parameters:** +- `settingName` (string) - Name of the setting +- `settingVal` (any) - Value to set + +**Usage:** +```lua +extensions.MPConfig.setConfig("myCustomSetting", true) +``` + +--- + +## MPCoreNetwork Functions + +### `MPCoreNetwork.getCurrentServer()` +Returns information about the current connected server + +**Returns:** +- (table) - Server data (ip, port, name, map) +- (nil) - If not connected + +**Usage:** +```lua +local server = extensions.MPCoreNetwork.getCurrentServer() +if server then + print("Server: " .. server.name) + print("IP: " .. server.ip .. ":" .. server.port) +end +``` + +--- + +## Event System Functions + +### `TriggerServerEvent(name, data)` +Sends an event to the server + +**Parameters:** +- `name` (string) - Event name +- `data` (string) - Data to send + +**Note:** +Global function. The server must have a registered handler for this event. + +**Usage:** +```lua +TriggerServerEvent("playerReady", "ready") + +-- With JSON +local data = {position = {x=100, y=200, z=50}} +TriggerServerEvent("updatePlayer", jsonEncode(data)) +``` + +--- + +### `TriggerClientEvent(name, data)` +Triggers a local client event + +**Parameters:** +- `name` (string) - Event name +- `data` (string) - Data to send + +**Note:** +Global function. Triggers locally without sending to server. + +**Usage:** +```lua +TriggerClientEvent("localUpdate", "data") +``` + +--- + +### `AddEventHandler(event_name, func, name)` +Registers a function to handle a specific event + +**Parameters:** +- `event_name` (string) - Name of the event to handle +- `func` (function) - Handler function (receives event data) +- `name` (string) - Optional internal name + +**Note:** +Global function. + +**Usage:** +```lua +AddEventHandler("playerDamage", function(data) + print("Damage: " .. data) +end) + +-- With JSON +AddEventHandler("vehicleSpawned", function(data) + local vehData = jsonDecode(data) + print("Spawned: " .. vehData.model) +end) +``` + +--- + +### `RemoveEventHandler(event_name, name)` +Removes an event handler + +**Parameters:** +- `event_name` (string) - Name of the event +- `name` (string) - Optional internal name + +**Note:** +Global function. + +**Usage:** +```lua +RemoveEventHandler("playerDamage") +``` + +--- + +## Keypress Functions + +### `onKeyPressed(keyname, func)` +Registers a function to be called when a key is pressed + +**Parameters:** +- `keyname` (string) - Name of the key (e.g., "NUMPAD1", "F1") +- `func` (function) - Function to call (receives boolean) + +**Note:** +Global function. + +**Usage:** +```lua +onKeyPressed("NUMPAD1", function(state) + print("NUMPAD1 pressed!") +end) +``` + +--- + +### `onKeyReleased(keyname, func)` +Registers a function to be called when a key is released + +**Parameters:** +- `keyname` (string) - Name of the key +- `func` (function) - Function to call (receives boolean) + +**Note:** +Global function. + +**Usage:** +```lua +onKeyReleased("NUMPAD1", function(state) + print("NUMPAD1 released!") +end) +``` + +--- + +### `addKeyEventListener(keyname, func, type)` +Registers a key event listener with customizable trigger type + +**Parameters:** +- `keyname` (string) - Name of the key +- `func` (function) - Function to call +- `type` (string) - Event type: "down", "up", or "both" (default: "both") + +**Note:** +Global function. + +**Usage:** +```lua +addKeyEventListener("F1", function(isPressed) + if isPressed then + print("F1 pressed") + else + print("F1 released") + end +end, "both") +``` + +--- + +### `getKeyState(keyname)` +Returns the current state of a key + +**Parameters:** +- `keyname` (string) - Name of the key + +**Returns:** +- (boolean) - True if pressed, false otherwise + +**Note:** +Global function. Only works for keys registered with addKeyEventListener. + +**Usage:** +```lua +local isPressed = getKeyState("NUMPAD1") +if isPressed then + print("NUMPAD1 is held down") +end +``` + +--- + +## UI Functions + +### `MPGameNetwork.spawnUiDialog(dialogInfo)` +Creates a custom interactive dialog box + +**Parameters:** +- `dialogInfo` (table) - Dialog configuration: + - `title` (string) - Dialog title (optional) + - `body` (string) - Dialog message (optional) + - `buttons` (table) - Button configurations (optional) + - `class` (string) - "experimental" for hazard lines (optional) + - `interactionID` (string) - Interaction identifier (optional) + - `reportToServer` (boolean) - Send to server (optional, default: false) + - `reportToExtensions` (boolean) - Trigger local event (optional, default: false) + +**Usage:** +```lua +-- Simple dialog +extensions.MPGameNetwork.spawnUiDialog({ + title = "Welcome", + body = "Welcome to the server!" +}) + +-- Choice dialog +extensions.MPGameNetwork.spawnUiDialog({ + title = "Choose Team", + body = "Which team?", + buttons = { + {label = "Red", key = "joinRed"}, + {label = "Blue", key = "joinBlue"} + }, + interactionID = "teamSelection", + reportToServer = true +}) +``` + +--- + +## MPGameNetwork Callbacks + +### `MPGameNetwork.onUpdate(dt)` +Called every frame while connected to multiplayer + +**Parameters:** +- `dt` (number) - Delta time in seconds + +**Usage:** +```lua +local originalOnUpdate = MPGameNetwork.onUpdate +MPGameNetwork.onUpdate = function(dt) + originalOnUpdate(dt) + -- Your code here +end +``` + +--- + +### `MPGameNetwork.onVehicleReady(gameVehicleID)` +Called when a vehicle is ready and extensions are loaded + +**Parameters:** +- `gameVehicleID` (number) - The game's internal vehicle ID + +**Usage:** +```lua +local originalOnVehicleReady = MPGameNetwork.onVehicleReady +MPGameNetwork.onVehicleReady = function(gameVehicleID) + originalOnVehicleReady(gameVehicleID) + -- Your code here +end +``` + +--- + +## Encoding Functions + +### `MPHelpers.b64encode(string)` +Encodes a string to Base64 (RFC 2045) + +**Parameters:** +- `string` (string) - String to encode + +**Returns:** +- (string) - Base64-encoded string + +**Usage:** +```lua +local encoded = extensions.MPHelpers.b64encode("Hello World") + +-- Encoding JSON +local data = {name = "Player", score = 100} +local encoded = extensions.MPHelpers.b64encode(jsonEncode(data)) +TriggerServerEvent("sendData", encoded) +``` + +--- + +### `MPHelpers.b64decode(string)` +Decodes a Base64 string (RFC 2045) + +**Parameters:** +- `string` (string) - Base64-encoded string + +**Returns:** +- (string) - Decoded string + +**Usage:** +```lua +local decoded = extensions.MPHelpers.b64decode("SGVsbG8gV29ybGQ=") + +-- Decoding JSON +AddEventHandler("receiveData", function(data) + local decoded = extensions.MPHelpers.b64decode(data) + local jsonData = jsonDecode(decoded) +end) +``` + +--- + +## Color Functions + +### `MPHelpers.hex2rgb(hex)` +Converts a hexadecimal color code to RGB values + +**Parameters:** +- `hex` (string) - Hex color code (e.g., "#FF5733" or "#F57") + +**Returns:** +- (table) - RGB values `{r, g, b}` in 0-1 range +- (table) - `{0, 0, 0}` if invalid + +**Note:** +Supports both 3-character and 6-character hex codes. + +**Usage:** +```lua +local rgb = extensions.MPHelpers.hex2rgb("#FF5733") +print(rgb[1], rgb[2], rgb[3]) -- 1.0, 0.341, 0.2 + +-- Short format +local rgb = extensions.MPHelpers.hex2rgb("#F57") +``` + +--- + +## String Functions + +### `MPHelpers.splitStringToTable(string, delimiter, convert_into)` +Splits a string by delimiter and optionally converts values + +**Parameters:** +- `string` (string) - String to split +- `delimiter` (string) - Delimiter to split by +- `convert_into` (number) - Conversion type (optional): + - `nil` or `0` - Keep as strings (default) + - `1` - Convert to numbers + - `2` - Convert to booleans + +**Returns:** +- (table) - Array of split values + +**Usage:** +```lua +-- Strings +local parts = extensions.MPHelpers.splitStringToTable("Hello,World", ",") +-- {"Hello", "World"} + +-- Numbers +local nums = extensions.MPHelpers.splitStringToTable("10,20,30", ",", 1) +-- {10, 20, 30} + +-- Parse coordinates +local coords = extensions.MPHelpers.splitStringToTable("100,200,50", ",", 1) +local x, y, z = coords[1], coords[2], coords[3] +``` + +--- + +## Table Functions + +### `MPHelpers.tableDiff(old, new)` +Compares two tables and returns their differences + +**Parameters:** +- `old` (table) - First table to compare +- `new` (table) - Second table to compare + +**Returns:** +- (table) `diff` - All keys that differ +- (table) `o` - Values from old that differ +- (table) `n` - Values from new that differ + +**Usage:** +```lua +local oldConfig = {speed = 100, damage = 50, armor = 30} +local newConfig = {speed = 120, damage = 50, armor = 40} + +local diff, oldVals, newVals = extensions.MPHelpers.tableDiff(oldConfig, newConfig) +-- diff = {speed = 120, armor = 40} + +for key, value in pairs(diff) do + print(key .. " changed from " .. oldVals[key] .. " to " .. newVals[key]) +end +``` + +--- + +## Debug Functions + +### `MPHelpers.simpletraces(level)` +Returns formatted caller information as string + +**Parameters:** +- `level` (number) - Stack level (optional, default: 2) + +**Returns:** +- (string) - Formatted string: `"source:line, namewhat name"` +- (string) - `"unknown"` if info not available + +**Usage:** +```lua +local function myFunction() + local caller = extensions.MPHelpers.simpletraces() + print("Called from: " .. caller) +end +``` + +--- + +### `MPHelpers.simpletrace(level)` +Logs caller information to console + +**Parameters:** +- `level` (number) - Stack level (optional, default: 1) + +**Note:** +Logs the calling location to the console. + +**Usage:** +```lua +local function myFunction() + extensions.MPHelpers.simpletrace() + -- Logs: "Code was called from: lua/ge/extensions/mymod.lua:42" +end +``` + +--- + +*Last updated: 01.01.2026* From 41142d591037fb183f71916a46fc1bf7336fe2ab Mon Sep 17 00:00:00 2001 From: 5DROR5 <5dror55@gmail.com> Date: Fri, 10 Apr 2026 15:28:42 +0300 Subject: [PATCH 2/3] Create Server-Side.md --- docs/en/API documentation/Server-Side.md | 1407 ++++++++++++++++++++++ 1 file changed, 1407 insertions(+) create mode 100644 docs/en/API documentation/Server-Side.md diff --git a/docs/en/API documentation/Server-Side.md b/docs/en/API documentation/Server-Side.md new file mode 100644 index 000000000..6d08c2c44 --- /dev/null +++ b/docs/en/API documentation/Server-Side.md @@ -0,0 +1,1407 @@ +## Table of Contents + +### Global +- [Global Functions](#global-functions) + +### MP +- [Players](#mp--players) +- [Vehicles](#mp--vehicles) +- [Communication](#mp--communication) +- [Events](#mp--events) +- [Utilities](#mp--utilities) + +### Util +- [Logging](#util--logging) +- [JSON](#util--json) +- [Random](#util--random) +- [Profiling](#util--profiling) + +### Http +- [Http Functions](#http) + +### FS +- [Checks](#fs--checks) +- [Operations](#fs--operations) +- [Paths](#fs--paths) + +### Events +- [Events Reference](#events) + +--- + +## Global Functions + +### `print(...)` + +Prints to the server console, prefixed with date, time and `[LUA]`. + +**Parameters:** +- `...` (any) - Values of any type. Tables are printed with their contents. + +**Usage:** +```lua +local name = "John Doe" +print("Hello, I'm", name, "and I'm", 32) +``` + +--- + +### `printRaw(...)` + +Prints to the server console without any prefix. + +**Parameters:** +- `...` (any) - Values of any type. + +--- + +### `exit()` + +Shuts down the server gracefully. Triggers the `onShutdown` event. + +--- + +## MP — Players + +### `MP.GetPlayerCount() -> number` + +Returns the number of currently connected players. + +**Returns:** +- (number) - Player count. + +--- + +### `MP.GetPlayers() -> table` + +Returns a table of all connected players. + +**Returns:** +- (table) - Map of `{[playerID] = playerName}`. + +--- + +### `MP.GetPlayerName(playerID) -> string` + +Returns the name of a player by ID. + +**Parameters:** +- `playerID` (number) - The player's ID. + +**Returns:** +- (string) - The player's name, or `""` if not found. + +**Usage:** +```lua +local player_id = 4 +print(MP.GetPlayerName(player_id)) +``` + +--- + +### `MP.GetPlayerIDByName(name) -> number` + +Returns the ID of a player by name. + +**Parameters:** +- `name` (string) - The player's name. + +**Returns:** +- (number) - The player's ID, or `-1` if not found. + +--- + +### `MP.GetPlayerIdentifiers(playerID) -> table` + +Returns identifiers for a player such as IP, BeamMP forum ID and Discord ID. + +**Parameters:** +- `playerID` (number) - The player's ID. + +**Returns:** +- (table) - Table with keys `ip`, `beammp`, `discord` (only if linked). +- (nil) - If the player was not found. + +**Usage:** +```lua +local player_id = 5 +print(MP.GetPlayerIdentifiers(player_id)) +-- { ip: "127.0.0.1", discord: "12345678987654321", beammp: "1234567" } +``` + +--- + +### `MP.GetPlayerRole(playerID) -> string|nil` + +Returns the player's role as set by the BeamMP backend. + +**Parameters:** +- `playerID` (number) - The player's ID. + +**Returns:** +- (string) - The player's role. +- (nil) - If the player was not found. + +--- + +### `MP.IsPlayerConnected(playerID) -> boolean` + +Returns whether a UDP packet has been received from the player, i.e. whether the connection is fully established. + +**Parameters:** +- `playerID` (number) - The player's ID. + +**Returns:** +- (boolean) - `true` if fully connected. + +**Usage:** +```lua +local player_id = 8 +print(MP.IsPlayerConnected(player_id)) +``` + +--- + +### `MP.IsPlayerGuest(playerID) -> boolean` + +Returns whether the player is a guest (not registered on the BeamMP forum). + +**Parameters:** +- `playerID` (number) - The player's ID. + +**Returns:** +- (boolean) - `true` if guest. + +--- + +### `MP.DropPlayer(playerID, reason?)` + +Kicks a player from the server. + +**Parameters:** +- `playerID` (number) - The player's ID. +- `reason` (string, optional) - Reason for the kick. + +**Usage:** +```lua +function ChatHandler(player_id, player_name, message) + if string.match(message, "darn") then + MP.DropPlayer(player_id, "Profanity is not allowed") + return 1 + end +end +``` + +--- + +## MP — Vehicles + +### `MP.GetPlayerVehicles(playerID) -> table` + +Returns all vehicles of a player. + +**Parameters:** +- `playerID` (number) - The player's ID. + +**Returns:** +- (table) - Map of `{[vehicleID] = dataString}` where dataString is a raw JSON string. +- (nil) - If the player has no vehicles or was not found. + +**Usage:** +```lua +local player_id = 3 +local player_vehicles = MP.GetPlayerVehicles(player_id) + +for vehicle_id, vehicle_data in pairs(player_vehicles) do + local start = string.find(vehicle_data, "{") + local formattedVehicleData = string.sub(vehicle_data, start, -1) + print(Util.JsonDecode(formattedVehicleData)) +end +``` + +--- + +### `MP.GetPositionRaw(playerID, vehicleID) -> table, string` + +Returns the current raw position of a vehicle. + +**Parameters:** +- `playerID` (number) - The player's ID. +- `vehicleID` (number) - The vehicle's ID. + +**Returns:** +- (table) - Table with keys: `pos`, `rot`, `vel`, `rvel`, `tim`, `ping`. +- (string) - Error message if one occurred, empty string on success. + +**Note:** +Each value in `pos`, `rot`, `vel`, `rvel` is a table with indices `1, 2, 3` (and `4` for `rot`). + +**Usage:** +```lua +local player_id = 4 +local vehicle_id = 0 + +local raw_pos, error = MP.GetPositionRaw(player_id, vehicle_id) +if error == "" then + local x, y, z = table.unpack(raw_pos["pos"]) + print("X:", x, "Y:", y, "Z:", z) +else + print(error) +end +``` + +--- + +### `MP.RemoveVehicle(playerID, vehicleID)` + +Removes a vehicle belonging to a player. + +**Parameters:** +- `playerID` (number) - The player's ID. +- `vehicleID` (number) - The vehicle's ID. + +**Usage:** +```lua +local player_id = 3 +local player_vehicles = MP.GetPlayerVehicles(player_id) + +for vehicle_id, vehicle_data in pairs(player_vehicles) do + MP.RemoveVehicle(player_id, vehicle_id) +end +``` + +--- + +## MP — Communication + +### `MP.SendChatMessage(playerID, message, logChat?)` + +Sends a chat message to a specific player or everyone. + +**Parameters:** +- `playerID` (number) - The player's ID, or `-1` for everyone. +- `message` (string) - The message content. +- `logChat` (boolean, optional) - Whether to log to the server log (default: `true`). + +**Note:** +This function does not return a value. + +**Usage:** +```lua +-- To a specific player +function ChatHandler(player_id, player_name, msg) + if string.match(msg, "darn") then + MP.SendChatMessage(player_id, "Please do not use profanity.") + return 1 + end +end + +-- To everyone +MP.SendChatMessage(-1, "Hello World!") +``` + +--- + +### `MP.SendNotification(playerID, message, icon?, category?)` + +Sends a notification (popup) to a specific player or everyone. + +**Parameters:** +- `playerID` (number) - The player's ID, or `-1` for everyone. +- `message` (string) - The notification content. +- `icon` (string, optional) - Notification icon. +- `category` (string, optional) - Notification category. + +**Note:** +This function does not return a value. When called with only 3 arguments (no category), the category is automatically set to the value of message. + +--- + +### `MP.ConfirmationDialog(playerID, title, body, buttons, interactionID, warning?, reportToServer?, reportToExtensions?)` + +Sends a confirmation dialog with buttons to a player. + +**Parameters:** +- `playerID` (number) - The player's ID, or `-1` for everyone. +- `title` (string) - Dialog title. +- `body` (string) - Dialog body text. +- `buttons` (table) - Array of buttons. +- `interactionID` (string) - Unique identifier for this interaction. +- `warning` (boolean, optional) - Show warning styling (default: `false`). +- `reportToServer` (boolean, optional) - Send response to server (default: `true`). +- `reportToExtensions` (boolean, optional) - Trigger local event (default: `true`). + +**Note:** +When called with only 5 arguments the function does not return a value. When called with 6–8 arguments it returns `boolean, string`. + +--- + +### `MP.TriggerClientEvent(playerID, eventName, data) -> boolean, string` + +Sends an event to a specific client or everyone. + +**Parameters:** +- `playerID` (number) - The player's ID, or `-1` for everyone. +- `eventName` (string) - The event name. +- `data` (string) - The data to send. + +**Returns:** +- (boolean) - `true` if sent successfully. Always `true` for `-1`. +- (string) - Error message if failed. + +--- + +### `MP.TriggerClientEventJson(playerID, eventName, data) -> boolean, string` + +Same as `TriggerClientEvent` but accepts a Lua table and automatically encodes it to JSON. + +**Parameters:** +- `playerID` (number) - The player's ID, or `-1` for everyone. +- `eventName` (string) - The event name. +- `data` (table) - Lua table to be JSON-encoded and sent. + +**Returns:** +- (boolean) - `true` on success. +- (string) - Error message if failed. + +--- + +## MP — Events + +### `MP.RegisterEvent(eventName, functionName)` + +Registers a function as a handler for an event. + +**Parameters:** +- `eventName` (string) - The event name. +- `functionName` (string) - The name of the Lua function to register. + +**Note:** +If the event does not exist it is created. Multiple handlers can be registered for the same event. + +**Usage:** +```lua +function ChatHandler(player_id, player_name, msg) + if msg == "hello" then + print("Hello World!") + return 0 + end +end + +MP.RegisterEvent("onChatMessage", "ChatHandler") +``` + +--- + +### `MP.TriggerLocalEvent(eventName, ...) -> table` + +Triggers an event in the current state only. Synchronous. + +**Parameters:** +- `eventName` (string) - The event name. +- `...` (any, optional) - Arguments passed to handlers. + +**Returns:** +- (table) - Table of return values from all handlers. + +**Usage:** +```lua +local Results = MP.TriggerLocalEvent("MyEvent") +print(Results) +``` + +--- + +### `MP.TriggerGlobalEvent(eventName, ...) -> table` + +Triggers an event in all states. Asynchronous. Local handlers run synchronously and immediately. + +**Parameters:** +- `eventName` (string) - The event name. +- `...` (any, optional) - Arguments. Supported types: string, number, boolean, table. + +**Returns:** +- (table) - Future-like object with: + - `:IsDone() -> boolean` — Whether all handlers have finished. + - `:GetResults() -> table` — Return values from all handlers. + +**Note:** +Call these methods with `:` not `.`. + +**Usage:** +```lua +local Future = MP.TriggerGlobalEvent("MyEvent") +while not Future:IsDone() do + MP.Sleep(100) +end +local Results = Future:GetResults() +print(Results) +``` + +--- + +### `MP.CreateEventTimer(eventName, intervalMS, strategy?)` + +Creates a timer that repeatedly triggers an event. + +**Parameters:** +- `eventName` (string) - The event to trigger. +- `intervalMS` (number) - Interval between triggers in milliseconds. +- `strategy` (number, optional) - `MP.CallStrategy.BestEffort` (default) or `MP.CallStrategy.Precise`. + +**Note:** +Intervals below 25ms are not recommended and will not be served reliably. + +**Usage:** +```lua +local seconds = 0 + +function CountSeconds() + seconds = seconds + 1 +end + +MP.RegisterEvent("EverySecond", "CountSeconds") +MP.CreateEventTimer("EverySecond", 1000) +``` + +--- + +### `MP.CancelEventTimer(eventName)` + +Cancels an existing event timer. + +**Parameters:** +- `eventName` (string) - The event name. + +**Note:** +The event may fire one more time before being cancelled due to asynchronous behaviour. + +--- + +## MP — Utilities + +### `MP.CreateTimer() -> table` + +Creates a timer object for measuring elapsed time. + +**Returns:** +- (table) - Object with: + - `:GetCurrent() -> float` — Seconds elapsed since last Start. + - `:Start()` — Resets the timer. + +**Usage:** +```lua +local mytimer = MP.CreateTimer() +-- do stuff here that needs to be timed +print(mytimer:GetCurrent()) +``` + +--- + +### `MP.GetOSName() -> string` + +Returns the name of the server's operating system. + +**Returns:** +- (string) - `"Windows"`, `"Linux"`, or `"Other"`. + +--- + +### `MP.GetServerVersion() -> number, number, number` + +Returns the server version. + +**Returns:** +- (number) - major +- (number) - minor +- (number) - patch + +**Usage:** +```lua +local major, minor, patch = MP.GetServerVersion() +print(major, minor, patch) +``` + +--- + +### `MP.Get(configID) -> value` + +Reads a server config setting by ID. + +**Parameters:** +- `configID` (number) - ID from `MP.Settings`. + +**Returns:** +- (value) - The setting's current value. + +--- + +### `MP.Set(configID, value)` + +Temporarily changes a server config setting. The change is not saved to the config file. + +**Parameters:** +- `configID` (number) - ID from `MP.Settings`. +- `value` (any) - New value. Type must match the setting. + +**Usage:** +```lua +MP.Set(MP.Settings.Debug, true) +``` + +--- + +### `MP.Settings` + +Enum of setting IDs for use with `MP.Get` and `MP.Set`. + +```lua +MP.Settings.Debug -- 0 (boolean) +MP.Settings.Private -- 1 (boolean) +MP.Settings.MaxCars -- 2 (number) +MP.Settings.MaxPlayers -- 3 (number) +MP.Settings.Map -- 4 (string) +MP.Settings.Name -- 5 (string) +MP.Settings.Description -- 6 (string) +MP.Settings.InformationPacket -- 7 (boolean) +``` + +--- + +### `MP.CallStrategy` + +Enum for use with `MP.CreateEventTimer`. + +```lua +MP.CallStrategy.BestEffort -- Skip trigger if previous handler hasn't finished (default) +MP.CallStrategy.Precise -- Always trigger, even if it causes the queue to build up +``` + +--- + +### `MP.Sleep(ms)` + +Halts the entire current Lua state for a number of milliseconds. + +**Parameters:** +- `ms` (number) - Time to sleep in milliseconds. + +**Note:** +Nothing will execute in the state while sleeping. **Do not sleep for more than 500ms** if event handlers are registered — a sleeping state can slow the entire server down significantly. + +**Usage:** +```lua +local Future = MP.TriggerGlobalEvent("MyEvent") +while not Future:IsDone() do + MP.Sleep(100) +end +``` + +--- + +### `MP.GetStateMemoryUsage() -> number` + +Returns the memory usage of the current Lua state. + +**Returns:** +- (number) - Memory in bytes. + +--- + +### `MP.GetLuaMemoryUsage() -> number` + +Returns the total memory usage of all Lua states combined. + +**Returns:** +- (number) - Memory in bytes. + +--- + +## Util — Logging + +### `Util.LogInfo(...)`, `Util.LogWarn(...)`, `Util.LogError(...)`, `Util.LogDebug(...)` + +Prints to the server log at the corresponding level. + +**Parameters:** +- `...` (any) - Values of any type. + +**Note:** +`Util.LogDebug` is only shown when `MP.Settings.Debug` is enabled. + +**Usage:** +```lua +Util.LogInfo("Hello, World!") +Util.LogWarn("Cool warning") +Util.LogError("Oh no!") +Util.LogDebug("hi") +``` + +--- + +## Util — JSON + +### `Util.JsonEncode(table) -> string` + +Encodes a Lua table into a JSON string. + +**Parameters:** +- `table` (table) - The table to encode. + +**Returns:** +- (string) - Minified JSON string. + +**Note:** +Automatically detects array vs object based on key types. Functions, userdata and unsupported types are ignored. + +**Usage:** +```lua +local player = { + name = "Lion", + age = 69, + skills = { "skill A", "skill B" } +} +local json = Util.JsonEncode(player) +-- '{"name":"Lion","age":69,"skills":["skill A","skill B"]}' +``` + +--- + +### `Util.JsonDecode(json) -> table` + +Decodes a JSON string into a Lua table. + +**Parameters:** +- `json` (string) - A valid JSON string. + +**Returns:** +- (table) - The decoded table. +- (nil) - If the JSON is invalid. + +**Usage:** +```lua +local json = "{\"message\":\"OK\",\"code\":200}" +local tbl = Util.JsonDecode(json) +-- { message = "OK", code = 200 } +``` + +--- + +### `Util.JsonPrettify(json) -> string` + +Adds indentation and newlines to a JSON string for human readability (indent of 4). + +**Parameters:** +- `json` (string) - A valid JSON string. + +**Returns:** +- (string) - Pretty-printed JSON. + +**Usage:** +```lua +local myjson = Util.JsonEncode({ name="Lion", age = 69, skills = { "skill A", "skill B" } }) +print(Util.JsonPrettify(myjson)) +``` + +--- + +### `Util.JsonMinify(json) -> string` + +Removes unnecessary whitespace and newlines from a JSON string. + +**Parameters:** +- `json` (string) - A valid JSON string. + +**Returns:** +- (string) - Minified JSON. + +**Usage:** +```lua +local pretty = Util.JsonPrettify(Util.JsonEncode({ name="Lion", age = 69 })) +print(Util.JsonMinify(pretty)) +``` + +--- + +### `Util.JsonFlatten(json) -> string` + +Flattens a nested JSON into `/a/b/c`-style keys per RFC 6901. + +**Parameters:** +- `json` (string) - A valid JSON string. + +**Returns:** +- (string) - Flattened JSON. + +**Usage:** +```lua +local json = Util.JsonEncode({ name="Lion", skills = { "skill A", "skill B" } }) +print(Util.JsonFlatten(json)) +-- '{"/name":"Lion","/skills/0":"skill A","/skills/1":"skill B"}' +``` + +--- + +### `Util.JsonUnflatten(json) -> string` + +Restores a flattened JSON back to its nested structure. + +**Parameters:** +- `json` (string) - A flattened JSON string. + +**Returns:** +- (string) - Nested JSON. + +--- + +### `Util.JsonDiff(a, b) -> string` + +Computes a diff between two JSON strings per RFC 6902. + +**Parameters:** +- `a` (string) - First JSON string. +- `b` (string) - Second JSON string. + +**Returns:** +- (string) - JSON Patch representing the differences. + +--- + +## Util — Random + +### `Util.Random() -> float` + +Returns a random float between 0 and 1. + +**Returns:** +- (float) + +**Usage:** +```lua +local rand = Util.Random() +print("rand: " .. rand) +-- rand: 0.135477 +``` + +--- + +### `Util.RandomRange(min, max) -> float` + +Returns a random float within a given range. + +**Parameters:** +- `min` (number) - Lower bound. +- `max` (number) - Upper bound. + +**Returns:** +- (float) + +**Usage:** +```lua +local randFloat = Util.RandomRange(1, 1000) +print("randFloat: " .. randFloat) +-- randFloat: 420.6969 +``` + +--- + +### `Util.RandomIntRange(min, max) -> number` + +Returns a random integer within a given range. + +**Parameters:** +- `min` (number) - Lower bound. +- `max` (number) - Upper bound. + +**Returns:** +- (number) - Integer. + +**Usage:** +```lua +local randInt = Util.RandomIntRange(1, 100) +print("randInt: " .. randInt) +-- randInt: 69 +``` + +--- + +## Util — Profiling + +### `Util.DebugStartProfile(name)` + +Starts a named execution time measurement. + +**Parameters:** +- `name` (string) - Identifier for this measurement. + +--- + +### `Util.DebugStopProfile(name)` + +Stops a named measurement. Must be called after `DebugStartProfile` with the same name. + +**Parameters:** +- `name` (string) - Identifier for this measurement. + +--- + +### `Util.DebugExecutionTime() -> table` + +Returns execution time statistics for every handler that has run. + +**Returns:** +- (table) - Per handler: `mean`, `stdev`, `min`, `max`, `n` (all in ms). + +**Usage:** +```lua +function printDebugExecutionTime() + local stats = Util.DebugExecutionTime() + local pretty = "DebugExecutionTime:\n" + local longest = 0 + for name, t in pairs(stats) do + if #name > longest then + longest = #name + end + end + for name, t in pairs(stats) do + pretty = pretty .. string.format("%" .. longest + 1 .. "s: %12f +/- %12f (min: %12f, max: %12f) (called %d time(s))\n", name, t.mean, t.stdev, t.min, t.max, t.n) + end + print(pretty) +end +``` + +--- + +## Http + +### `Http.CreateConnection(host, port) -> table` + +Creates an HTTP connection to an external server. + +**Parameters:** +- `host` (string) - Server address. +- `port` (number) - Port number. + +**Returns:** +- (table) - Connection object with method `:Get(path, headers)`. + +--- + +### `connection:Get(path, headers)` + +Sends an HTTP GET request. + +**Parameters:** +- `path` (string) - The request path. +- `headers` (table) - Headers as `{[string] = string}`. + +--- + +## FS — Checks + +### `FS.Exists(path) -> boolean` + +Returns whether a path exists. + +**Parameters:** +- `path` (string) - The path to check. + +**Returns:** +- (boolean) - `true` if exists. + +--- + +### `FS.IsDirectory(path) -> boolean` + +Returns whether a path is a directory. + +**Parameters:** +- `path` (string) - The path to check. + +**Returns:** +- (boolean) - `true` if directory. + +**Note:** +`false` does not imply the path is a file. Use `FS.IsFile` to check separately. + +--- + +### `FS.IsFile(path) -> boolean` + +Returns whether a path is a regular file. + +**Parameters:** +- `path` (string) - The path to check. + +**Returns:** +- (boolean) - `true` if regular file. + +**Note:** +`false` does not imply the path is a directory. + +--- + +## FS — Operations + +### `FS.CreateDirectory(path) -> boolean, string` + +Creates a directory including any missing parent directories (like `mkdir -p`). + +**Parameters:** +- `path` (string) - Path of the directory to create. + +**Returns:** +- (boolean) - `true` on success. +- (string) - Error message on failure, or `""` on success. + +**Usage:** +```lua +local success, error_message = FS.CreateDirectory("data/mystuff/somefolder") + +if not success then + print("failed to create directory: " .. error_message) +end +``` + +--- + +### `FS.Remove(path) -> boolean, string` + +Removes a file or empty directory. + +**Parameters:** +- `path` (string) - The path to remove. + +**Returns:** +- (boolean) - `true` on success. +- (string) - Error message on failure. + +--- + +### `FS.Rename(path, newPath) -> boolean, string` + +Renames or moves a file or directory. + +**Parameters:** +- `path` (string) - Current path. +- `newPath` (string) - New path. + +**Returns:** +- (boolean) - `true` on success. +- (string) - Error message on failure. + +--- + +### `FS.Copy(path, newPath) -> boolean, string` + +Copies a file or directory (recursive). + +**Parameters:** +- `path` (string) - Source path. +- `newPath` (string) - Destination path. + +**Returns:** +- (boolean) - `true` on success. +- (string) - Error message on failure. + +--- + +### `FS.ListFiles(path) -> table` + +Returns a list of file names in a directory (not recursive). + +**Parameters:** +- `path` (string) - Directory path. + +**Returns:** +- (table) - Array of file names. +- (nil) - If the path does not exist. + +**Usage:** +```lua +print(FS.ListFiles("Resources/Server/examplePlugin")) +-- { 1: "example.json", 2: "example.lua" } +``` + +--- + +### `FS.ListDirectories(path) -> table` + +Returns a list of directory names inside a directory (not recursive). + +**Parameters:** +- `path` (string) - Directory path. + +**Returns:** +- (table) - Array of directory names. +- (nil) - If the path does not exist. + +**Usage:** +```lua +print(FS.ListDirectories("Resources")) +-- { 1: "Client", 2: "Server" } +``` + +--- + +## FS — Paths + +### `FS.GetFilename(path) -> string` + +Returns the filename with extension from a path. + +**Parameters:** +- `path` (string) - A path string. + +**Returns:** +- (string) - The filename. + +**Usage:** +```lua +"my/path/a.txt" -> "a.txt" +"somefile.txt" -> "somefile.txt" +"/awesome/path" -> "path" +``` + +--- + +### `FS.GetExtension(path) -> string` + +Returns the file extension including the dot. + +**Parameters:** +- `path` (string) - A path string. + +**Returns:** +- (string) - The extension (e.g. `".json"`), or `""` if none. + +**Usage:** +```lua +"myfile.txt" -> ".txt" +"somefile." -> "." +"/awesome/path" -> "" +"/awesome/path/file.zip.txt" -> ".txt" +``` + +--- + +### `FS.GetParentFolder(path) -> string` + +Returns the path of the containing directory. + +**Parameters:** +- `path` (string) - A path string. + +**Returns:** +- (string) - Parent folder path. + +**Usage:** +```lua +"/var/tmp/example.txt" -> "/var/tmp" +"/" -> "/" +"mydir/a/b/c.txt" -> "mydir/a/b" +``` + +--- + +### `FS.ConcatPaths(...) -> string` + +Joins path segments together using the system's preferred separator, resolving `..` where present. + +**Parameters:** +- `...` (string) - Path segments. + +**Returns:** +- (string) - Joined path. + +**Usage:** +```lua +FS.ConcatPaths("a", "b", "/c/d/e/", "/f/", "g", "h.txt") +-- "a/b/c/d/e/f/g/h.txt" +``` + +--- + +## Events + +### Player connection order + +``` +onPlayerAuth → onPlayerConnecting → onPlayerJoining → onPlayerJoin +``` + +--- + +### `onInit` + +Triggered right after all plugin files have been loaded. + +**Arguments:** none +**Cancellable:** no + +--- + +### `onConsoleInput` + +Triggered when the server console receives input. + +**Arguments:** +- `input` (string) - The text that was entered. + +**Cancellable:** no + +**Usage:** +```lua +function handleConsoleInput(cmd) + local delim = cmd:find(' ') + if delim then + local message = cmd:sub(delim+1) + if cmd:sub(1, delim-1) == "print" then + return message + end + end +end + +MP.RegisterEvent("onConsoleInput", "handleConsoleInput") +``` + +--- + +### `onShutdown` + +Triggered when the server shuts down, after all players have been kicked. + +**Arguments:** none +**Cancellable:** no + +--- + +### `onPlayerAuth` + +Triggered when a player attempts to connect, before any other connection events. + +**Arguments:** +- `name` (string) - Player name. +- `role` (string) - Player role from the backend. +- `isGuest` (boolean) - Whether the player is a guest. +- `identifiers` (table) - Identifiers: `ip`, `beammp`, `discord`. + +**Cancellable:** yes +- Return `1` — deny with a generic message. +- Return `string` — deny with the string as the reason. +- Return `2` — allow entry even if the server is full. + +**Usage:** +```lua +function myPlayerAuthorizer(name, role, is_guest, identifiers) + return "Sorry, you cannot join at this time." +end + +MP.RegisterEvent("onPlayerAuth", "myPlayerAuthorizer") +``` + +--- + +### `postPlayerAuth` + +Triggered after `onPlayerAuth`, regardless of whether the player was accepted or rejected. + +**Arguments:** +- `wasRejected` (boolean) - Whether the player was rejected. +- `reason` (string) - Rejection reason if rejected. +- `name` (string) - Player name. +- `role` (string) - Player role. +- `isGuest` (boolean) - Whether guest. +- `identifiers` (table) - Identifiers. + +**Cancellable:** no + +--- + +### `onPlayerConnecting` + +Triggered when a player starts connecting, after `onPlayerAuth`. + +**Arguments:** +- `playerID` (number) + +**Cancellable:** no + +--- + +### `onPlayerJoining` + +Triggered after the player has finished downloading all mods. + +**Arguments:** +- `playerID` (number) + +**Cancellable:** no + +--- + +### `onPlayerJoin` + +Triggered after the player has finished syncing and entered the game. + +**Arguments:** +- `playerID` (number) + +**Cancellable:** no + +--- + +### `onPlayerDisconnect` + +Triggered when a player disconnects. + +**Arguments:** +- `playerID` (number) + +**Cancellable:** no + +--- + +### `onChatMessage` + +Triggered when a player sends a chat message. + +**Arguments:** +- `playerID` (number) +- `playerName` (string) +- `message` (string) + +**Cancellable:** yes — returning `1` prevents the message from being shown to anyone. + +**Usage:** +```lua +function MyChatMessageHandler(sender_id, sender_name, message) + if message == "darn" then + return 1 + else + return 0 + end +end + +MP.RegisterEvent("onChatMessage", "MyChatMessageHandler") +``` + +--- + +### `postChatMessage` + +Triggered after `onChatMessage`. + +**Arguments:** +- `wasSent` (boolean) - Whether the message was sent. +- `playerID` (number) +- `playerName` (string) +- `message` (string) + +**Cancellable:** no + +--- + +### `onVehicleSpawn` + +Triggered when a player spawns a new vehicle. + +**Arguments:** +- `playerID` (number) +- `vehicleID` (number) +- `data` (string) - JSON string with vehicle configuration and positional data. + +**Cancellable:** yes — returning a value other than `0` prevents the spawn. + +--- + +### `postVehicleSpawn` + +Triggered after `onVehicleSpawn`. + +**Arguments:** +- `wasSpawned` (boolean) - Whether the vehicle was actually spawned. +- `playerID` (number) +- `vehicleID` (number) +- `data` (string) + +**Cancellable:** no + +--- + +### `onVehicleEdited` + +Triggered when a player edits an existing vehicle. + +**Arguments:** +- `playerID` (number) +- `vehicleID` (number) +- `data` (string) - JSON string of the new configuration (does not include positional data). + +**Cancellable:** yes — returning a value other than `0` cancels the edit. + +--- + +### `postVehicleEdited` + +Triggered after `onVehicleEdited`. + +**Arguments:** +- `wasAllowed` (boolean) - Whether the edit was allowed. +- `playerID` (number) +- `vehicleID` (number) +- `data` (string) + +**Cancellable:** no + +--- + +### `onVehicleDeleted` + +Triggered when a vehicle is deleted. + +**Arguments:** +- `playerID` (number) +- `vehicleID` (number) + +**Cancellable:** no + +--- + +### `onVehicleReset` + +Triggered when a player resets a vehicle. + +**Arguments:** +- `playerID` (number) +- `vehicleID` (number) +- `data` (string) - JSON string of the new position and rotation (does not include configuration). + +**Cancellable:** no + +--- + +### `onVehiclePaintChanged` + +Triggered when a vehicle's paint is changed. + +**Arguments:** +- `playerID` (number) +- `vehicleID` (number) +- `data` (string) - JSON string with the new paint data. + +**Cancellable:** no + +--- + +### `onFileChanged` + +Triggered when a file in the plugin directory changes. + +**Arguments:** +- `path` (string) - Path of the changed file, relative to the server root. + +**Cancellable:** no + +**Note:** +Files added after the server has started are not tracked. From f51d9d54ecc9488c3dfcb6ab97f6957e8cac1eac Mon Sep 17 00:00:00 2001 From: 5DROR5 <5dror55@gmail.com> Date: Fri, 10 Apr 2026 15:35:41 +0300 Subject: [PATCH 3/3] Update Client-Side.md --- docs/en/API documentation/Client-Side.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/en/API documentation/Client-Side.md b/docs/en/API documentation/Client-Side.md index cf6d2dcee..97e31dd2d 100644 --- a/docs/en/API documentation/Client-Side.md +++ b/docs/en/API documentation/Client-Side.md @@ -1,5 +1,3 @@ -# BeamMP Client-Side API Documentation - ## Table of Contents ### MPVehicleGE