BeamMP allows server-owners to extend the functionality of their server via custom lua scripts/plugins.
all lua files live inside of their respective plugin folder, the plugin folder should look like this: Resources\Server\<pluginName> every lua file within a plugin folder has its own dedicated lua environment; under normal circumstances, separate lua files cannot interact with each-other beyond triggering events.
in BeamMP, events must be registered using RegisterEvent(<EventName>,<functionName>) otherwise they will not be triggered, the 'EventName' parameter is the title of the desired event to be registered as a string, 'FunctionName' is the name of the global function as a string that you want to be called when the event is triggered.
Vanilla BeamMP servers ship with various pre-existing events which correspond to various in-game actions. can be cancelled by returning 1 in the function.
| Event Name | Parameters | When is it triggered? | When cancelled | Notes |
|---|---|---|---|---|
| onInit | nothing | When the lua file is loaded | Does nothing | |
| onPlayerConnecting | PlayerID | When the player presses 'Connect' | Not recomended, use DropPlayer(PlayerID, reason) | |
| onPlayerJoining | PlayerID | When the player begins loading | Not recomended, use DropPlayer(PlayerID, reason) | |
| onPlayerJoin | PlayerID | When the player is done loading | Not recomended, use DropPlayer(PlayerID, reason) | |
| onPlayerDisconnect | PlayerID | When the player leaves the server | Does Nothing | |
| onChatMessage | PlayerID, name, message | When a player sends a chat message | Message does not display in chatbox | |
| onVehicleSpawn | PlayerID, vehicleID, data | When a player spawns a vehicle | Deletes vehicle, does not trigger onVehicleDeleted | data is raw JSON |
| onVehicleEdited | PlayerID, vehicleID, data | When a player applies their edits to the server | Deletes vehicle, does not trigger onVehicleDeleted | data is raw JSON |
| onVehicleDeleted | PlayerID, vehicleID | When a player deletes their vehicle | Does Nothing |
Users may also define their own Events beyond the pre-existing BeamMP events, they are registered the same way as normal events, the difference being that user-defined events are not tied to a specific event on the server and instead have to be triggered manually.
User-defined events can be triggered using two functions, TriggerLocalEvent(<EventName>, ...) or TriggerGlobalEvent(<EventName>, ...) String, EventName is the name that users will register their events under, any parameters after EventName, will be passed to the function the event points to. TriggerLocalEvent(<EventName>, ...) will execute any registered instances of EventName within the plugin folder, whereas TriggerGlobalEvent(<EventName>, ...) will execute any registered instance of EventName regardless of plugin folder.
Under normal circumstances, user-defined events are the only way that separate lua files will be able to communicate with each other.
BeamMP also has a set of predefined global functions you may use.
| Function | Description | Notes |
|---|---|---|
| GetPlayerName(<serverID>) | Returns the players discord name as a string | |
| GetPlayerDiscordID(<serverID>) | Deprecated, for compatibility, currently returns the player's name as a string. | Deprecated, do not use this. |
| GetPlayerHWID(<serverID>) | Returns the players hardware id as a string. | hardware ID is not implemented yet. |
| GetPlayerVehicles(<serverID>) | Returns the players vehicles as a table of IDs and Data (nil if no cars were found) | Doesn't work/inconsistent. |
| DropPlayer(<serverID>, <Reason>) | Drops the connection for a specific player. Essentially Kicking them | |
| SendChatMessage(<serverID>,<Message>) | Sends a message over the network as the server to a player use -1 to broadcast | use -1 to broadcast |
| RegisterEvent(<EventName>,<functionName>) | Register a function to be triggered by EventName. functionName is a string representing a global function. |
|
| TriggerLocalEvent(<EventName>, ...) | Trigger any Event registered under <EventName> within the plugin folder. Any further args after <EventName> will be passed through as args. |
|
| TriggerGlobalEvent(<EventName>, ...) | Trigger any Event registered under <EventName> regardless of the plugin folder. Any further args after <EventName> will be passed through as args. |
|
| CreateThread(<funcName>, <times per sec>) | funcName is a string representing the global name of a function. A new thread will be created, on which, function is called x times per sec |
cannot pass args use this instead of infinite loops times/sec is between 1 and 500 |
| StopThread() | Will stop trying to call the thread function of the current script | if there is no thread, nothing happens |
| GetPlayerCount() | Returns the number of players on the server. | |
| Sleep(<millisecs>) | pauses ALL operations for milliseconds. It is recommended that you only use Sleep inside of a thread. | |
| RemoveVehicle(<serverID>,<VehicleID>) | Deletes a player's vehicle. | |
| GetPlayers() | Returns a table of serverID's and their names. | nil if there is no players connected |
| TriggerClientEvent(<serverID>,<function name>,<Data>) | Will send a trigger request to the client lua. | |
| Set(<configID>, <new value>) | Will change the running-config of the server depending on the ID. |
0 for the debug config, 1 for the private config, 2 for the CarCount Config, 3 for the MaxPlayers config, 4 for the Map, 5 for the Name, 6 for the Description, any other ID will result in a console warning. |
| exit | will close the server. |
When a player connects to your server, they are assigned a serverID starting from 0 and counting upwards. serverIDs are reused; if a player leaves and re-joins they will not be assigned a new serverID, they will simply get another available one. When the server restarts, serverIDs will be reset.
Players in BeamMP have 3 static identifiers which can be obtained from their serverID being their name, discordID, and their hardwareID or HWID. (though the latter of the aforementioned isn't implemented, we will act as if it is) Each of the three ID types has their own origins and strength's/weaknesses to using them for player identification.
| ID TYPE | PROS | CONS | FUNCTION TO OBTAIN |
|---|---|---|---|
| name | easy to obtain, straightforward | not secure | GetPlayerName(<serverID>) |
| discordID | fairly secure | inconvenient | GetPlayerDiscordID(<serverID>) |
| HWID | extremely secure | hard to obtain | GetPlayerHWID(<serverID>) |
Vehicles in beamMP have 3 attributes that the server pays attention to, the owner's serverID, the vehicles vehicleID and it's data. The the Owner's serverID is straight forward, it is the serverID, every vehicle also has an ID, vehicle IDs are not unique to the vehicle; two vehicles may have the same ID, assuming they're from different owners. Unlike serverIDs, vehicleIDs are reused, for example, if I have 4 vehicles, their IDs are 0, 1, 2 and, 3 if I delete the vehicle in vehicleID 2, I will have 0, 1 and, 3, when I spawn a new vehicle, the new vehicle will slot into ID 2. Lastly, the last attribute vehicles have is data, data contains a vehicle, name, parts, and other data; as the name implies. data is stored as a raw JSON string, so you will need a JSON library alternatively, you can manually step through the string and dig out the information you need.