BeamMP Lua Plugins: How to Use Server Events

A BeamMP server plugin is a Lua script in its own folder under Resources/Server, for example Resources/Server/MyPlugin/main.lua. It reacts to server events: you write a function and connect it with MP.RegisterEvent("onPlayerJoining", "myFunction"). Some events, such as onChatMessage and onVehicleSpawn, can be cancelled by returning 1. Your FREAKHOSTING server runs Lua 5.3.5.

Plugin folder	Main file	Load order	Lua version on our servers
`Resources/Server/<PluginName>/`	`main.lua` (any `.lua` name works)	All `.lua` files in the folder, alphabetically	5.3.5

How to create a BeamMP Lua plugin

Create the folder

In the Game Panel, open Files, go to Resources/Server and create a folder, for example Welcome.

Create the script

Create main.lua in that folder and paste the example below.

Restart

Restart the server. print() output and Lua errors appear in the console with a [LUA] prefix.

Example: welcome message and timed announcement

function onJoining(player_id)
  MP.SendChatMessage(player_id, "Welcome to the server, " .. MP.GetPlayerName(player_id) .. "!")
end

function announce()
  MP.SendChatMessage(-1, "Type /help for commands. Be fair, no ramming.")
end

MP.RegisterEvent("onPlayerJoining", "onJoining")

-- Run "announceEvent" every 10 minutes (600000 ms)
MP.RegisterEvent("announceEvent", "announce")
MP.CreateEventTimer("announceEvent", 600000)

Which events can a BeamMP plugin use?

Event	Arguments	Cancel with `return 1`?
`onInit`	–	No
`onPlayerAuth`	`player_name, player_role, is_guest, identifiers`	Yes (return `1` or a reason text)
`onPlayerConnecting`	`player_id`	No
`onPlayerJoining`	`player_id` (player has loaded the mods)	No
`onPlayerDisconnect`	`player_id`	No
`onChatMessage`	`player_id, player_name, message`	Yes
`onVehicleSpawn`	`player_id, vehicle_id, data`	Yes
`onVehicleEdited`	`player_id, vehicle_id, data`	Yes
`onVehicleDeleted`	`player_id, vehicle_id`	No
`onVehicleReset`	`player_id, vehicle_id, data`	No
`onConsoleInput`	`input`	No
`onFileChanged`	`path`	No
`onShutdown`	–	No

Which MP functions are most useful?

Function	What it does
`MP.RegisterEvent(event, "functionName")`	Connects a function to an event (the name is a text string)
`MP.SendChatMessage(player_id, text)`	Sends chat to one player, or everyone with `-1`
`MP.GetPlayers()`	Table of player IDs and names
`MP.GetPlayerName(player_id)`	A player’s name
`MP.GetPlayerIdentifiers(player_id)`	Table with `ip`, `beammp` and, if linked, `discord`
`MP.DropPlayer(player_id, reason)`	Kicks a player, reason optional
`MP.RemoveVehicle(player_id, vehicle_id)`	Deletes a player’s vehicle
`MP.GetPlayerVehicles(player_id)`	A player’s vehicles
`MP.CreateEventTimer(event, interval_ms)`	Fires an event on a timer
`Util.JsonDecode(text)`	Turns JSON text into a Lua table

The full list is in the official BeamMP server scripting reference.

Do I need to restart after editing a plugin?

Saving a file directly in a plugin’s folder reloads that plugin. Files in subfolders don’t trigger a reload, and files or folders added while the server runs aren’t watched, so restart after adding a new plugin.

Frequently asked questions

Can I use several Lua files in one plugin?

Yes. Every .lua file in the plugin folder loads in alphabetical order. Files in subfolders only load when you require() them.

Where do I see my plugin’s errors?

In the panel console and in Server.log.

Can a plugin change server settings?

MP.Set changes some settings for the running server only. The panel writes the Startup values back at the next start. For more player slots, open a ticket.

BeamMP server guide

Every BeamMP page in one place.

Add chat commands

/help and /players example.

Restrict vehicles

Vehicle allowlist plugin.

Anti-grief protection

Ban list plugin.

Console commands

The Lua console and more.

Checked against the official BeamMP server scripting reference on 3 November 2026, with file paths from our Game Panel (BeamMP Server v3.9.3, Lua 5.3.5).

Need Extra Help?

If you encounter any issues, our support team is ready to assist:

Live Chat: Quick assistance via our website.
Support Ticket: Open a Ticket
Discord: Join our Community
Email: support@freakhosting.com

Save on Your Hosting

Ready to upgrade your hosting? Use code KB20 at checkout for 20% off your first order!

Last Updated: November 2026

Getting Started

Popular Games

Survival Games

GTA & RDR Multiplayer

Racing & Simulation

Shooters

Sandbox & Building

Other Games

BeamMP Lua Plugins: How to Use Server Events

How to create a BeamMP Lua plugin

Example: welcome message and timed announcement

Which events can a BeamMP plugin use?

Which MP functions are most useful?

Do I need to restart after editing a plugin?

Frequently asked questions

Can I use several Lua files in one plugin?

Where do I see my plugin’s errors?

Can a plugin change server settings?

BeamMP server guide

Add chat commands

Restrict vehicles

Anti-grief protection

Console commands

Need Extra Help?

Save on Your Hosting

​How to create a BeamMP Lua plugin

​Example: welcome message and timed announcement

​Which events can a BeamMP plugin use?

​Which MP functions are most useful?

​Do I need to restart after editing a plugin?

​Frequently asked questions

​Can I use several Lua files in one plugin?

​Where do I see my plugin’s errors?

​Can a plugin change server settings?

​Related guides

BeamMP server guide

Add chat commands

Restrict vehicles

Anti-grief protection

Console commands

​Need Extra Help?

​Save on Your Hosting

How to create a BeamMP Lua plugin

Example: welcome message and timed announcement

Which events can a BeamMP plugin use?

Which MP functions are most useful?

Do I need to restart after editing a plugin?

Frequently asked questions

Can I use several Lua files in one plugin?

Where do I see my plugin’s errors?

Can a plugin change server settings?

Related guides

Need Extra Help?

Save on Your Hosting