BeamMP Lua Scripting

BeamMP has a built-in server-side Lua environment. Scripts in Resources/Server/ are loaded at startup and can react to player events, send messages, and control the server programmatically.

New to Vyper Hosting?

The Vyper Hosting file manager and SFTP access let you upload, edit, and iterate on Lua scripts without leaving your browser. Console output is live in the panel so you can debug instantly. Get a BeamMP server on our website.

Note

This guide assumes basic programming familiarity. New to Lua? The Lua 5.4 reference manual is the definitive resource.

Core API Functions

Players

MP.GetPlayers()                    -- table of {id = name}
MP.GetPlayerName(playerID)         -- player's username string
MP.SendChatMessage(playerID, msg)  -- send message; -1 = broadcast to all

Events

Register a Lua function to run when something happens:

MP.RegisterEvent("onPlayerConnecting", "myFunction")
function myFunction(playerID)
    -- runs when a player connects
end

Event Reference

Event	Arguments	Description
onPlayerConnecting	playerID	Player is connecting
onPlayerConnected	playerID	Player fully joined
onPlayerDisconnecting	playerID	Player is leaving
onChatMessage	playerID, name, message	Player sent a chat message
onVehicleSpawned	playerID, vehicleID, data	Vehicle spawned
onVehicleEdited	playerID, vehicleID, data	Vehicle modified
onVehicleDeleted	playerID, vehicleID	Vehicle deleted
onVehicleReset	playerID, vehicleID	Vehicle reset

Timers

-- Run a function every 300 seconds
MP.CreateTimer(300, function()
    MP.SendChatMessage(-1, "Remember to follow the server rules!")
end)

Example: /rules Command

local rules = {
    "1. No intentional ramming.",
    "2. Keep chat respectful.",
    "3. Listen to admins.",
}

MP.RegisterEvent("onChatMessage", "handleChat")

function handleChat(playerID, playerName, message)
    if message == "/rules" then
        for _, rule in ipairs(rules) do
            MP.SendChatMessage(playerID, rule)
        end
        return 1 -- prevent "/rules" from appearing in chat
    end
end

Example: Join & Leave Messages

MP.RegisterEvent("onPlayerConnected", "onJoin")
function onJoin(playerID)
    local name = MP.GetPlayerName(playerID)
    MP.SendChatMessage(-1, name .. " has joined the server!")
end

MP.RegisterEvent("onPlayerDisconnecting", "onLeave")
function onLeave(playerID)
    local name = MP.GetPlayerName(playerID)
    MP.SendChatMessage(-1, name .. " has left the server.")
end

Debugging

• Use print("message") - output appears in the Console tab of your Vyper Hosting panel.
• Syntax errors appear in the console on startup with the line number.

Deploying Your Script

1. Write your script and save it as a .lua file.
2. In your panel, go to Files → Resources → Server and upload the file. Or use SFTP - see SFTP guides.
3. Restart the server - your script is active immediately.

Further Reading

BeamMP Server API Docs Official API reference for all server-side Lua functions and events.

BeamMP Forums Community scripts, examples, and plugin discussions.