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: +
+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: +
+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: +
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: +
+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: +
+getOwnMap()Returns a table containing all vehicles owned by this client
+Parameters: +- None
+Returns:
+- (table) - Map of owned vehicles {[gameVehicleID] = vehicles_subtable}
Usage: +
+getVehicleMap()Returns a table of all known multiplayer vehicles
+Parameters: +- None
+Returns:
+- (table) - Map of all vehicles {[serverVehicleID] = gameVehicleID}
Usage: +
+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: +
+getNicknameMap()Returns all multiplayer gameVehicleIDs with their owner names
+Parameters: +- None
+Returns:
+- (table) - Map of nicknames {[gameVehicleID] = ownerName}
Usage: +
+getVehicles()Returns the complete vehicles table
+Parameters: +- None
+Returns:
+- (table) - All vehicles {[serverVehicleID] = vehicles_subtable}
Usage: +
local vehicles = extensions.MPVehicleGE.getVehicles()
+for serverID, vehicle in pairs(vehicles) do
+ print("Vehicle: " .. vehicle.jbeam)
+end
+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: +
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: +
local players = extensions.MPVehicleGE.getPlayers()
+for playerID, player in pairs(players) do
+ print("Player: " .. player.name)
+end
+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: +
+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: +
+hideNicknames(hide)Turns on or off the nametag drawing from BeamMP
+Parameters:
+- hide (boolean) - True to hide nametags, false to show them
Usage: +
extensions.MPVehicleGE.hideNicknames(true) -- Hide
+extensions.MPVehicleGE.hideNicknames(false) -- Show
+toggleNicknames()Toggles the displaying of nametags
+Parameters: +- None
+Usage: +
+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: +
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: +
+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: +
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: +
+groundmarkerToPlayer(targetName)Sets a ground marker route to target player's position (static)
+Parameters:
+- targetName (string) - Player's name, or nil to clear
Usage: +
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: +
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: +
local pos = vec3(100, 200, 50)
+local success, nodeID = extensions.MPVehicleGE.queryRoadNodeToPosition(pos)
+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: +
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: +
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: +
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: +
local player = extensions.MPVehicleGE.getPlayerByName("John")
+if player then
+ player:clearCustomRole()
+end
+vehicle:getOwner()Returns the owner of this vehicle
+Returns: +- (table) - Player object +- (number) - Player's ID
+Usage: +
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: +
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: +
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: +
local vehicle = extensions.MPVehicleGE.getVehicleByServerID("0-0")
+if vehicle then
+ vehicle:setDisplayName("Patrol Car #1")
+end
+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.
+Always preserve the original function when overriding:
+-- 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
+onUpdate(dt)Called every frame while connected to multiplayer
+Parameters:
+- dt (number) - Delta time in seconds since last frame
Usage: +
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: +
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: +
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: +
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: +
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: +
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: +
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: +
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: +
local originalOnUIInitialised = MPVehicleGE.onUIInitialised
+MPVehicleGE.onUIInitialised = function()
+ originalOnUIInitialised()
+
+ print("BeamMP UI initialized")
+end
+onSettingsChanged()Called when BeamMP settings are changed
+Usage: +
local originalOnSettingsChanged = MPVehicleGE.onSettingsChanged
+MPVehicleGE.onSettingsChanged = function()
+ originalOnSettingsChanged()
+
+ print("BeamMP settings changed")
+end
+MPConfig.getPlayerServerID()Returns the local player's server-assigned ID
+Returns: +- (number) - The player's server ID (-1 if not set)
+Usage: +
+MPConfig.getNickname()Returns the local player's nickname
+Returns: +- (string) - The player's current nickname
+Usage: +
+MPConfig.getConfig()Returns the BeamMP configuration settings
+Returns: +- (table) - Configuration table with all BeamMP settings +- (nil) - If config file doesn't exist
+Usage: +
+MPConfig.setConfig(settingName, settingVal)Sets a specific configuration value
+Parameters:
+- settingName (string) - Name of the setting
+- settingVal (any) - Value to set
Usage: +
+MPCoreNetwork.getCurrentServer()Returns information about the current connected server
+Returns: +- (table) - Server data (ip, port, name, map) +- (nil) - If not connected
+Usage: +
local server = extensions.MPCoreNetwork.getCurrentServer()
+if server then
+ print("Server: " .. server.name)
+ print("IP: " .. server.ip .. ":" .. server.port)
+end
+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: +
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: +
+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: +
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: +
+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: +
+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: +
+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: +
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: +
+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: +
-- 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.onUpdate(dt)Called every frame while connected to multiplayer
+Parameters:
+- dt (number) - Delta time in seconds
Usage: +
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: +
local originalOnVehicleReady = MPGameNetwork.onVehicleReady
+MPGameNetwork.onVehicleReady = function(gameVehicleID)
+ originalOnVehicleReady(gameVehicleID)
+ -- Your code here
+end
+MPHelpers.b64encode(string)Encodes a string to Base64 (RFC 2045)
+Parameters:
+- string (string) - String to encode
Returns: +- (string) - Base64-encoded string
+Usage: +
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: +
local decoded = extensions.MPHelpers.b64decode("SGVsbG8gV29ybGQ=")
+
+-- Decoding JSON
+AddEventHandler("receiveData", function(data)
+ local decoded = extensions.MPHelpers.b64decode(data)
+ local jsonData = jsonDecode(decoded)
+end)
+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: +
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")
+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: +
-- 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]
+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: +
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
+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: +
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: +
local function myFunction()
+ extensions.MPHelpers.simpletrace()
+ -- Logs: "Code was called from: lua/ge/extensions/mymod.lua:42"
+end
+Last updated: 01.01.2026
+ + + + + + + + + + + + + + + + + + + + + + + + +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: +
+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.GetPlayerCount() -> numberReturns the number of currently connected players.
+Returns: +- (number) - Player count.
+MP.GetPlayers() -> tableReturns a table of all connected players.
+Returns:
+- (table) - Map of {[playerID] = playerName}.
MP.GetPlayerName(playerID) -> stringReturns 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: +
+MP.GetPlayerIDByName(name) -> numberReturns 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) -> tableReturns 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: +
local player_id = 5
+print(MP.GetPlayerIdentifiers(player_id))
+-- { ip: "127.0.0.1", discord: "12345678987654321", beammp: "1234567" }
+MP.GetPlayerRole(playerID) -> string|nilReturns 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) -> booleanReturns 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: +
+MP.IsPlayerGuest(playerID) -> booleanReturns 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: +
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.GetPlayerVehicles(playerID) -> tableReturns 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: +
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, stringReturns 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: +
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: +
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.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: +
-- 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, stringSends 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, stringSame 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.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: +
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, ...) -> tableTriggers 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: +
+MP.TriggerGlobalEvent(eventName, ...) -> tableTriggers 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: +
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: +
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.CreateTimer() -> tableCreates a timer object for measuring elapsed time.
+Returns:
+- (table) - Object with:
+ - :GetCurrent() -> float — Seconds elapsed since last Start.
+ - :Start() — Resets the timer.
Usage: +
local mytimer = MP.CreateTimer()
+-- do stuff here that needs to be timed
+print(mytimer:GetCurrent())
+MP.GetOSName() -> stringReturns the name of the server's operating system.
+Returns:
+- (string) - "Windows", "Linux", or "Other".
MP.GetServerVersion() -> number, number, numberReturns the server version.
+Returns: +- (number) - major +- (number) - minor +- (number) - patch
+Usage: +
+MP.Get(configID) -> valueReads 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: +
+MP.SettingsEnum of setting IDs for use with MP.Get and MP.Set.
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.CallStrategyEnum for use with MP.CreateEventTimer.
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: +
local Future = MP.TriggerGlobalEvent("MyEvent")
+while not Future:IsDone() do
+ MP.Sleep(100)
+end
+MP.GetStateMemoryUsage() -> numberReturns the memory usage of the current Lua state.
+Returns: +- (number) - Memory in bytes.
+MP.GetLuaMemoryUsage() -> numberReturns the total memory usage of all Lua states combined.
+Returns: +- (number) - Memory in bytes.
+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: +
Util.LogInfo("Hello, World!")
+Util.LogWarn("Cool warning")
+Util.LogError("Oh no!")
+Util.LogDebug("hi")
+Util.JsonEncode(table) -> stringEncodes 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: +
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) -> tableDecodes 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: +
local json = "{\"message\":\"OK\",\"code\":200}"
+local tbl = Util.JsonDecode(json)
+-- { message = "OK", code = 200 }
+Util.JsonPrettify(json) -> stringAdds 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: +
local myjson = Util.JsonEncode({ name="Lion", age = 69, skills = { "skill A", "skill B" } })
+print(Util.JsonPrettify(myjson))
+Util.JsonMinify(json) -> stringRemoves unnecessary whitespace and newlines from a JSON string.
+Parameters:
+- json (string) - A valid JSON string.
Returns: +- (string) - Minified JSON.
+Usage: +
local pretty = Util.JsonPrettify(Util.JsonEncode({ name="Lion", age = 69 }))
+print(Util.JsonMinify(pretty))
+Util.JsonFlatten(json) -> stringFlattens a nested JSON into /a/b/c-style keys per RFC 6901.
Parameters:
+- json (string) - A valid JSON string.
Returns: +- (string) - Flattened JSON.
+Usage: +
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) -> stringRestores a flattened JSON back to its nested structure.
+Parameters:
+- json (string) - A flattened JSON string.
Returns: +- (string) - Nested JSON.
+Util.JsonDiff(a, b) -> stringComputes 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() -> floatReturns a random float between 0 and 1.
+Returns: +- (float)
+Usage: +
+Util.RandomRange(min, max) -> floatReturns a random float within a given range.
+Parameters:
+- min (number) - Lower bound.
+- max (number) - Upper bound.
Returns: +- (float)
+Usage: +
local randFloat = Util.RandomRange(1, 1000)
+print("randFloat: " .. randFloat)
+-- randFloat: 420.6969
+Util.RandomIntRange(min, max) -> numberReturns a random integer within a given range.
+Parameters:
+- min (number) - Lower bound.
+- max (number) - Upper bound.
Returns: +- (number) - Integer.
+Usage: +
+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() -> tableReturns execution time statistics for every handler that has run.
+Returns:
+- (table) - Per handler: mean, stdev, min, max, n (all in ms).
Usage: +
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.CreateConnection(host, port) -> tableCreates 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.Exists(path) -> booleanReturns whether a path exists.
+Parameters:
+- path (string) - The path to check.
Returns:
+- (boolean) - true if exists.
FS.IsDirectory(path) -> booleanReturns 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) -> booleanReturns 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.CreateDirectory(path) -> boolean, stringCreates 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: +
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, stringRemoves 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, stringRenames 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, stringCopies 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) -> tableReturns 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: +
+FS.ListDirectories(path) -> tableReturns 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: +
+FS.GetFilename(path) -> stringReturns the filename with extension from a path.
+Parameters:
+- path (string) - A path string.
Returns: +- (string) - The filename.
+Usage: +
+FS.GetExtension(path) -> stringReturns the file extension including the dot.
+Parameters:
+- path (string) - A path string.
Returns:
+- (string) - The extension (e.g. ".json"), or "" if none.
Usage: +
"myfile.txt" -> ".txt"
+"somefile." -> "."
+"/awesome/path" -> ""
+"/awesome/path/file.zip.txt" -> ".txt"
+FS.GetParentFolder(path) -> stringReturns the path of the containing directory.
+Parameters:
+- path (string) - A path string.
Returns: +- (string) - Parent folder path.
+Usage: +
+FS.ConcatPaths(...) -> stringJoins path segments together using the system's preferred separator, resolving .. where present.
Parameters:
+- ... (string) - Path segments.
Returns: +- (string) - Joined path.
+Usage: +
+onInitTriggered right after all plugin files have been loaded.
+Arguments: none +Cancellable: no
+onConsoleInputTriggered when the server console receives input.
+Arguments:
+- input (string) - The text that was entered.
Cancellable: no
+Usage: +
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")
+onShutdownTriggered when the server shuts down, after all players have been kicked.
+Arguments: none +Cancellable: no
+onPlayerAuthTriggered 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: +
function myPlayerAuthorizer(name, role, is_guest, identifiers)
+ return "Sorry, you cannot join at this time."
+end
+
+MP.RegisterEvent("onPlayerAuth", "myPlayerAuthorizer")
+postPlayerAuthTriggered 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
+onPlayerConnectingTriggered when a player starts connecting, after onPlayerAuth.
Arguments:
+- playerID (number)
Cancellable: no
+onPlayerJoiningTriggered after the player has finished downloading all mods.
+Arguments:
+- playerID (number)
Cancellable: no
+onPlayerJoinTriggered after the player has finished syncing and entered the game.
+Arguments:
+- playerID (number)
Cancellable: no
+onPlayerDisconnectTriggered when a player disconnects.
+Arguments:
+- playerID (number)
Cancellable: no
+onChatMessageTriggered 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: +
function MyChatMessageHandler(sender_id, sender_name, message)
+ if message == "darn" then
+ return 1
+ else
+ return 0
+ end
+end
+
+MP.RegisterEvent("onChatMessage", "MyChatMessageHandler")
+postChatMessageTriggered after onChatMessage.
Arguments:
+- wasSent (boolean) - Whether the message was sent.
+- playerID (number)
+- playerName (string)
+- message (string)
Cancellable: no
+onVehicleSpawnTriggered 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.
postVehicleSpawnTriggered after onVehicleSpawn.
Arguments:
+- wasSpawned (boolean) - Whether the vehicle was actually spawned.
+- playerID (number)
+- vehicleID (number)
+- data (string)
Cancellable: no
+onVehicleEditedTriggered 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.
postVehicleEditedTriggered after onVehicleEdited.
Arguments:
+- wasAllowed (boolean) - Whether the edit was allowed.
+- playerID (number)
+- vehicleID (number)
+- data (string)
Cancellable: no
+onVehicleDeletedTriggered when a vehicle is deleted.
+Arguments:
+- playerID (number)
+- vehicleID (number)
Cancellable: no
+onVehicleResetTriggered 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
+onVehiclePaintChangedTriggered when a vehicle's paint is changed.
+Arguments:
+- playerID (number)
+- vehicleID (number)
+- data (string) - JSON string with the new paint data.
Cancellable: no
+onFileChangedTriggered 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.
+ + + + + + + + + + + + + + + + + + + + + + + + +The Launcher is not connecting to the game. +This quick guide explains how to manually change the launcher port.
+Show advanced optionsLauncher port change the port number to something else, for example 4567Open file location in the context menulauncher.cfg file in a text editor"Port": 4444, number to the same you used earlier in the ingame options, in this example 4567If theres still no connection, try again with another port. Any number between ~2000 and 65535 is a valid port
+Create a support ticket on our Discord Server.
+Tags: Launcher, Connection Failed, Port Number
+ + + + + + + + + + + + + + + + + + + + + + + + +In BeamMP, the Server you decide to connect to, provides the necessary mods. These get downloaded and activated automatically upon connecting. +Having local mods installed and active often leads to BeamMP not functioning properly, even if you have just one additional mod besides BeamMP.
+There are 3 options to resolve possible issues caused by mods with using BeamMP.
+Before joining any server, make sure you have no mods besides 'multiplayerbeammp' enabled. +If this method does not work, for example the game freezes / shows a blackscreen, or you still have issues, refer to the next option.
+Open the BeamNG.Drive userfolder and rename the current folder to for example current_old. Close BeamNG.drive before renaming the folder.
+The result should be a clean new userfolder.
+
If you have renamed the userfolder, you forced the game to create a new, clean userfolder. You may copy the 'settings' and 'vehicles' folder from the folder you renamed (e.g. current_old) to the new folder it created.
+Make sure BeamNG.Drive is closed and replace all elements in the location you want to copy the folders to. You should now have all configs and settings as they were before.
!!! warning "Be careful when moving back files/folders to the new userfolder.
+If you resolved any issues by renaming the userfolder, moving back the old files may cause any issues you had to possibly re-occur.
+After you are done, start BeamNG.Drive via the BeamMP-Launcher and you should have 'multiplayerbeammp' as your only enabled mod available in the repository as well as the button on the Main Menu to enter BeamMP. +If you still have issues joining modded server, they likely provide broken/outdated mods.
+To clean up cached mods from the BeamMP directories, go to the installation location of your BeamMP-Launcher. By default, the path would be 'C:\Users\AppData\BeamMP-Launcher\'. In there, you will find a 'Resources' folder. +Delete the folder to delete all cached mods. This can be helpful if you need more space on your disk or want to clean out oudated BeamNG mods.
+If you have placed mods in the content folder, you should remove them.
+To access the Beamng.drive\content\ folder and clean the folder of any mods, open the installation location of BeamNG.drive.
+Right click the content folder and delete it. Proceed to verify the game files via Steam or Epic Games. This is going to download the base files again.
??? quote "DO_NOT_INSTALL_MODS_HERE.txt"
+
+ Do NOT copy mods into this folder: it can lead to broken mods, slower installation of updates, a broken mod manager, broken Safe Mode and others.
+Info
+Before tampering with the firewall, make sure that your network within the windows networking settings is set to private (assuming you are in a private network).
+DISCLAIMER:
+Firewall / Defender exclsuions are a risk.
+By creating exclsuions, you understand the risks of allowing programs on your PC and opening up ports on your home network to the public and therefore void the right to hold BeamMP accountable for any and all damages that may happen to you or your household.
+We take no responsibility for any content on any externally linked services or websites.
+Windows Defender Firewall with advanced setting.Inbound to open the inbound exclusions tab.Create new rule in the top right to create a new exclusion.Program to create a program specific exclusion.BeamMP-Launcher.exe. The default would be %appdata%\BeamMP-Launcher\BeamMP-Launcher.exe (without quotes).Windows Defender Firewall with advanced setting.Inbound to open the inbound exclusions tab.Create new rule in the top right to create a new exclusion.Port to create a program specific exclusion.BeamMP-Server.exe. The file is located whereever you placed it after downloading it.Windows Security app.virus and threat protection.Manage settings beneath "Virus & threat protection settings".Exclusions tab.process.BeamMP-Launcher.exe or BeamMP-Server.exeinto the field and save it.Open a Thread on the Forum or on our Discord server in the #support channel.
How to check for CGNAT?
+All Firewall exclusions and Port forwarding rules are set up correctly, yet nobody can join your home-hosted Server?
+If you have connection problems and you are using a Hosting-Service, contact them for assistance. If you want to use a VPS or cannot host a server at home, take a look at our +list of Partnered hosting services (Server setup documentation).
+For a detailed explanation, on what CGNAT is and why it's an issue when trying to host a server at home, take a look at this page.
+Open a command prompt, run tracert -4 beammp.com. This will output a series of network hops. Wait for the operation to finish (may take up to 30 hops). Check the first few IP addresses after the IP of your Router/Modem/Gateway.
+If multiple IP addresses within the range of 100.64.x.x-100.127.x.x or 10.xx.xx.xx appear after the first hop, you are most likely behind a CGNAT.
Note
+The first hop will be your Router/Modem/Gateway and differs between Devices.
+The official ranges for local networks are as follows: 10.0.0.xxx - 192.168.xxx.xxx - `172.16.xxx.xxx
Find out the WAN IP on your router by looking it up on its interface. Compare it to the IP posted on e.g. https://whatsmyip.org . If they are NOT the same, you are behind a CGNAT.
+Call your Internet Service Provider for assistance. +Depending on your ISP, they might not offer dedicated dynamic IP adresses. Keep in mind, that a static IP is not necessary.
+Warning
+Internet Service Providers may only offer dedicated IP addresses as a paid option. +Please check the prices of our partnered hosting services as they could be cheaper than this fee!
+Example of a non-CGNAT Network:
+Tags: Server, 10060 10061, CGNAT, Connection Failed, Port Forward, Firewall
+ + + + + + + + + + + + + + + + + + + + + + + + +The Launcher can't update or shows a blank screen? +This quick guide explains how to manually update the Launcher.
+Note
+You should have already used or installed BeamMP using the installer provided by our website before continuing.
+C:\Users\<username>\AppData\Roaming\ . Replace D:\BeamMP-Launcher, then place the Launcher in the respective BeamMP-Launcher folder.Create a support ticket on our Discord Server. +Tags: Launcher, download,
+ + + + + + + + + + + + + + + + + + + + + + + + +List of commonly asked questions.
+There is a full guide on how to install BeamMP on Windows, you can find it here.
+BeamMP will not work with pirated or outdated versions of BeamNG.drive. +Modifications such as, but not limited to, 3rd party mods, may interfere with BeamMP. (See How to clear mods) +The BeamMP support team is unable to provide support for issues related to: pirated, outdated or otherwise modified versions of BeamNG.drive.
+The Client is not officially supported on Linux. However, you can follow our guide on how to use BeamMP on Linux
+Some antivirus programs may flag BeamMP as a threat, due to it interacting with the network and other factors. There are no viruses in any of the code. The code for the launcher, server, and lua client can be found on our GitHub.
+We are working hard to make the Multiplayer experience as stable as possible. If you have already lowered your graphic settings and your performance is still poor, consider playing on a server with less players. The game is mainly CPU bound when you play with lots of people, so older CPUs (even quadcores) will suffer with more than a handful of people. (General Rule of Thumb: 1 car per CPU Thread)
+All the source code can be found on our GitHub. +Before making any changes, keep in mind that the code is subject to our Terms of Use and licenses:
+| Code | +License | +
|---|---|
| Server | +LICENSE | +
| Launcher | +LICENSE | +
| Client Lua | +LICENSE | +
If the issue is code related and you know how to use Github, open a new "Issue" in the appropriate repository on our GitHub. We use an issue-based workflow so even if you already have a fix for the bug, consider opening a new "Issue", then open a "Pull Request" with the solutions for the issue. More info on contributing can be found here.
+If you don't have a GitHub account or you don't know how to use GitHub or have any other questions, you can get in touch with us in the following ways:
+Linking your Discord and BeamMP account is a new feature to BeamMP. To do this go to your Forum Account Preferences and connect your Discord account under "Associated Accounts" (this is only visible when 2FA for the forum is disabled).
+Early access (including the purple nametag and other benefits) can be obtained by supporting us financially on Patreon by buying a tier, donating, or by boosting the Discord Server. +Donating x amount US$ = x additional server key(s) including EA benefits. +Boosting gives you +4 Server keys in addition to EA benefits.
+Please ensure you do the following to automatically receive your perks:
+Please be patient, it can take a few hours, sometimes up to 12, for the system to sync. If you have not received your perks after 12 hours and have completed the above steps please contact BeamMP support.
+If your question or issue relates to the Game or playing please refer to the Game FAQs. +If your question or issue relates to running a Server please refer to the Server FAQs. +Otherwise please check out the forums where the community can ask questions and get answers.
+ + + + + + + + + + + + + + + + + + + + + + + + +List of commonly asked questions and known bugs.
+All the information to set up your own server can be found here.
+We provide binaries for many Linux distributions here. +If there are no binaries for your Operating System/Distribution, you can build it yourself by downloading the source on our GitHub, a tutorial can be found here.
+Read the port forwarding guide that's available here. Below there's a brief summary of the most noteworthy steps. +If other players, trying to connect to your server, receive an error code 10060, 10061 or 10038 in their BeamMP launcher, then you should check the following steps:
+You can check if you have successfully portforwarded using CheckBeamMP whilst the server is running.
+ + +Notes:
+If the server is running on the same machine as the game, you yourself have to use Direct Connect to join, with the IP 127.0.0.1 and your server's port. +For you to be able to join your own, self-hosted server trough the server-list, your router needs to support NAT-loopback, but this is a function not many home routers support.
+All the source code can be found on our GitHub. +Before doing anything keep in mind that the code is subject to our Terms of Use and licenses:
+| Code | +License | +
|---|---|
| Server | +LICENSE | +
| Launcher | +LICENSE | +
| Client Lua | +LICENSE | +
If the issue is code related and you know how to use Github, create a new "Issue" in the appropriate repository on our GitHub. We use an issue-based workflow so even if you already have a fix for the bug, consider opening a new "Issue", then asking a "Pull Request" that solves your "Issue". More info on contributing can be found here.
+If you don't have a GitHub account or you don't know how to use GitHub you can get in touch with us in the following ways:
+If you are hosting a server with one of our partnered hosting services, the IP will be posted on the respective Server Management Interface. +You can also find the IP for your Server(s) on the Keymaster Website.
+For Servers hosted at home, open whatsmyip.org in a Browser. +This will output the public IPv4 address you are being contacted with from the Internet.
+Note, that 127.0.0.1 is the localhost address and can only be used by yourself, if the Server is hosted on the same Computer. +If you are still having connection troubles with your home hosted server, check the port forwardings as well as CheckBeamMP
+ + +Have a look at this page to determine wether you can host a server at home or not.
+Tags: IP, Server, Connection Failed, 10060/10061
+ + + + + + + + + + + + + + + + + + + + + + + + +