mirror of
https://github.com/BeamMP/Docs.git
synced 2026-07-25 08:10:32 +00:00
More work!!!
This commit is contained in:
Starystars67
@@ -0,0 +1,46 @@
|
||||
# Contributing to the BeamMP Docs
|
||||
|
||||
BeamMP is using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material) as its theme. This is a theme for [MkDocs](https://www.mkdocs.org).
|
||||
Full documentation can be found at their respective sites.
|
||||
|
||||
## Getting Started
|
||||
|
||||
To help contribute to these docs you can take one of two approaches as set out below:
|
||||
|
||||
### 1. Edit the raw markdown files
|
||||
|
||||
Editing the raw markdown files is the fastest approach and best for quick edits such as spelling, grammar or new snippets of content.
|
||||
This approach does require a prior knowledge of markdown however as you will need to understand what your contribution will produce.
|
||||
|
||||
If this is the approach you wish to take then please follow these steps:
|
||||
|
||||
1. Click edit on the page you wish to edit.
|
||||
2. Fork the project into your own GitHub account.
|
||||
3. Make the changes you see fit.
|
||||
4. Commit your changes to your fork.
|
||||
5. Raise a pull request against our repository [here](https://github.com/BeamMP/Docs).
|
||||
|
||||
Once you have created your pull request one of the BeamMP Mod Team will review your Pull Request and either approve it or request some changes.
|
||||
If changes were requested and you have completed them we will re-review your Pull Request.
|
||||
Then your changes will be merged into the repository and automatically deployed as part of our continuous integration.
|
||||
|
||||
### 2. Make edits with live preview
|
||||
|
||||
Editing our docs this way will still take a similar approach as in option 1 however you will be able to preview your changes this way.
|
||||
|
||||
1. Click edit on the page you wish to edit.
|
||||
2. Fork the project into your own GitHub account.
|
||||
3. Clone the project locally.
|
||||
4. Setup Material for MkDocs according to their guide [here](https://squidfunk.github.io/mkdocs-material/getting-started/)
|
||||
5. Run `mkdocs serve` to start the live-reloading docs server from where you cloned the fork to.
|
||||
6. Make the changes that you see fit.
|
||||
7. Commit your changes to your fork.
|
||||
8. Raise a pull request against our repository [here](https://github.com/BeamMP/Docs).
|
||||
|
||||
|
||||
## Project layout
|
||||
|
||||
mkdocs.yml # The configuration file.
|
||||
docs/
|
||||
index.md # The documentation homepage.
|
||||
... # Other markdown pages, images and other files.
|
||||
@@ -0,0 +1,11 @@
|
||||
---
|
||||
title: BeamMP Scripting
|
||||
description: BeamMP scripting references for client and server
|
||||
---
|
||||
|
||||
# BeamMP Scripting
|
||||
|
||||
## References
|
||||
- [Mod (In-Game)](./mod-in-game.md)
|
||||
- [Server v3 (Latest)](./server/latest.md)
|
||||
- [Server v2 (Legacy)](./server/legacy-v2.md)
|
||||
@@ -0,0 +1,43 @@
|
||||
::: warning "This site is under construction!"
|
||||
|
||||
This site is being actively worked on.
|
||||
|
||||
Feel you could help? Please do by clicking on the page with a pencil on the right!
|
||||
|
||||
This can be done any page too.
|
||||
|
||||
# Mod/In-Game Scripting Reference
|
||||
|
||||
BeamMP allows you to create your own client side plugins as well. We have provided a few functions that you can use to communicate with other multiplayer mods, and other players through the server.
|
||||
|
||||
# Functions
|
||||
|
||||
List of available functions for scripting:
|
||||
|
||||
| Function | Notes |
|
||||
|-------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `TriggerServerEvent("eventName", "data")` | Triggers an event in the server lua environment, both parameters are strings. |
|
||||
| `TriggerClientEvent("eventName", "data")` | Triggers an event in the local lua environment, both parameters are strings. Good for communication between plugins. |
|
||||
| `AddEventHandler("eventName", Function)` | Adds the 2nd parameter to the table to be called when `eventName` is received (either locally or from the server), `Function` will get 1 parameter, a string containing the event data. |
|
||||
|
||||
# Code snippets
|
||||
|
||||
For example to parse the chat use the included `ChatMessageIncluded` event as such:
|
||||
|
||||
```lua
|
||||
local function chatReceived(msg) -- Receive event with parameters
|
||||
print("chat received: "..msg)
|
||||
local i = string.find(s, ":") -- Find where our first ':' is, used to separate the sender and message
|
||||
if i == nil then
|
||||
print("error parsing message: separator could not be found!")
|
||||
return -- Could not find separator, cancel function
|
||||
end
|
||||
print("index of separator: "..tostring(i))
|
||||
local sender = string.sub(msg, 1, i-1) -- Substring our input to separate its 2 parts
|
||||
local message = string.sub(msg, i+1, -1) -- Do whatever you want to with the message
|
||||
print("sender: " .. sender)
|
||||
print("message: ".. message)
|
||||
end
|
||||
|
||||
AddEventHandler("ChatMessageReceived", chatReceived) -- Add our event handler to the list managed by BeamMP
|
||||
```
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,335 @@
|
||||
::: warning "This site is under construction!"
|
||||
|
||||
This site is being actively worked on.
|
||||
|
||||
Feel you could help? Please do by clicking on the page with a pencil on the right!
|
||||
|
||||
This can be done any page too.
|
||||
|
||||
# Server Scripting Reference
|
||||
## Server Version 2.X
|
||||
::: warning
|
||||
|
||||
BeamMP server version 2.X is now unsupported. This documentation is provided as a reference only.
|
||||
Please update to the latest version for maintenance and support.
|
||||
---
|
||||
|
||||
> This is 2.x scripting. Only refer to this if your server is old/outdated (version 2.x.x). For the latest documentation see [here](https://docs.beammp.com/scripting/server/latest-server-reference).
|
||||
{.is-warning}
|
||||
|
||||
### Notes
|
||||
|
||||
To get the output of a function in the server console you have to wrap it in a `print()` statement.
|
||||
For example:
|
||||
`print(GetPlayerName(0))` will return the name of your server's first player.
|
||||
|
||||
`<PlayersServerID>` starts at 0.
|
||||
|
||||
### List of available functions for scripting
|
||||
|
||||
#### GetPlayerName(playersServerID)
|
||||
Returns the player's discord name as a string
|
||||
```lua
|
||||
function onPlayerJoin(playerID)
|
||||
local name = GetPlayerName(playerID)
|
||||
-- Do something
|
||||
end
|
||||
```
|
||||
|
||||
#### GetPlayerDiscordID(playersServerID)
|
||||
Returns the player's discord name as a string
|
||||
```lua
|
||||
function onPlayerJoin(playerID)
|
||||
local name = GetPlayerDiscordID(playerID)
|
||||
-- Do something
|
||||
end
|
||||
```
|
||||
|
||||
#### GetPlayerHWID(playersServerID)
|
||||
Returns the player's discord ID as a string
|
||||
```lua
|
||||
function onPlayerJoin(playerID)
|
||||
local name = GetPlayerHWID(playerID)
|
||||
-- Do something
|
||||
end
|
||||
```
|
||||
|
||||
#### GetPlayerVehicles(playersServerID)
|
||||
Returns the player's vehicles as an object/array
|
||||
```lua
|
||||
function onChatMessage(playerID, senderName, message)
|
||||
local vehicleList = GetPlayerVehicles(playerID)
|
||||
for vehicleID, vehicleData in pairs(vehicleList) do
|
||||
-- Do something
|
||||
-- Could also be used to check how many vehicles a player have
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
#### DropPlayer(playersServerID)
|
||||
Drops the connection for a specific player. Essentially Kicking them
|
||||
```lua
|
||||
function onVehicleSpawn(playerID, vehicleID, vehicleData)
|
||||
-- Do something
|
||||
DropPlayer(playerID)
|
||||
end
|
||||
```
|
||||
|
||||
#### SendChatMessage(playersServerID, message)
|
||||
Sends a message over the network to the specified user. Use -1 for everyone
|
||||
```lua
|
||||
function onPlayerJoin(playerID)
|
||||
SendChatMessage(-1, "Someone just joined!")
|
||||
end
|
||||
```
|
||||
|
||||
#### CancelEvent() -- DEPRECIATED
|
||||
Cancels the event from happening. This might be going soon. Use `return 1` to cancel the event.
|
||||
|
||||
#### onInit()
|
||||
If declared in a lua file, it will be called once C++ successfully finished loading the current lua file
|
||||
```lua
|
||||
function onInit()
|
||||
print("Server ready")
|
||||
end
|
||||
```
|
||||
|
||||
#### exit()
|
||||
Will close the server
|
||||
```lua
|
||||
function onInit()
|
||||
print("Server Ready. But who needs a server which is running")
|
||||
exit() -- Stops the server
|
||||
end
|
||||
```
|
||||
|
||||
#### CreateThread(functionName, callInterval)
|
||||
Will execute the function on a dedicated thread and it will run callInterval times a second.
|
||||
1 = It will run every second.
|
||||
|
||||
```lua
|
||||
function yourFunction()
|
||||
for i = 1,10 do
|
||||
SendChatMessage(-1, "Countdown: "..i)
|
||||
Sleep(1000)
|
||||
end
|
||||
end
|
||||
CreateThread("yourFunction", 30)
|
||||
```
|
||||
|
||||
DEPRECIATED EXAMPLE
|
||||
Will execute the function on a dedicated thread
|
||||
```lua
|
||||
function yourFunction()
|
||||
for i = 1,10 do
|
||||
SendChatMessage(-1, "Countdown: "..i)
|
||||
Sleep(1000)
|
||||
end
|
||||
end
|
||||
CreateThread("yourFunction", 30)
|
||||
```
|
||||
|
||||
#### StopThread(functionName)
|
||||
Will stop trying to call the thread function of the current script
|
||||
```lua
|
||||
function yourFunction()
|
||||
delayExpired = false
|
||||
Sleep(10000)
|
||||
delayExpired = true
|
||||
end
|
||||
CreateThread("yourFunction", 30)
|
||||
-- Do something
|
||||
if not delayExpired then
|
||||
StopThread("yourFunction")
|
||||
else
|
||||
-- Do something
|
||||
end
|
||||
|
||||
```
|
||||
|
||||
#### Sleep(millisecs) - DEPRECIATED
|
||||
Will pause execution for the amount of time specified (warning doing so will pause the entire server if you didn't create a thread)
|
||||
```lua
|
||||
function countdown()
|
||||
for i = 1,10 do
|
||||
SendChatMessage(-1, "Countdown: "..i)
|
||||
Sleep(1000)
|
||||
end
|
||||
end
|
||||
CreateThread("countdown", 10)
|
||||
```
|
||||
|
||||
#### GetPlayerCount()
|
||||
Will return how many players are connected
|
||||
```lua
|
||||
function onPlayerJoin(playerID)
|
||||
SendChatMessage(playerID, "You are the "..GetPlayerCount().."th player!"
|
||||
end
|
||||
```
|
||||
|
||||
#### RemoveVehicle(playerServerID, VehicleID)
|
||||
Will despawn a vehicle
|
||||
```lua
|
||||
function onVehicleSpawn(playerID, vehicleID, vehicleData)
|
||||
if --[[ Vehicle data equal something it shouldn't be ]] then
|
||||
RemoveVehicle(playerID, vehicleIID)
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
#### GetPlayers()
|
||||
Will return a table of IDs with Names
|
||||
```lua
|
||||
local function onPlayerJoin(joinedPlayerID)
|
||||
local players = GetPlayers()
|
||||
for playerID, playerName in pairs(players) do
|
||||
if playerID == joinedPlayerID then
|
||||
-- Do something
|
||||
end
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
#### RegisterEvent(eventName, functionName)
|
||||
Will register that function to the event specified. Both must be strings
|
||||
```lua
|
||||
function anyEvent()
|
||||
-- Do something
|
||||
end
|
||||
RegisterEvent("onAnyEventHappen", "anyEvent")
|
||||
-- Do something
|
||||
TriggerLocalEvent("onAnyEventHappen")
|
||||
```
|
||||
|
||||
#### TriggerLocalEvent(eventName)
|
||||
Will call every registered function in the same plugin folder.
|
||||
```lua
|
||||
function anyEvent()
|
||||
-- Do something
|
||||
end
|
||||
RegisterEvent("onAnyEventHappen", "anyEvent")
|
||||
-- Do something
|
||||
TriggerLocalEvent("onAnyEventHappen")
|
||||
```
|
||||
|
||||
#### TriggerGlobalEvent(eventName)
|
||||
Will call every registered function with this event name.
|
||||
```lua
|
||||
-- File A
|
||||
function anyEvent()
|
||||
-- Do something
|
||||
end
|
||||
RegisterEvent("onAnyEventHappen", "anyEvent")
|
||||
```
|
||||
```lua
|
||||
-- File B
|
||||
TriggerGlobalEvent("onAnyEventHappen")
|
||||
```
|
||||
|
||||
#### TriggerClientEvent(playerServerID, eventName, data)
|
||||
Will call that event with the given data on the specified client (-1 for broadcast)
|
||||
```lua
|
||||
function onPlayerJoin(playerServerID)
|
||||
TriggerClientEvent(playerServerID, "anyEvent", "You just joined the server")
|
||||
end
|
||||
RegisterEvent("onAnyEventHappen", "anyEvent")
|
||||
```
|
||||
|
||||
#### Set(configID, newValue)
|
||||
will set a config setting to the new specified value table below|
|
||||
```lua
|
||||
function onChatMessage(playerID, senderName, message)
|
||||
if playerID == adminPlayer then
|
||||
if message == --[[ anything ]] then
|
||||
Set(3, 10)
|
||||
end
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
#### List of available config settings for the `Set()` command
|
||||
> Note that these will not save to the config file.
|
||||
|
||||
|Config ID|Name|Will only accept|
|
||||
|---|---|---|
|
||||
|`0`|Debug setting|true or false|
|
||||
|`1`|Private setting|true or false|
|
||||
|`2`|Max car per player|number|
|
||||
|`3`|Max players|number|
|
||||
|`4`|Map|string|
|
||||
|`5`|Name|string|
|
||||
|`6`|Description|string|
|
||||
|any other ID will result in a console warning|
|
||||
|
||||
### List of available events for scripting
|
||||
#### Default Events
|
||||
Example of how to use an event:
|
||||
```lua
|
||||
function onInit()
|
||||
RegisterEvent("onPlayerJoin", "onPlayerJoin")
|
||||
end
|
||||
|
||||
function onPlayerJoin(playerServerID)
|
||||
-- Do something
|
||||
end
|
||||
```
|
||||
|
||||
If you dont want guests on your server:
|
||||
```lua
|
||||
function onInit()
|
||||
print("noGuests Ready")
|
||||
RegisterEvent("onPlayerAuth","onPlayerAuth")
|
||||
end
|
||||
|
||||
function onPlayerAuth(name, role, isGuest)
|
||||
if isGuest then
|
||||
return "You must be signed in to join this server!"
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
|Event|Parameters|Description|
|
||||
|---|---|---|
|
||||
|`onPlayerAuth`|The player's name, forum role, guest account (bool)|A player has authenticated and is requesting to join|
|
||||
|`onPlayerConnecting`|The player's ID|A player is loading in (Before loading the map)|
|
||||
|`onPlayerJoining`|The player's ID|A player is loading the map and will be joined soon|
|
||||
|`onPlayerJoin`|The player's ID|A player has joined and loaded in|
|
||||
|`onPlayerDisconnect`|The player's ID|A player has disconnected|
|
||||
|`onChatMessage`|The sender's ID, name, and the chat message|A chat message was sent. This would be good for making a commands system|
|
||||
|`onVehicleSpawn`|The player's ID, the vehicle ID, and the vehicle data|This is called when someone spawns a vehicle|
|
||||
|`onVehicleEdited`|The player's ID, the vehicle ID, and the vehicle data|This is called when someone edits a vehicle, or replaces their existing one|
|
||||
|`onVehicleDeleted`|The player's ID and the vehicle ID|This is called when someone deletes a vehicle they own|
|
||||
|
||||
#### Custom Events
|
||||
Custom events can also be created for your own use. This is done very much the same to how the default ones are done.
|
||||
|
||||
Example of how to use a custom event:
|
||||
```lua
|
||||
function onInit()
|
||||
RegisterEvent("myCustomEvent", "myCustomEvent")
|
||||
end
|
||||
|
||||
function myCustomEvent(playerServerID, customData)
|
||||
-- Do something
|
||||
end
|
||||
```
|
||||
|
||||
This can then be called either from client side or serverside using the respective functions.
|
||||
|
||||
### Players
|
||||
|
||||
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.
|
||||
|
||||
#### Static Identifiers
|
||||
|
||||
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() |
|
||||
| discordID | fairly secure | inconvenient | GetPlayerDiscordID() |
|
||||
| HWID | extremely secure | hard to obtain | GetPlayerHWID() |
|
||||
|
||||
### Vehicles
|
||||
|
||||
Vehicles in beamMP have 3 attributes that the server pays attention to, the owner's serverID, the vehicles vehicleID and it's data. 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.
|
||||
@@ -0,0 +1,77 @@
|
||||
# Getting started
|
||||
|
||||
In order to get started with development for BeamMP you will need at least:
|
||||
|
||||
- BeamNG.drive, installed locally
|
||||
- BeamMP, installed locally; at least the launcher, additionally also the server
|
||||
- Git, installed locally, and a GitHub.com account
|
||||
- A code editor, for example VSCode or notepad++
|
||||
|
||||
---
|
||||
# Difference between mod, launcher and server
|
||||
|
||||
BeamMP is split into three main parts:
|
||||
|
||||
- The mod is loaded by BeamNG, like any other vehicle or UI mod for the game. Its main function is to establish a local connection with the launcher and to display the multiplayer UI elements. It's mostly written in Lua, with some JavaScript, HTML, and CSS for the UI elements. Its repo is [https://github.com/BeamMP/BeamMP](https://github.com/BeamMP/BeamMP)
|
||||
- The launcher's main function is to establish a constant connection to the mod, and once necessary, establish a connection to the chosen server, as well as handling user login with the BeamMP backend. It's written in C++, is precompiled by BeamMP and can be found at [https://github.com/BeamMP/BeamMP-Launcher](https://github.com/BeamMP/BeamMP-Launcher)
|
||||
- The server establishes connections between one or many launchers, as well as "heartbeating" to the BeamMP backend, providing information such as IP, port, version, number of players, etc. Additionally, it manages and runs server-side Lua plugins. It's written in C++, precompiled by BeamMP for a few different OS and CPU architectures, and can be found at [https://github.com/BeamMP/BeamMP-Server](https://github.com/BeamMP/BeamMP-Server)
|
||||
|
||||
---
|
||||
# Setting up a development environment to work on the mod
|
||||
|
||||
## Using an unpacked folder for BeamNG
|
||||
|
||||
In order to efficiently work on mods in BeamNG, it is advised to use an `unpacked` folder, rather than packaging zips after every change.
|
||||
|
||||
Open up the BeamNG userfolder by navigating to `%appdata%/Local/BeamNG.drive/0.xx/mods` where `xx` is the most recent BeamNG version.
|
||||
Create a folder called `unpacked` inside the `mods` folder.
|
||||
|
||||
Further information about the userfolder can be found at [https://documentation.beamng.com/support/userfolder/](https://documentation.beamng.com/support/userfolder/)
|
||||
|
||||
## Enabling dev mode in the BeamMP launcher
|
||||
|
||||
In order to prevent auto-update deleting your local git clone, it's necessary to disable it, using `--no-download`.
|
||||
If you also don't want the launcher to start BeamNG, and would like to see debug prints, then using `--dev` is advised.
|
||||
|
||||
| Argument | Note |
|
||||
|:--------------------------------------|:-------------------------------------------|
|
||||
| `--help` or `-h` | Will print the following list of arguments |
|
||||
| `--port <port>` or `-p` | Change the default listen port to `<port>`. This must be configured ingame too |
|
||||
| `--verbose` or `-v` | Verbose mode, prints debug messages |
|
||||
| `--no-download` | Skip downloading and installing the BeamMP Lua mod |
|
||||
| `--no-update` | Skip applying launcher updates (you must update manually) |
|
||||
| `--no-launch` | Skip launching the game (you must launch the game manually) |
|
||||
| `--dev` | Developer mode, same as --verbose --no-download --no-launch --no-update |
|
||||
| `--game <args...>` or `-- <args...>` | Passes arguments to the game |
|
||||
|
||||
## Cloning the BeamMP repo into the unpacked folder
|
||||
|
||||
While you can manually copy the BeamMP mod files from our github repo, it is highly recommended to use a source-control system like git.
|
||||
First create a fork of [https://github.com/BeamMP/BeamMP](https://github.com/BeamMP/BeamMP)
|
||||
|
||||
Most efficient would be to clone the repo directly into the `unpacked` folder.
|
||||
|
||||
For `git`, run `git clone https://github.com/yourName/BeamMP` from a PowerShell or CMD window started from the `unpacked` folder.
|
||||
While in the userfolder, make sure theres no `multiplayer` folder left in `mods` and that now there's `unpacked/beammp`.
|
||||
|
||||
Now give the dev mode a try. Start the BeamMP launcher, start BeamNG manually, once ingame make sure that BeamMP is the only active mod.
|
||||
You should be able to use BeamMP as usual.
|
||||
|
||||
Using a code editor, you can now add or change code directly in the `unpacked` folder.
|
||||
You can then try the changes by reloading Lua ingame by pressing `Ctrl+L` (and `F5` if you made UI changes).
|
||||
|
||||
Once you're happy with your changes, you can commit them through git. See [the Git-SCM website](https://git-scm.com/doc) for tutorials and documentation on how to use Git. As soon as your changes are committed and pushed (to your fork), you can make a pull-request.
|
||||
|
||||
Feel free to ask in the #scripting channel in our [Discord](https://discord.gg/beammp) if you encounter any issues.
|
||||
|
||||
---
|
||||
# Setting up a local server
|
||||
|
||||
While working on BeamMP, it can be beneficial to use a local server. You can follow the general [server installation](../../server/create-a-server.md) while omitting the first two steps for purely local connections.
|
||||
|
||||
Set the server to private in the `serverConfig.toml` while using any string as the `AuthKey`.
|
||||
|
||||
---
|
||||
# Contribution Guidelines
|
||||
|
||||
For details on code format, commit message format, general development best practices, etc. please see the `CONTRIBUTING.md` file in each repo. This file contains more detailed information on how to contribute. The `README.md` in each repo usually contains build steps as well (for compiled projects).
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: Guides
|
||||
description: This set of pages provides some basic guides for BeamMP
|
||||
status: new
|
||||
---
|
||||
::: warning "This site is under construction!"
|
||||
|
||||
This site is being actively worked on.
|
||||
|
||||
Feel you could help? Please do by clicking on the page with a pencil on the right!
|
||||
|
||||
This can be done any page too.
|
||||
|
||||
# BeamMP Development Guides
|
||||
|
||||
This page will be the introduction and preface for both client and server content creation.
|
||||
|
||||
This page needs developing still.
|
||||
@@ -0,0 +1,112 @@
|
||||
# Multiplayer mod creation
|
||||
|
||||
## Folder structure and file basics
|
||||
|
||||
The basic folder and file structure needs to look like this:
|
||||
|
||||
```
|
||||
Resources/
|
||||
├─ Client/
|
||||
│ └─ examplePlugin.zip/
|
||||
│ ├─ scripts/
|
||||
│ │ └─ modScript.lua
|
||||
│ └─ lua/
|
||||
│ └─ ge/
|
||||
│ └─ extensions/
|
||||
│ └─ examplePlugin.lua
|
||||
└─ Server/
|
||||
└─ examplePlugin/
|
||||
├─ examplePlugin.lua
|
||||
└─ further_lua/
|
||||
└─ further.lua
|
||||
```
|
||||
|
||||
The serverside lua is the bare minimum, if you want to add custom events, you also need at least a clientside lua as well as a modscript.lua
|
||||
|
||||
The Server folder must contain subfolders, one for each server-side mod.
|
||||
It is good practice to only have a single main lua file and add further lua files into subfolders.
|
||||
However, you are not required to do that, the server will load lua files in alphabetical order should there be multiple.
|
||||
|
||||
The Client folder contains the zip files that are sent to a client, which then will load them as a mod.
|
||||
Any other files in the Client folder will cause an error on server startup, but apart from that will be ignored by the server.
|
||||
The modScript.lua will be read by BeamNG and instructs the game which plugin to load.
|
||||
|
||||
:::example ""
|
||||
[Download the examplePlugin.zip](../../../../assets/content/ResourcesForExamplePlugin.zip)
|
||||
:::
|
||||
|
||||
## Serverside lua
|
||||
|
||||
There's more examples in the examplePlugin, but heres a very basic one, printing a players identifiers:
|
||||
|
||||
```lua
|
||||
function onInit() --runs when plugin is loaded
|
||||
|
||||
MP.RegisterEvent("onPlayerAuth", "onPlayerAuth") --Provided by BeamMP
|
||||
|
||||
print("examplePlugin loaded")
|
||||
end
|
||||
|
||||
--A player has authenticated and is requesting to join
|
||||
--The player's name (string), forum role (string), guest account (bool), identifiers (table -> ip, beammp)
|
||||
function onPlayerAuth(player_name, role, isGuest, identifiers)
|
||||
local ip = identifiers.ip
|
||||
local beammp = identifiers.beammp or "N/A"
|
||||
print("onPlayerAuth: player_name: " .. player_name .. " | role: " .. role .. " | isGuest: " .. tostring(isGuest) .. " | identifiers: ip: " .. ip .. " - beammp: " .. beammp)
|
||||
end
|
||||
```
|
||||
|
||||
`onPlayerAuth` gets triggered as soon as a player wants to join, also see [onPlayerAuth in the scripting reference](../../../scripting/server/latest-server-reference/#onplayerauth)
|
||||
|
||||
Another example using onPlayerAuth, but this will deny guests from joining the server by sending the client a message back, which will then be shown to the player:
|
||||
|
||||
```lua
|
||||
function onPlayerAuth(playerName, playerRole, isGuest, identifiers)
|
||||
if isGuest then
|
||||
return "No guests allowed, please use a BeamMP account"
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
Further info on serverside functions provided by BeamMP can be found in the [latest server reference](../../../scripting/server/latest-server-reference.md)
|
||||
|
||||
## Clientside lua
|
||||
|
||||
This largely follows the [BeamNG extensions](https://documentation.beamng.com/modding/programming/extensions/)
|
||||
|
||||
```lua
|
||||
local M = {}
|
||||
|
||||
if extensions.isExtensionLoaded("examplePlugin") then
|
||||
log("E", "examplePlugin", "examplePlugin loaded on client side")
|
||||
return
|
||||
end
|
||||
|
||||
return M
|
||||
```
|
||||
Prints to the console that the examplePlugin was loaded
|
||||
|
||||
Refer to the [beamNG documentation on debug prints](https://documentation.beamng.com/modding/programming/debugging/#a-add-a-log) to learn more
|
||||
|
||||
## modScript.lua
|
||||
|
||||
Usually contains only two lines
|
||||
|
||||
```lua
|
||||
load('examplePlugin')
|
||||
setExtensionUnloadMode('examplePlugin', 'manual')
|
||||
```
|
||||
|
||||
You can add a log print if you want to see in the logs when your modScript gets processed by BeamNG
|
||||
|
||||
```lua
|
||||
load('examplePlugin')
|
||||
setExtensionUnloadMode('examplePlugin', 'manual')
|
||||
log('I', 'modScript', "examplePlugin loaded")
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,7 @@
|
||||
::: warning This site is under construction!
|
||||
This site is being actively worked on.
|
||||
|
||||
Feel you could help? Please do by clicking "Edit this page" at the bottom!
|
||||
:::
|
||||
|
||||
# BeamNG.drive Development Introduction
|
||||
@@ -0,0 +1,19 @@
|
||||
::: warning "This site is under construction!"
|
||||
|
||||
This site is being actively worked on.
|
||||
|
||||
Feel you could help? Please do by clicking on the page with a pencil on the right!
|
||||
|
||||
This can be done any page too.
|
||||
|
||||
# BeamNG.drive Map Creation
|
||||
|
||||
...
|
||||
|
||||
## Introduction
|
||||
|
||||
...
|
||||
|
||||
## Getting Started
|
||||
|
||||
...
|
||||
@@ -0,0 +1,19 @@
|
||||
::: warning "This site is under construction!"
|
||||
|
||||
This site is being actively worked on.
|
||||
|
||||
Feel you could help? Please do by clicking on the page with a pencil on the right!
|
||||
|
||||
This can be done any page too.
|
||||
|
||||
# BeamNG.drive Prop Creation
|
||||
|
||||
...
|
||||
|
||||
## Introduction
|
||||
|
||||
...
|
||||
|
||||
## Getting Started
|
||||
|
||||
...
|
||||
@@ -0,0 +1,19 @@
|
||||
::: warning "This site is under construction!"
|
||||
|
||||
This site is being actively worked on.
|
||||
|
||||
Feel you could help? Please do by clicking on the page with a pencil on the right!
|
||||
|
||||
This can be done any page too.
|
||||
|
||||
# BeamNG.drive Vehicle Creation
|
||||
|
||||
...
|
||||
|
||||
## Introduction
|
||||
|
||||
...
|
||||
|
||||
## Getting Started
|
||||
|
||||
...
|
||||
@@ -0,0 +1,7 @@
|
||||
::: warning This site is under construction!
|
||||
This site is being actively worked on.
|
||||
|
||||
Feel you could help? Please do by clicking "Edit this page" at the bottom!
|
||||
:::
|
||||
|
||||
# BeamNG.drive Development Introduction
|
||||
@@ -0,0 +1,88 @@
|
||||
::: warning "This site is under construction!"
|
||||
|
||||
This site is being actively worked on.
|
||||
|
||||
Feel you could help? Please do by clicking on the page with a pencil on the right!
|
||||
|
||||
This can be done any page too.
|
||||
# Creating an ImGui Window
|
||||
|
||||
This page covers how to create a basic ImGui window.
|
||||
|
||||
## Setup
|
||||
|
||||
Before using ImGui, some setup is required:
|
||||
|
||||
```lua
|
||||
local im = ui_imgui -- shortcut to prevent lookups all the time. should help with optimization
|
||||
local imguiExampleWindowOpen = im.BoolPtr(true)
|
||||
```
|
||||
|
||||
`imguiExampleWindowOpen` will be used to determine when this example window should be rendered.
|
||||
|
||||
## Window Rendering
|
||||
|
||||
ImGui windows and their contents must be recreated for every frame they should be displayed. This means that some form of onUpdate function is necessary to use ImGui.
|
||||
|
||||
```lua
|
||||
local function onUpdate()
|
||||
if worldReadyState == 2 then
|
||||
if imguiExampleWindowOpen[0] == true then
|
||||
imguiExample()
|
||||
end
|
||||
end
|
||||
end
|
||||
M.onUpdate = onUpdate
|
||||
```
|
||||
|
||||
This will run a function to create this example's window, so long as the level is fully loaded, and that the example window should be displaying.
|
||||
|
||||
## Window Content
|
||||
|
||||
If you're new to writing ImGui, think of it as a distant cousin of HTML:
|
||||
|
||||
* `im.SetNextWindowSize(im.ImVec2(x, y), im.Cond_FirstUseEver)` defines your viewport size if it hasn't already been defined
|
||||
* `im.Begin()` and `im.End()` is your `<body>` and `</body>`
|
||||
* `im.Text()` is your `<p></p>`
|
||||
|
||||
```lua
|
||||
local buttonPresses = 0
|
||||
|
||||
local function imguiExample()
|
||||
im.SetNextWindowSize(im.ImVec2(366, 100), im.Cond_FirstUseEver) -- prepare our window
|
||||
im.Begin("Hello World, I am a window") -- create a window with the title of "Hello World, I am a window"
|
||||
im.Indent() -- a... padding element
|
||||
im.Text("Hello World, I am text.") -- add a line of text, somewhat like a <p> element
|
||||
im.SameLine() -- Not really HTML. This appends the following element to the same line as the previous element.
|
||||
if im.Button("The Hello World Button") then -- Like <button>. This runs Lua when pressed.
|
||||
buttonPresses = buttonPresses + 1
|
||||
end
|
||||
if buttonPresses > 0 then
|
||||
im.Text("The Hello World Button has been pressed " .. buttonPresses .. " times!")
|
||||
else
|
||||
im.Text("The Hello World Button has not been pressed.")
|
||||
end
|
||||
im.Unindent() -- end the "padding element"
|
||||
im.End() -- complete our "canvas" so it can be drawn
|
||||
end
|
||||
```
|
||||
|
||||
You can add the following function to easily toggle visibility of the window:
|
||||
|
||||
```lua
|
||||
local function toggleExampleImgui()
|
||||
imguiExampleWindowOpen[0] = not imguiExampleWindowOpen[0]
|
||||
end
|
||||
```
|
||||
|
||||
## Result
|
||||
|
||||
<figure class="image image_resized" style="width:100%" markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
When the The Hello World Button button is pressed, the counter below it will update to display the amount of times the The Hello World Button button has been pressed.
|
||||
|
||||
## Download
|
||||
|
||||
This tutorial is almost entirely based off of [StanleyDudek](https://github.com/StanleyDudek)'s ImGui example mod. You can download this example mod [here](../../../../assets/content/imguiExample.zip).
|
||||
@@ -0,0 +1,2 @@
|
||||
# lua-mods.md
|
||||
This page needs creating
|
||||
@@ -0,0 +1,266 @@
|
||||
# UI-App Creation
|
||||
|
||||
In order to make a UI-App you will need some knowledge of the AngularJS framework, the main documentation can be found here: [AngularJS docs](https://docs.angularjs.org/guide)
|
||||
|
||||
## File structure
|
||||
|
||||
A UI-App needs four important files to work:
|
||||
- app.js | Contains the main code used by the UI-App [Javascript docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript)
|
||||
- app.html | The code that displays your app [Html docs](https://developer.mozilla.org/fr/docs/Web/HTML)
|
||||
- app.json | Contains the information of the UI-App
|
||||
- app.png | The image file showing in the app selector
|
||||
|
||||
### UI-App style
|
||||
We recommend using the ``<style>`` tag to style your app, a .css file will work, but you will not be able to see the changes in real-time.
|
||||
|
||||
## Example
|
||||
|
||||
This example is from DanielW Thanks to him
|
||||
|
||||
ui\modules\apps\ExampleApp\app.html
|
||||
```html
|
||||
<div style="width: 100%; height: 100%;" class="bngApp">
|
||||
<link type="text/css" rel="stylesheet" href="/ui/modules/apps/ExampleApp/app.css" />
|
||||
|
||||
<div id="exampleAppContainer">
|
||||
<span>Gear: <span>{{ gearName }}</span></span>
|
||||
|
||||
<div layout="row" layout-align="center center">
|
||||
<md-input-container flex>
|
||||
<label>Input</label>
|
||||
<input ng-model="message" ng-keydown="sendMessage($event)">
|
||||
</md-input-container>
|
||||
|
||||
<md-button md-no-ink class="md-warn" ng-disabled="!message" ng-click="sendMessage()">Send</md-button>
|
||||
</div>
|
||||
|
||||
<span style="display: block">Messages:</span>
|
||||
|
||||
<!-- Scroll Area -->
|
||||
<ul bng-nav-scroll style="margin: 0; padding: 0; overflow-y: auto; width: 100%; height: 100%; background-color: #37373740;">
|
||||
|
||||
<!-- Iterate over the messages and display them -->
|
||||
<li ng-repeat="message in messages track by $index" style="display: flex; align-items: center; height: 35px;">
|
||||
<span style="padding: 0 0.2em; width: 100%;">{{ message }}</span>
|
||||
|
||||
<!-- Button to delete the message, this calls the `deleteMessage` function in `app.js` -->
|
||||
<md-button md-no-ink class="md-icon-button md-warn" ng-click="deleteMessage($index)">
|
||||
<md-icon class="material-icons">delete</md-icon>
|
||||
</md-button>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
Here, you can see a ``<span>`` tag displaying the gear of your vehicle, an input used to send a message to the ``sendMessage()`` function in the Javascript and a repeated ``<li>`` tag using <b>ng-repeat</b> on the ``messages`` variable located in the Javascript
|
||||
|
||||
ui\modules\apps\ExampleApp\app.js
|
||||
```js
|
||||
angular.module('beamng.apps')
|
||||
.directive('exampleApp', [function() {
|
||||
return {
|
||||
templateUrl: '/ui/modules/apps/ExampleApp/app.html',
|
||||
replace: true,
|
||||
restrict: 'EA',
|
||||
scope: true,
|
||||
|
||||
controller: ['$scope', function($scope) {
|
||||
$scope.gearName = '0'
|
||||
$scope.message = ''
|
||||
$scope.messages = []
|
||||
|
||||
// Setup the streams we want. For now, we only want the engine information. You can add more, you'll just have to look around to find the different streams
|
||||
let steamList = ['engineInfo']
|
||||
StreamsManager.add(steamList)
|
||||
|
||||
$scope.$on('destroy', function() {
|
||||
StreamsManager.remove(steamList)
|
||||
})
|
||||
|
||||
// Do I even need to put this comment here explaining what this function does?
|
||||
// Well, I have done it for a lot of other things when they weren't needed. I'll leave this one be...
|
||||
$scope.$on('streamsUpdate', function(event, streams) {
|
||||
if (!streams.engineInfo) // Early return... You probably noticed that without this useless comment though
|
||||
return;
|
||||
|
||||
// `lua/vehicle/controller/vehicleController.lua:538` (or use console.log)
|
||||
let gear = streams.engineInfo[5]
|
||||
|
||||
// Update the gear name in HTML if needed
|
||||
if ($scope.gearName !== gear)
|
||||
$scope.gearName = gear
|
||||
})
|
||||
|
||||
$scope.sendMessage = function(event) {
|
||||
if (event && event.key !== 'Enter')
|
||||
return
|
||||
|
||||
if ($scope.message == '')
|
||||
return
|
||||
|
||||
// Forward the message to the Lua extension to modify it
|
||||
bngApi.engineLua('extensions.exampleMod.modifyMessage("' + $scope.message + '")')
|
||||
$scope.message = ''
|
||||
}
|
||||
|
||||
$scope.deleteMessage = function(idx) {
|
||||
$scope.messages.splice(idx, 1)
|
||||
}
|
||||
|
||||
// The `modifyMessage` function will call this hook with the modified data
|
||||
$scope.$on('MessageReady', function(_, modifiedMessage) {
|
||||
$scope.messages.push(modifiedMessage)
|
||||
});
|
||||
}]
|
||||
}
|
||||
}])
|
||||
```
|
||||
Note the usage of <b>$scope</b>. This is very important because you will need to define your variables and functions within <b>$scope</b> to be able to access it from the <b>Html</b> inside any <b>ng-*</b> tag.
|
||||
So in this example, after the ``sendMessage()`` function being executed from the <b>Html</b> it will send it to a lua file located in the extensions directory of the mod and execute the ``modifyMessage()`` function inside this lua file.
|
||||
|
||||
An example of how the lua side could look like:
|
||||
```lua
|
||||
local function modifyMessage(message)
|
||||
message = message .. " [Modified!]"
|
||||
guihooks.trigger('MessageReady', message)
|
||||
end
|
||||
```
|
||||
^ This is a simplified version of the lua to just show the function
|
||||
|
||||
The main focus here is the usage of <b>guihooks.trigger</b> which triggers an AngularJS event defined with ``$scope.$on()``. As you can see at the very bottom of the Javascript file the event is named MessageReady and will be executed by the <b>guihooks.trigger</b> function with the message payload and then will be pushed inside the ``$scope.messages`` variable to be displayed by the li tag using <b>ng-repeat</b> in the <b>Html</b> file
|
||||
|
||||
The full lua file is just below
|
||||
|
||||
lua\ge\extensions\exampleMod.lua
|
||||
```lua
|
||||
local M = {}
|
||||
|
||||
--[[
|
||||
This is the entry point of our extension, this is what the game loads from our `modScript.lua`.
|
||||
In the modScript file, you can load more extensions and put them in the same directory as this file.
|
||||
|
||||
In this file, we will communicate with the following:
|
||||
1. Our vehicle extension. That extension tells this extension when to send it data, and we send it. Take a look at `vehicle/extensions/auto/exampleVehicleExtension.lua`
|
||||
2. Input. Take a look at `core/input/actions/myActions.json`. When the bounded key is pressed, it will call `onActionKeyDown` (a function we export below)
|
||||
]]
|
||||
|
||||
-- Game Function Hooks
|
||||
--------------------------------------------
|
||||
local function onExtensionLoaded()
|
||||
log('D', "onExtensionLoaded", "Called")
|
||||
end
|
||||
|
||||
local function onExtensionUnloaded()
|
||||
log('D', "onExtensionUnloaded", "Called")
|
||||
end
|
||||
|
||||
-- Custom Functions
|
||||
--------------------------------------------
|
||||
local function onActionKeyDown()
|
||||
log('D', "onActionKeyDown", "Pressed!")
|
||||
end
|
||||
|
||||
local function onVehicleExtensionLoaded(vehID)
|
||||
log('D', "onVehicleExtensionLoaded", "Sending some data to the vehicle")
|
||||
|
||||
local veh = be:getObjectByID(vehID) -- If you don't have the ID, you can also use `be:getPlayerVehicle(0)` to get the current vehicle.
|
||||
if not veh then return end -- The usual error checking
|
||||
|
||||
local data = {
|
||||
["name"] = "Daniel W"
|
||||
}
|
||||
|
||||
veh:queueLuaCommand("extensions.exampleVehicleExtension.onDataReceived('" .. jsonEncode(data) .. "')")
|
||||
end
|
||||
|
||||
local function modifyMessage(message)
|
||||
message = message .. " [Modified!]"
|
||||
guihooks.trigger('MessageReady', message)
|
||||
end
|
||||
|
||||
-- Export Interface
|
||||
--------------------------------------------
|
||||
M.onExtensionLoaded = onExtensionLoaded
|
||||
M.onExtensionUnloaded = onExtensionUnloaded
|
||||
|
||||
M.onActionKeyDown = onActionKeyDown
|
||||
M.onVehicleExtensionLoaded = onVehicleExtensionLoaded
|
||||
M.modifyMessage = modifyMessage
|
||||
|
||||
--[[ Other functions could include:
|
||||
- onPreRender(dtReal, dtSim, dtRaw)
|
||||
- onUpdate(dtReal, dtSim, dtRaw)
|
||||
- onClientPreStartMission(levelPath)
|
||||
- onClientPostStartMission(levelPath)
|
||||
|
||||
To find all of these, search the following in `BeamNG.Drive/lua`: `extensions.hook(`
|
||||
--]]
|
||||
|
||||
return M
|
||||
```
|
||||
|
||||
Note that its very important to return the M (module) variable with the needed functions inside!
|
||||
For example, without the ``M.modifyMessage = modifyMessage`` line, the ``bngApi.engineLua('extensions.exampleMod.modifyMessage("' + $scope.message + '")')`` function will not be able to find the modifyMessage() function
|
||||
|
||||
|
||||
ui\modules\apps\ExampleApp\app.css
|
||||
```css
|
||||
#exampleAppContainer {
|
||||
width: 100%;
|
||||
height: 100%;
|
||||
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
align-items: center;
|
||||
align-content: center;
|
||||
}
|
||||
|
||||
#exampleAppContainer > * {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
}
|
||||
```
|
||||
|
||||
ui\modules\apps\ExampleApp\app.json
|
||||
```json
|
||||
{
|
||||
"domElement": "<example-app></example-app>",
|
||||
"name": "Example App",
|
||||
"types": [
|
||||
"ui.apps.categories.debug"
|
||||
],
|
||||
"description": "example-app",
|
||||
"css": {
|
||||
"left": "0px",
|
||||
"height": "auto",
|
||||
"width": "270px",
|
||||
"min-width": "200px",
|
||||
"min-height": "90px",
|
||||
"top": "0px"
|
||||
},
|
||||
"author": "Daniel W",
|
||||
"version": "0.1",
|
||||
"directive": "exampleApp"
|
||||
}
|
||||
```
|
||||
The directive needs to be the same as in the <b>Javascript</b> file
|
||||
|
||||
|
||||
|
||||
|
||||
# Javascript functions provided by BeamNG for UI-Apps
|
||||
|
||||
```js
|
||||
bngApi.engineLua("lua_path.function()")
|
||||
```
|
||||
Useful to run a lua function with or without arguments
|
||||
|
||||
# Lua functions provided by BeamNG for UI-Apps
|
||||
|
||||
```lua
|
||||
guihooks.trigger("EventName", Payload)
|
||||
```
|
||||
The payload can be any type but its better to keep it as an Array / Object or a String to not be lost.
|
||||
|
||||
<b>IMPORTANT</b> : Sometime it can happen that the event name you use is already used internally by something else and cause problems, so for example if your app is named Nickel, it can be a good practice to name every of your Angular event like NKEventName instead of EventName
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
::: warning "This site is under construction!"
|
||||
|
||||
This site is being actively worked on.
|
||||
|
||||
Feel you could help? Please do by clicking on the page with a pencil on the right!
|
||||
|
||||
This can be done any page too.
|
||||
|
||||
# BeamNG.drive CEF Code Snippets
|
||||
|
||||
to-do
|
||||
@@ -0,0 +1,275 @@
|
||||
::: warning "This site is under construction!"
|
||||
|
||||
This site is being actively worked on.
|
||||
|
||||
Feel you could help? Please do by clicking on the page with a pencil on the right!
|
||||
|
||||
This can be done any page too.
|
||||
|
||||
# BeamNG.drive CSS Code Snippets
|
||||
|
||||
## Common variables
|
||||
|
||||
=== "BeamNG CEF Orange"
|
||||
|
||||
```css
|
||||
var(--bng-orange) /*Common orange*/
|
||||
var(--bng-orange-shade1) /*70% opacity*/
|
||||
var(--bng-orange-shade2) /*40% opacity*/
|
||||
var(--bng-orange-shade1opaque)
|
||||
var(--bng-orange-shade2opaque)
|
||||
```
|
||||
|
||||
=== "Monochrome"
|
||||
|
||||
```css
|
||||
--- Monochrome
|
||||
var(--bng-black-8) /*80% opacity (duplicate --bng-black-o8)*/
|
||||
var(--bng-black-6) /*60% opacity (duplicate --bng-black-o6)*/
|
||||
var(--bng-black-4) /*40% opacity (duplicate --bng-black-o4)*/
|
||||
var(--bng-black-2) /*20% opacity (duplicate --bng-black-o2)*/
|
||||
|
||||
var(--dark-neutral-grey)
|
||||
var(--neutral-grey)
|
||||
var(--light-neutral-grey)
|
||||
var(--dark-grey)
|
||||
var(--dark-grey-alpha) /*80% opacity*/
|
||||
|
||||
var(--black-1) /*70% opacity*/
|
||||
var(--black-2) /*40% opacity (duplicate --bng-black-o4)*/
|
||||
|
||||
var(--white-1) /*80% opacity*/
|
||||
var(--white-2) /*40% opacity*/
|
||||
var(--white-3) /*20% opacity*/
|
||||
```
|
||||
|
||||
=== "BeamNG Vue UI Color Palette"
|
||||
|
||||
All of these support adding `-rgb` to the end of the variable name to convert them to raw red, green, blue values. Use -rgb like so: `rgba(var(--bng-orange-500-rgb), 0.5)` for 50% opacity bng-orange-500.
|
||||
|
||||
=== "Add Red"
|
||||
|
||||
```css
|
||||
var(--bng-add-red-50)
|
||||
var(--bng-add-red-100)
|
||||
var(--bng-add-red-200)
|
||||
var(--bng-add-red-300)
|
||||
var(--bng-add-red-400)
|
||||
var(--bng-add-red-500)
|
||||
var(--bng-add-red-550)
|
||||
var(--bng-add-red-600)
|
||||
var(--bng-add-red-650)
|
||||
var(--bng-add-red-700)
|
||||
var(--bng-add-red-750)
|
||||
var(--bng-add-red-800)
|
||||
var(--bng-add-red-850)
|
||||
var(--bng-add-red-900)
|
||||
```
|
||||
|
||||
=== "Orange"
|
||||
|
||||
```css
|
||||
var(--bng-orange-50)
|
||||
var(--bng-orange-100)
|
||||
var(--bng-orange-200)
|
||||
var(--bng-orange-300)
|
||||
var(--bng-orange-400)
|
||||
var(--bng-orange-500)
|
||||
var(--bng-orange-550)
|
||||
var(--bng-orange-600)
|
||||
var(--bng-orange-650)
|
||||
var(--bng-orange-700)
|
||||
var(--bng-orange-750)
|
||||
var(--bng-orange-800)
|
||||
var(--bng-orange-850)
|
||||
var(--bng-orange-900)
|
||||
```
|
||||
|
||||
=== "Ter Peach"
|
||||
|
||||
```css
|
||||
var(--bng-ter-peach-50)
|
||||
var(--bng-ter-peach-100)
|
||||
var(--bng-ter-peach-200)
|
||||
var(--bng-ter-peach-300)
|
||||
var(--bng-ter-peach-400)
|
||||
var(--bng-ter-peach-500)
|
||||
var(--bng-ter-peach-550)
|
||||
var(--bng-ter-peach-600)
|
||||
var(--bng-ter-peach-650)
|
||||
var(--bng-ter-peach-700)
|
||||
var(--bng-ter-peach-750)
|
||||
var(--bng-ter-peach-800)
|
||||
var(--bng-ter-peach-850)
|
||||
var(--bng-ter-peach-900)
|
||||
```
|
||||
|
||||
=== "Ter Yellow"
|
||||
|
||||
```css
|
||||
var(--bng-ter-yellow-50)
|
||||
var(--bng-ter-yellow-100)
|
||||
var(--bng-ter-yellow-200)
|
||||
var(--bng-ter-yellow-300)
|
||||
var(--bng-ter-yellow-400)
|
||||
var(--bng-ter-yellow-500)
|
||||
var(--bng-ter-yellow-550)
|
||||
var(--bng-ter-yellow-600)
|
||||
var(--bng-ter-yellow-650)
|
||||
var(--bng-ter-yellow-700)
|
||||
var(--bng-ter-yellow-750)
|
||||
var(--bng-ter-yellow-800)
|
||||
var(--bng-ter-yellow-850)
|
||||
var(--bng-ter-yellow-900)
|
||||
```
|
||||
|
||||
=== "Add Green"
|
||||
|
||||
```css
|
||||
var(--bng-add-green-50)
|
||||
var(--bng-add-green-100)
|
||||
var(--bng-add-green-200)
|
||||
var(--bng-add-green-300)
|
||||
var(--bng-add-green-400)
|
||||
var(--bng-add-green-500)
|
||||
var(--bng-add-green-600)
|
||||
var(--bng-add-green-700)
|
||||
var(--bng-add-green-800)
|
||||
var(--bng-add-green-900)
|
||||
```
|
||||
|
||||
=== "Baby Blue"
|
||||
|
||||
```css
|
||||
var(--bng-add-babyblue-50)
|
||||
var(--bng-add-babyblue-100)
|
||||
var(--bng-add-babyblue-200)
|
||||
var(--bng-add-babyblue-300)
|
||||
var(--bng-add-babyblue-400)
|
||||
var(--bng-add-babyblue-500)
|
||||
var(--bng-add-babyblue-550)
|
||||
var(--bng-add-babyblue-600)
|
||||
var(--bng-add-babyblue-650)
|
||||
var(--bng-add-babyblue-700)
|
||||
var(--bng-add-babyblue-750)
|
||||
var(--bng-add-babyblue-800)
|
||||
var(--bng-add-babyblue-850)
|
||||
var(--bng-add-babyblue-900)
|
||||
```
|
||||
|
||||
=== "Add Blue"
|
||||
|
||||
```css
|
||||
var(--bng-add-blue-50)
|
||||
var(--bng-add-blue-100)
|
||||
var(--bng-add-blue-200)
|
||||
var(--bng-add-blue-300)
|
||||
var(--bng-add-blue-400)
|
||||
var(--bng-add-blue-500)
|
||||
var(--bng-add-blue-600)
|
||||
var(--bng-add-blue-700)
|
||||
var(--bng-add-blue-800)
|
||||
var(--bng-add-blue-900)
|
||||
```
|
||||
|
||||
=== "Indigo Blue"
|
||||
|
||||
```css
|
||||
var(--bng-add-indigoblue-50)
|
||||
var(--bng-add-indigoblue-100)
|
||||
var(--bng-add-indigoblue-200)
|
||||
var(--bng-add-indigoblue-300)
|
||||
var(--bng-add-indigoblue-400)
|
||||
var(--bng-add-indigoblue-500)
|
||||
var(--bng-add-indigoblue-550)
|
||||
var(--bng-add-indigoblue-600)
|
||||
var(--bng-add-indigoblue-650)
|
||||
var(--bng-add-indigoblue-700)
|
||||
var(--bng-add-indigoblue-750)
|
||||
var(--bng-add-indigoblue-800)
|
||||
var(--bng-add-indigoblue-850)
|
||||
var(--bng-add-indigoblue-900)
|
||||
```
|
||||
|
||||
=== "Add Magenta"
|
||||
|
||||
```css
|
||||
var(--bng-add-magenta-50)
|
||||
var(--bng-add-magenta-100)
|
||||
var(--bng-add-magenta-200)
|
||||
var(--bng-add-magenta-300)
|
||||
var(--bng-add-magenta-400)
|
||||
var(--bng-add-magenta-500)
|
||||
var(--bng-add-magenta-550)
|
||||
var(--bng-add-magenta-600)
|
||||
var(--bng-add-magenta-650)
|
||||
var(--bng-add-magenta-700)
|
||||
var(--bng-add-magenta-750)
|
||||
var(--bng-add-magenta-800)
|
||||
var(--bng-add-magenta-850)
|
||||
var(--bng-add-magenta-900)
|
||||
```
|
||||
|
||||
=== "Ter Blue Gray"
|
||||
|
||||
```css
|
||||
var(--bng-ter-blue-gray-50)
|
||||
var(--bng-ter-blue-gray-100)
|
||||
var(--bng-ter-blue-gray-200)
|
||||
var(--bng-ter-blue-gray-300)
|
||||
var(--bng-ter-blue-gray-400)
|
||||
var(--bng-ter-blue-gray-500)
|
||||
var(--bng-ter-blue-gray-550)
|
||||
var(--bng-ter-blue-gray-600)
|
||||
var(--bng-ter-blue-gray-650)
|
||||
var(--bng-ter-blue-gray-700)
|
||||
var(--bng-ter-blue-gray-750)
|
||||
var(--bng-ter-blue-gray-800)
|
||||
var(--bng-ter-blue-gray-850)
|
||||
var(--bng-ter-blue-gray-900)
|
||||
```
|
||||
|
||||
=== "Cool Gray"
|
||||
|
||||
```css
|
||||
var(--bng-cool-gray-50)
|
||||
var(--bng-cool-gray-100)
|
||||
var(--bng-cool-gray-200)
|
||||
var(--bng-cool-gray-300)
|
||||
var(--bng-cool-gray-400)
|
||||
var(--bng-cool-gray-500)
|
||||
var(--bng-cool-gray-550)
|
||||
var(--bng-cool-gray-600)
|
||||
var(--bng-cool-gray-650)
|
||||
var(--bng-cool-gray-700)
|
||||
var(--bng-cool-gray-750)
|
||||
var(--bng-cool-gray-800)
|
||||
var(--bng-cool-gray-850)
|
||||
var(--bng-cool-gray-900)
|
||||
```
|
||||
|
||||
=== "Other"
|
||||
|
||||
```css
|
||||
var(--bng-off-black) /*Used in Vue for buttons and some headers*/
|
||||
var(--bng-off-white) /*Used in Vue for interactable elements*/
|
||||
var(--bng-off-white-brighter) /*Used in Vue for headers*/
|
||||
```
|
||||
|
||||
=== "Extra color presets"
|
||||
|
||||
```css
|
||||
var(--bng-filter-orange) /*Filter preset to force SVGs to use bng-orange*/
|
||||
var(--bng-black-o8) /*80% opacity*/
|
||||
var(--bng-black-o6) /*60% opacity*/
|
||||
var(--bng-black-o4) /*40% opacity*/
|
||||
var(--bng-black-o2) /*20% opacity*/
|
||||
```
|
||||
|
||||
=== "Corner rounding presets"
|
||||
|
||||
```css
|
||||
var(--bng-corners-1) /*0.25rem*/
|
||||
var(--bng-corners-2) /*0.50rem*/
|
||||
var(--bng-corners-3) /*1.00rem*/
|
||||
```
|
||||
@@ -0,0 +1,78 @@
|
||||
::: warning "This site is under construction!"
|
||||
|
||||
This site is being actively worked on.
|
||||
|
||||
Feel you could help? Please do by clicking on the page with a pencil on the right!
|
||||
|
||||
This can be done any page too.
|
||||
:::
|
||||
|
||||
# BeamNG.drive ImGui Code Snippets
|
||||
|
||||
## Setup
|
||||
|
||||
### Setup ImGui
|
||||
|
||||
```lua
|
||||
local im = ui_imgui
|
||||
```
|
||||
|
||||
### Setup Window
|
||||
|
||||
```lua
|
||||
im.SetNextWindowSize(im.ImVec2(366, 100), im.Cond_FirstUseEver)
|
||||
```
|
||||
|
||||
### Create window
|
||||
|
||||
```lua
|
||||
im.Begin("Window Title") -- Create window
|
||||
im.End()
|
||||
```
|
||||
|
||||
## General
|
||||
|
||||
=== "Basic Formatting"
|
||||
|
||||
```lua
|
||||
im.Text("")
|
||||
im.TextWrapped("") -- automatic word wrap
|
||||
im.TextColored(im.ImVec4(0,1,0,1), "") -- R,G,B,A
|
||||
im.TextDisabled("") -- predefined style for disabled text
|
||||
|
||||
im.LabelText("", "")
|
||||
im.BulletText("") -- Bullet point with text
|
||||
im.SeparatorText("") -- Separator with centered text
|
||||
|
||||
im.Separator() -- might want a NewLine before these
|
||||
im.SameLine() -- horizontally append the following element to the previous element
|
||||
im.NewLine()
|
||||
|
||||
im.Spacing() -- small padding
|
||||
im.Indent()
|
||||
im.Unindent()
|
||||
```
|
||||
|
||||
=== "Inputs"
|
||||
|
||||
```lua
|
||||
im.Button("", im.ImVec2(0,0)) -- 0 = fit to content
|
||||
im.SmallButton("") -- Fit to content and slightly less padding
|
||||
im.ArrowButton("", 0) -- arg 1: string is not actually used? arg 2: 0 = left, 1 = right, 2 = up, 3 = down
|
||||
im.InvisibleButton("", im.ImVec2(0,0), ...) -- used for imgui cursor positioning?
|
||||
|
||||
im.Checkbox("", im.BoolPtr(false))
|
||||
|
||||
im.RadioButton1("", im.BoolPtr(false))
|
||||
im.RadioButton2("", im.IntPtr(), 0) -- arg. 3: 0 or 1 for disabled or enabled
|
||||
```
|
||||
|
||||
=== "Other"
|
||||
|
||||
```lua
|
||||
im.Bullet()
|
||||
|
||||
im.ProgressBar(0.5, im.ImVec2(0,0), "") -- arg 2: 0 for default width and/or height
|
||||
|
||||
im.TextUnformatted("", "") -- Second argument seems to crash the game
|
||||
```
|
||||
@@ -0,0 +1,381 @@
|
||||
::: warning "This site is under construction!"
|
||||
|
||||
This site is being actively worked on.
|
||||
|
||||
Feel you could help? Please do by clicking on the page with a pencil on the right!
|
||||
|
||||
This can be done any page too.
|
||||
|
||||
# BeamNG.drive Lua Code Snippets
|
||||
|
||||
## World
|
||||
|
||||
### Drawing a marker & Vehicle detection
|
||||
|
||||
Drawing markers in the map can be one of the best ways to indicate to the user that there is some form of interaction that they can do there.
|
||||
|
||||
Drawing a marker is fairly easy. Here is an example of how the bus route marker is drawn:
|
||||
|
||||
```lua
|
||||
local function createBusMarker(markerName)
|
||||
local marker = createObject('TSStatic')
|
||||
marker:setField('shapeName', 0, "art/shapes/interface/position_marker.dae")
|
||||
marker:setPosition(vec3(0, 0, 0))
|
||||
marker.scale = vec3(1, 1, 1)
|
||||
marker:setField('rotation', 0, '1 0 0 0')
|
||||
marker.useInstanceRenderData = true
|
||||
marker:setField('instanceColor', 0, '1 1 1 0')
|
||||
marker:setField('collisionType', 0, "Collision Mesh")
|
||||
marker:setField('decalType', 0, "Collision Mesh")
|
||||
marker:setField('playAmbient', 0, "1")
|
||||
marker:setField('allowPlayerStep', 0, "1")
|
||||
marker:setField('canSave', 0, "0")
|
||||
marker:setField('canSaveDynamicFields', 0, "1")
|
||||
marker:setField('renderNormals', 0, "0")
|
||||
marker:setField('meshCulling', 0, "0")
|
||||
marker:setField('originSort', 0, "0")
|
||||
marker:setField('forceDetail', 0, "-1")
|
||||
marker.canSave = false
|
||||
marker:registerObject(markerName)
|
||||
scenetree.MissionGroup:addObject(marker)
|
||||
return marker
|
||||
end
|
||||
|
||||
-- this can then be called in a loop to setup your markers.
|
||||
-- NOTE: You should only do this once as part of your setup and not called on each frame.
|
||||
if #markers == 0 then
|
||||
for k,v in pairs(nameMarkers) do
|
||||
local mk = scenetree.findObject(v)
|
||||
if mk == nil then
|
||||
log('I', logTag,'Creating marker '..tostring(v))
|
||||
mk = createBusMarker(v)
|
||||
ScenarioObjectsGroup:addObject(mk.obj)
|
||||
end
|
||||
table.insert(markers, mk)
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
Here is a custom marker example from [BeamNG-FuelStations](https://github.com/BeamMP/BeamNG-FuelStations/tree/master):
|
||||
|
||||
```lua
|
||||
local stations = [
|
||||
{ "location": [ -778.813, 485.973, 23.46 ], "type":"gas" },
|
||||
{ "location": [ 617.164, -192.107, 53.2 ], "type":"ev" },
|
||||
]
|
||||
|
||||
local function IsEntityInsideArea(pos1, pos2, radius)
|
||||
return pos1:distance(pos2) < radius
|
||||
end
|
||||
|
||||
local onUpdate = function (dt)
|
||||
for k, spot in pairs(stations) do -- loop through all spots on the current map
|
||||
local bottomPos = vec3(spot.location[1], spot.location[2], spot.location[3])
|
||||
local topPos = bottomPos + vec3(0,0,2) -- offset vec to get top position (2m tall)
|
||||
|
||||
local spotInRange = false -- is this spot in range? used for color
|
||||
local spotCompatible = false -- is this spot compatible?
|
||||
|
||||
if activeVeh then -- we have a car and its ours (if in mp)
|
||||
local vehPos = activeVeh:getPosition()
|
||||
|
||||
spotInRange = IsEntityInsideArea(vec3(vehPos.x, vehPos.y,vehPos.z), bottomPos, 1.5)
|
||||
|
||||
spotCompatible = activeFuelType == "any" or spot.type == "any" or activeFuelType == spot.type
|
||||
end
|
||||
|
||||
local spotColor = (spotInRange and spotCompatible) and activeColorMap[spot.type] or inactiveColorMap[spot.type] or ColorF(1,1,1,0.5)
|
||||
|
||||
debugDrawer:drawCylinder(bottomPos:toPoint3F(), topPos:toPoint3F(), 1, spotColor) --bottom, top, radius, color
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
## User Interface
|
||||
|
||||
### Toast Notifications, Top right of screen
|
||||
|
||||
<figure class="image image_resized" style="width:75%" markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
```lua
|
||||
--guihooks.trigger('toastrMsg', {type, title, msg, config = {timeOut}})
|
||||
guihooks.trigger('toastrMsg', {type = "info", title = "Info Message:", msg = "Info Message Text Here", config = {timeOut = 5000}})
|
||||
guihooks.trigger('toastrMsg', {type = "warning", title = "Warning Message:", msg = "Warning Message Text Here", config = {timeOut = 5000}})
|
||||
guihooks.trigger('toastrMsg', {type = "error", title = "Error Message:", msg = "Error Message Text Here", config = {timeOut = 5000}})
|
||||
```
|
||||
|
||||
### Message notifications, top left of screen by default in Messages app
|
||||
|
||||
This requires the 'Messages' or 'Messages & Tasks' UI app. Icons can be found at `ui\ui-vue\src\assets\fonts\bngIcons\svg\`
|
||||
|
||||
<figure class="image image_resized" style="width:75%" markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
```lua
|
||||
--guihooks.trigger('Message', {msg, ttl, category, icon})
|
||||
--ui_message(msg, ttl, category, icon)
|
||||
guihooks.trigger('Message', {msg = "Message Text Here", ttl = 5.0, category = "arrow_upward", icon = "arrow_upward"})
|
||||
guihooks.trigger('Message', {msg = "Message Text Here", ttl = 5.0, category = "arrow_downward", icon = "arrow_downward"})
|
||||
guihooks.trigger('Message', {msg = "Message Text Here", ttl = 5.0, category = "flag", icon = "flag"})
|
||||
guihooks.trigger('Message', {msg = "Message Text Here", ttl = 5.0, category = "check", icon = "check"})
|
||||
guihooks.trigger('Message', {msg = "Message Text Here", ttl = 5.0, category = "check_circle", icon = "check_circle"})
|
||||
guihooks.trigger('Message', {msg = "Message Text Here", ttl = 5.0, category = "warning", icon = "warning"})
|
||||
guihooks.trigger('Message', {msg = "Message Text Here", ttl = 5.0, category = "error", icon = "error"})
|
||||
guihooks.trigger('Message', {msg = "Message Text Here", ttl = 5.0, category = "directions_car", icon = "directions_car"})
|
||||
guihooks.trigger('Message', {msg = "Message Text Here", ttl = 5.0, category = "star", icon = "star"})
|
||||
guihooks.trigger('Message', {msg = "Message Text Here", ttl = 5.0, category = "timeline", icon = "timeline"})
|
||||
guihooks.trigger('Message', {msg = "Message Text Here", ttl = 5.0, category = "save", icon = "save"})
|
||||
guihooks.trigger('Message', {msg = "Message Text Here", ttl = 5.0, category = "settings", icon = "settings"})
|
||||
```
|
||||
|
||||
### Center large or small display flash
|
||||
|
||||
<figure class="image image_resized" style="width:75%" markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
<figure class="image image_resized" style="width:75%" markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
```lua
|
||||
--guihooks.trigger('ScenarioFlashMessage', {{msg, ttl, sound, big}} ) -- requires RaceCountdown ui app
|
||||
guihooks.trigger('ScenarioFlashMessage', {{"Message", 5.0, 0, true}} )
|
||||
guihooks.trigger('ScenarioFlashMessage', {{"Message Text Here", 5.0, 0, false}} )
|
||||
|
||||
--countdown example, when all executed at once, the items are queued and will follow eachother after the previous ttl expires
|
||||
guihooks.trigger('ScenarioFlashMessage', {{"3", 1.0, "Engine.Audio.playOnce('AudioGui', 'event:UI_Countdown1')", true}})
|
||||
guihooks.trigger('ScenarioFlashMessage', {{"2", 1.0, "Engine.Audio.playOnce('AudioGui', 'event:UI_Countdown2')", true}})
|
||||
guihooks.trigger('ScenarioFlashMessage', {{"1", 1.0, "Engine.Audio.playOnce('AudioGui', 'event:UI_Countdown3')", true}})
|
||||
guihooks.trigger('ScenarioFlashMessage', {{"GO!", 3.0, "Engine.Audio.playOnce('AudioGui', 'event:UI_CountdownGo')", true}})
|
||||
|
||||
--another sound example
|
||||
guihooks.trigger('ScenarioFlashMessage', {{"Teleported!", 3.0, "Engine.Audio.playOnce('AudioGui', 'event:UI_Checkpoint')", false}})
|
||||
```
|
||||
|
||||
### Center mid-size persistent display
|
||||
|
||||
This requires the 'Race Realtime Display' UI app.
|
||||
|
||||
<figure class="image image_resized" style="width:75%" markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
```lua
|
||||
--guihooks.trigger('ScenarioRealtimeDisplay', {msg = msg} ) -- requires Race Realtime Display ui app
|
||||
guihooks.trigger('ScenarioRealtimeDisplay', {msg = "Message Text Here"} )
|
||||
--these messages persist, clear with a blank string
|
||||
--if you are running live data, this is a good one to update rapidly (think timers, distance calcs, et cetera)
|
||||
guihooks.trigger('ScenarioRealtimeDisplay', {msg = ""} )
|
||||
```
|
||||
|
||||
### Confirmation Dialog
|
||||
|
||||
ConfirmationDialog is a simplistic popup with up to two buttons.
|
||||
|
||||
```lua
|
||||
-- Open a ConfirmationDialog with a title, body text, and up to two buttons
|
||||
guihooks.trigger("ConfirmationDialogOpen",
|
||||
"Example Title",
|
||||
"Example Body Text",
|
||||
"Okay",
|
||||
"", --gelua. empty string
|
||||
"Cancel",
|
||||
"" --gelua
|
||||
)
|
||||
|
||||
-- Close any open ConfirmationDialog with the provided title
|
||||
guihooks.trigger("ConfirmationDialogClose", "Example Title")
|
||||
```
|
||||
|
||||
<figure class="image image_resized" style="width:75%" markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
Both fields of a button must be strings in order for the button to appear.
|
||||
|
||||
If the Okay button is provided, pressing the *OK / Primary action* action is equivalent to pressing the Okay button.
|
||||
|
||||
If the Cancel button is provided, pressing the *Menu* action is equivalent to pressing the Cancel button.
|
||||
|
||||
HTML is supported and can be used to add images/icons, for example.
|
||||
|
||||
Multiple can be displayed at once, displayed sequentially.
|
||||
|
||||
::: bug
|
||||
|
||||
Providing no buttons prevents the player from escaping the dialog without using the console.
|
||||
|
||||
::: bug
|
||||
|
||||
The SDF parts of the Minimap UI app remain visible while a ConfirmationDialog is active.
|
||||
|
||||
`#!lua guihooks.trigger('ShowApps', false)` to hide UI apps can be used as a hacky workaround.
|
||||
|
||||
<figure class="image image_resized" style="width:75%" markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
### introPopupTutorial
|
||||
|
||||
introPopupTutorial is a highly customizable popup that is largely defined with embedded HTML. It is standard to load from a standalone HTML file located in `/gameplay/tutorials/pages/*/content.html`.
|
||||
|
||||
```lua
|
||||
guihooks.trigger("introPopupTutorial", {
|
||||
{
|
||||
content = readFile("/gameplay/tutorials/pages/template/content.html"):gsub("\r\n",""),
|
||||
flavour = "onlyOk"
|
||||
}
|
||||
})
|
||||
|
||||
guihooks.trigger("introPopupClose")
|
||||
```
|
||||
|
||||
<figure class="image image_resized" style="width:75%" markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
`flavour` controls which buttons are displayed. Four flavours exist:
|
||||
|
||||
* `withLogbook`
|
||||
* Buttons: Career Logbook, Okay
|
||||
* `onlyOk`
|
||||
* Buttons: Okay
|
||||
* `onlyLogbook`
|
||||
* Buttons: Career Logbook
|
||||
* `noButtons`
|
||||
* Provides no buttons
|
||||
|
||||
::: warning
|
||||
|
||||
When using the noButtons flavour on the page, providing no extra JavaScript in the page content to close the popup causes a softlock. Pages are not combined into one popup in this flavour. It is not recommended to use this flavour.
|
||||
|
||||
If multiple pages are provided, or the hook is triggered multiple times, then the pages are combined into the same popup. If the hook is triggered while a introPopup is active, or when a different introPopup type has already been triggered, then it is displayed in a separate popup after the existing popup is closed.
|
||||
|
||||
### introPopupCareer
|
||||
|
||||
introPopupCareer is an easy to use, but open ended popup that supports embedding HTML, if needed.
|
||||
|
||||
Flavours control which buttons are displayed and the default image aspect ratio. Four flavours exist:
|
||||
|
||||
* `default`
|
||||
* Default image aspect ratio: 16x9
|
||||
* Buttons: Later, Okay
|
||||
* `welcome`
|
||||
* Default image aspect ratio: 16x9
|
||||
* Buttons: Career Logbook, Okay
|
||||
* `branch-info`
|
||||
* Default image aspect ratio: 16x9
|
||||
* Buttons: Career Logbook, Okay
|
||||
* `garage`
|
||||
* Buttons: Later, Okay
|
||||
|
||||
```lua
|
||||
guihooks.trigger("introPopupCareer", {
|
||||
{
|
||||
title = "Example title",
|
||||
text = "Example text",
|
||||
image = "/gameplay/tutorials/pages/template/image.jpg",
|
||||
ratio = "16x9",
|
||||
flavour = "default"
|
||||
}
|
||||
})
|
||||
|
||||
guihooks.trigger("introPopupClose")
|
||||
```
|
||||
|
||||
<figure class="image image_resized" style="width:75%" markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
If multiple pages are provided, or the hook is triggered multiple times, then the pages are combined into the same popup. If the hook is triggered while a introPopup is active, or when a different introPopup type has already been triggered, then it is displayed in a separate popup after the existing popup is closed.
|
||||
|
||||
::: bug
|
||||
|
||||
The background blur has a minimum height, causing popups with short content to have excess blur below its window. Two main workarounds exist:
|
||||
|
||||
* Repeat `\n` and end with `#!html <div />` until the window covers the blur
|
||||
* Use an empty or missing `image` path and adjust the aspect ratio until the window covers the blur
|
||||
|
||||
### introPopupMission
|
||||
|
||||
introPopupMission is almost identical to introPopupCareer, but needs buttons to be defined rather than picking a preset for buttons.
|
||||
|
||||
Button styles are combined as *bng-button-*`style`. Built-in button styles are:
|
||||
|
||||
* `main` - orange
|
||||
* `secondary` - cyan
|
||||
* `attention` - red
|
||||
* `white` - white
|
||||
* `link` - translucent
|
||||
* `outline` - orange outline
|
||||
|
||||
```lua
|
||||
guihooks.trigger('introPopupMission', {
|
||||
title = "introPopupMission title",
|
||||
text = "introPopupMission description",
|
||||
image = "/gameplay/tutorials/pages/template/image.jpg",
|
||||
ratio = "16x9",
|
||||
buttons = {
|
||||
{ default=true, class="main", label="main button", clickLua="" },
|
||||
{ default=false, class="secondary", label="secondary button", clickLua="" },
|
||||
{ default=false, class="attention", label="attention button", clickLua="" },
|
||||
{ default=false, class="white", label="white button", clickLua="" },
|
||||
{ default=false, class="link", label="link button", clickLua="" },
|
||||
{ default=false, class="outline", label="outline button", clickLua="" }
|
||||
}
|
||||
})
|
||||
|
||||
guihooks.trigger("introPopupClose")
|
||||
```
|
||||
|
||||
<figure class="image image_resized" style="width:75%" markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
If multiple pages are provided, or the hook is triggered multiple times, then the pages are combined into the same popup. If the hook is triggered while a introPopup is active, or when a different introPopup type has already been triggered, then it is displayed in a separate popup after the existing popup is closed.
|
||||
|
||||
::: bug
|
||||
|
||||
The background blur has a minimum height, causing popups with short content to have excess blur below its window. Two main workarounds exist:
|
||||
|
||||
* Repeat `\n` and end with `#!html <div />` until the window covers the blur
|
||||
* Use an empty or missing `image` path and adjust the aspect ratio until the window covers the blur
|
||||
|
||||
### Dialogue
|
||||
|
||||
Dialogue is used in the *A Rocky Start* campaign to display information about a mission. It is a centered, vertically aligned popup with a specific layout. It does not support embedding HTML.
|
||||
|
||||
```lua
|
||||
ui_missionInfo.openDialogue({
|
||||
title = "Dialogue title",
|
||||
type = "Custom", -- isn't actually displayed
|
||||
typeName = "typeName",
|
||||
data = {
|
||||
{label = "objective", value = "reward"}
|
||||
-- add more...
|
||||
},
|
||||
buttons = {
|
||||
{action = "accept", text = "Accept", cmd = ""},
|
||||
{action = 'decline',text = "Decline", cmd = ""}
|
||||
-- add more...
|
||||
}
|
||||
})
|
||||
|
||||
ui_missionInfo.closeDialogue()
|
||||
```
|
||||
|
||||
<figure class="image image_resized" style="width:75%" markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
Only one Dialogue can be displayed at once. Any existing Dialogue is overridden.
|
||||
|
||||
::: info
|
||||
|
||||
`#!lua ui_missionInfo.closeDialogue()` must be used to close a dialogue.
|
||||
|
||||
Make sure you call this function when any button is pressed.
|
||||
@@ -0,0 +1,179 @@
|
||||
# Getting Started
|
||||
|
||||
## **1. Compatibility**
|
||||
|
||||
BeamMP is fully compatible with Windows and Linux, compatibility with MacOS is being worked on.
|
||||
However, both Linux and MacOS are secondary platforms, this means bugs are to be expected.
|
||||
|
||||
::: warning
|
||||
BeamMP will not work with pirated or outdated versions of BeamNG.drive.
|
||||
The BeamMP support team does not offer support for issues with pirated / outdated copies.
|
||||
:::
|
||||
---
|
||||
|
||||
## **2. Installation**
|
||||
|
||||
### **2a. Windows Installation**
|
||||
|
||||
::: note
|
||||
As of April 1st, 2026, the MSI installer is an "unrecognized app" according to Windows Defender SmartScreen.
|
||||
|
||||
To bypass this warning, click 'More info', then click 'Run anyway'.
|
||||
:::
|
||||
|
||||
1. Go to [beammp.com](https://beammp.com/) and click the 'Download Now' button.
|
||||
2. Run the `BeamMP_Installer.msi` installer and follow the instructions.
|
||||
3. The BeamMP Launcher icon should appear on your desktop. If not, just search for “BeamMP” in the Windows search bar.
|
||||
|
||||
::: note
|
||||
As you are loading into a map with multiple vehicles spawned it might take longer than expected to join.
|
||||
:::
|
||||
|
||||
### **2b. Linux Installation**
|
||||
|
||||
Currently you need to build the Launcher yourself.
|
||||
In order to do this, you need a basic understanding of how to build an application.
|
||||
|
||||
Make sure you have basic development tools installed, often found in packages, for example:
|
||||
|
||||
- Debian/Ubuntu: `sudo apt install build-essential`
|
||||
- Fedora: `sudo dnf install cmake gcc gcc-c++ make perl perl-IPC-Cmd perl-FindBin perl-File-Compare perl-File-Copy kernel-headers kernel-devel`
|
||||
- Arch: `sudo pacman -S base-devel`
|
||||
- openSUSE: `zypper in -t pattern devel-basis`
|
||||
- SteamOS (Arch): `sudo pacman -S base-devel linux-api-headers glibc libconfig` (You also need to do `sudo steamos-readonly disable` but make sure to enable it again after installing the packages)
|
||||
|
||||
|
||||
Clone `vcpkg`, bootstrap it and add it to PATH
|
||||
|
||||
1.
|
||||
```bash
|
||||
git clone https://github.com/microsoft/vcpkg.git
|
||||
```
|
||||
|
||||
2.
|
||||
```bash
|
||||
./vcpkg/bootstrap-vcpkg.sh
|
||||
```
|
||||
|
||||
3.
|
||||
```bash
|
||||
export VCPKG_ROOT="$(pwd)/vcpkg"
|
||||
export PATH=$VCPKG_ROOT:$PATH
|
||||
```
|
||||
|
||||
|
||||
Clone the BeamMP-Launcher Repository to your system using `git`, for example:
|
||||
`git clone https://github.com/BeamMP/BeamMP-Launcher.git`
|
||||
[Additional information about cloning a GitHub Repo](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
|
||||
|
||||
If you've used the example clone command we provided, you can use `cd BeamMP-Launcher` to go to the project's root directory.
|
||||
|
||||
Checkout the tag that was used for the [latest release](https://github.com/BeamMP/BeamMP-Launcher/releases/latest). For example, if `v2.8.0` is used in the latest release, then do `git checkout v2.8.0`
|
||||
|
||||
In the root directory of the project,
|
||||
|
||||
1.
|
||||
```cmake
|
||||
cmake . -B bin -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-linux
|
||||
```
|
||||
|
||||
2.
|
||||
```cmake
|
||||
cmake --build bin --parallel
|
||||
```
|
||||
|
||||
::: note
|
||||
Should you run out of RAM while building, you can ommit the --parallel instruction, it will then use less RAM due to building only on one CPU thread.
|
||||
:::
|
||||
|
||||
:::note ""
|
||||
By not specifying `-DCMAKE_BUILD_TYPE=Release` you are building a debug version, which is larger in filesize but does not contain the launcher-can-only-connect-to-a-server-once bug
|
||||
:::
|
||||
|
||||
:::note Fedora Users
|
||||
If vcpkg fails during OpenSSL compilation with kernel headers errors, ensure all dependencies are installed:
|
||||
```bash
|
||||
sudo dnf install kernel-headers kernel-devel gcc gcc-c++ make perl
|
||||
```
|
||||
Then clean the vcpkg cache:
|
||||
```bash
|
||||
rm -rf $VCPKG_ROOT/buildtrees/openssl
|
||||
```
|
||||
And retry the cmake configuration command.
|
||||
:::
|
||||
|
||||
Move the finished application out of the `/bin` folder into its own folder and run it from there:
|
||||
```bash
|
||||
mkdir -p ~/beammp-launcher
|
||||
cp bin/BeamMP-Launcher ~/beammp-launcher/
|
||||
cd ~/beammp-launcher
|
||||
./BeamMP-Launcher
|
||||
```
|
||||
|
||||
The native Linux BeamMP-Launcher will start and use native Linux BeamNG.drive
|
||||
|
||||
### **2c. Using beamNG.drive with Proton**
|
||||
|
||||
Should you want to use the native linux BeamMP-Launcher together with BeamNG.drive running through Proton, you can do so:
|
||||
|
||||
Run the BeamMP-Launcher using the argument ` --no-launch` (This will prevent the Launcher from starting native linux BeamNG.drive). Further information about launcher arguments can be found in the [Development Environment Setup](../developers/dev-environment-setup.md)
|
||||
|
||||
Change the userfolder location of Proton-BeamNG.drive to the location of Linux-BeamNG.drive (since the native linux BeamMP-Launcher currently only writes into the Linux-BeamNG.drive userfolder)
|
||||
|
||||
This can be done for example by creating a symlink
|
||||
|
||||
- Note the Linux-BeamNG.drive userfolder location (this is usually found in `~/.local/share/BeamNG.drive`) and rename it, for example to `BeamNG.drive_old`
|
||||
- Note the Proton-BeamNG.drive userfolder location (this is usually found in `~/.local/share/Steam/steamapps/compatdata/284160/pfx/drive_c/users/steamuser/AppData/Local/BeamNG.drive`)
|
||||
- Create a symlink between both userfolders `ln -s ~/.local/share/Steam/steamapps/compatdata/284160/pfx/drive_c/users/steamuser/AppData/Local/BeamNG.drive ~/.local/share`
|
||||
|
||||
With the symlink in place between the userfolders and the launcher compiled, you can have Steam run the game via Proton, while also automatically executing the launcher with the following replacement for your launch options for the vanilla game, found in the game's Properties window in its entry in Steam:
|
||||
|
||||
- `~/BeamMP/BeamMP-Launcher --no-launch & %command% ; killall BeamMP-Launcher`
|
||||
|
||||
Note that this assumes you put the launcher's binary you compiled earlier into `/home/user/BeamMP/`, so change it to match where you put the finished binary, and you will need to re-compile the launcher with the correct git branch each time a launcher update is released.
|
||||
|
||||
::: tip "Adding an emoji-font to get in-text emojis"
|
||||
In order to get emojis to show up in either the serverlist (As part of a servers customised name) or in the ingame chat, you need to have a font that contains emojis.
|
||||
|
||||
This can be done for example by adding the [Linux-port of the Windows Segoe-UI emoji font](https://github.com/mrbvrz/segoe-ui-linux)
|
||||
:::
|
||||
|
||||
### **2d. Updating the Launcher**
|
||||
|
||||
If you already built the launcher and want to update it:
|
||||
|
||||
```bash
|
||||
export VCPKG_ROOT="$(pwd)/vcpkg"
|
||||
cd BeamMP-Launcher
|
||||
git fetch --tags
|
||||
```
|
||||
Checkout the tag that was used for the [latest release](https://github.com/BeamMP/BeamMP-Launcher/releases/latest). For example, if `v2.8.0` is used in the latest release, then do `git checkout v2.8.0`
|
||||
```
|
||||
cmake . -B bin -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-linux
|
||||
cmake --build bin --parallel
|
||||
cp bin/BeamMP-Launcher ~/beammp-launcher/
|
||||
cd ~/beammp-launcher
|
||||
./BeamMP-Launcher
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
||||
## **3. Using BeamMP**
|
||||
|
||||
1. Once you have started the launcher, you should see a terminal window. Shortly after, the standard BeamNG launcher should start. **Do not** close the terminal window.
|
||||
2. In the BeamNG.drive main menu, click the `Repository` button and check to make sure that `multiplayerbeammp` is **the only** enabled mod.
|
||||
3. Return to the main menu, click on 'More..' and the 'Multiplayer' button to start multiplayer.
|
||||
4. You will be prompted to login or play as a guest (not all servers will allow guests). You can create an account on our [forum](https://forum.beammp.com) and then login to BeamMP with the same credentials.
|
||||
5. Select any server you like, and press `Connect`. Enjoy!
|
||||
|
||||
---
|
||||
|
||||
## **4. Known Issues**
|
||||
|
||||
- The native linux BeamMP-Launcher currently can only connect to a server once, after disconnecting you need to restart the launcher. You can do that without closing the game inbetween
|
||||
- If you don’t see the “Multiplayer” button. Make sure that the BeamMP mod is present and activated in the “Mod Manager” then try pressing CTRL + L.
|
||||
- VPNs of any type may cause connection issues.
|
||||
- If the Launcher reports any errors, read the [FAQ](https://forum.beammp.com/c/faq/35).
|
||||
|
||||
Should you need further help with installation, you are welcome to create a post on our [forum](https://forum.beammp.com) or ask on our [Discord server](https://discord.gg/beammp).
|
||||
@@ -0,0 +1,179 @@
|
||||
# Getting Started
|
||||
|
||||
## **1. Compatibility**
|
||||
|
||||
BeamMP is fully compatible with Windows and Linux, compatibility with MacOS is being worked on.
|
||||
However, both Linux and MacOS are secondary platforms, this means bugs are to be expected.
|
||||
|
||||
::: warning
|
||||
BeamMP will not work with pirated or outdated versions of BeamNG.drive.
|
||||
The BeamMP support team does not offer support for issues with pirated / outdated copies.
|
||||
:::
|
||||
---
|
||||
|
||||
## **2. Installation**
|
||||
|
||||
### **2a. Windows Installation**
|
||||
|
||||
::: note
|
||||
As of April 1st, 2026, the MSI installer is an "unrecognized app" according to Windows Defender SmartScreen.
|
||||
|
||||
To bypass this warning, click 'More info', then click 'Run anyway'.
|
||||
:::
|
||||
|
||||
1. Go to [beammp.com](https://beammp.com/) and click the 'Download Now' button.
|
||||
2. Run the `BeamMP_Installer.msi` installer and follow the instructions.
|
||||
3. The BeamMP Launcher icon should appear on your desktop. If not, just search for “BeamMP” in the Windows search bar.
|
||||
|
||||
::: note
|
||||
As you are loading into a map with multiple vehicles spawned it might take longer than expected to join.
|
||||
:::
|
||||
|
||||
### **2b. Linux Installation**
|
||||
|
||||
Currently you need to build the Launcher yourself.
|
||||
In order to do this, you need a basic understanding of how to build an application.
|
||||
|
||||
Make sure you have basic development tools installed, often found in packages, for example:
|
||||
|
||||
- Debian/Ubuntu: `sudo apt install build-essential`
|
||||
- Fedora: `sudo dnf install cmake gcc gcc-c++ make perl perl-IPC-Cmd perl-FindBin perl-File-Compare perl-File-Copy kernel-headers kernel-devel`
|
||||
- Arch: `sudo pacman -S base-devel`
|
||||
- openSUSE: `zypper in -t pattern devel-basis`
|
||||
- SteamOS (Arch): `sudo pacman -S base-devel linux-api-headers glibc libconfig` (You also need to do `sudo steamos-readonly disable` but make sure to enable it again after installing the packages)
|
||||
|
||||
|
||||
Clone `vcpkg`, bootstrap it and add it to PATH
|
||||
|
||||
1.
|
||||
```bash
|
||||
git clone https://github.com/microsoft/vcpkg.git
|
||||
```
|
||||
|
||||
2.
|
||||
```bash
|
||||
./vcpkg/bootstrap-vcpkg.sh
|
||||
```
|
||||
|
||||
3.
|
||||
```bash
|
||||
export VCPKG_ROOT="$(pwd)/vcpkg"
|
||||
export PATH=$VCPKG_ROOT:$PATH
|
||||
```
|
||||
|
||||
|
||||
Clone the BeamMP-Launcher Repository to your system using `git`, for example:
|
||||
`git clone https://github.com/BeamMP/BeamMP-Launcher.git`
|
||||
[Additional information about cloning a GitHub Repo](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
|
||||
|
||||
If you've used the example clone command we provided, you can use `cd BeamMP-Launcher` to go to the project's root directory.
|
||||
|
||||
Checkout the tag that was used for the [latest release](https://github.com/BeamMP/BeamMP-Launcher/releases/latest). For example, if `v2.8.0` is used in the latest release, then do `git checkout v2.8.0`
|
||||
|
||||
In the root directory of the project,
|
||||
|
||||
1.
|
||||
```cmake
|
||||
cmake . -B bin -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-linux
|
||||
```
|
||||
|
||||
2.
|
||||
```cmake
|
||||
cmake --build bin --parallel
|
||||
```
|
||||
|
||||
::: note
|
||||
Should you run out of RAM while building, you can ommit the --parallel instruction, it will then use less RAM due to building only on one CPU thread.
|
||||
:::
|
||||
|
||||
:::note ""
|
||||
By not specifying `-DCMAKE_BUILD_TYPE=Release` you are building a debug version, which is larger in filesize but does not contain the launcher-can-only-connect-to-a-server-once bug
|
||||
:::
|
||||
|
||||
:::note Fedora Users
|
||||
If vcpkg fails during OpenSSL compilation with kernel headers errors, ensure all dependencies are installed:
|
||||
```bash
|
||||
sudo dnf install kernel-headers kernel-devel gcc gcc-c++ make perl
|
||||
```
|
||||
Then clean the vcpkg cache:
|
||||
```bash
|
||||
rm -rf $VCPKG_ROOT/buildtrees/openssl
|
||||
```
|
||||
And retry the cmake configuration command.
|
||||
:::
|
||||
|
||||
Move the finished application out of the `/bin` folder into its own folder and run it from there:
|
||||
```bash
|
||||
mkdir -p ~/beammp-launcher
|
||||
cp bin/BeamMP-Launcher ~/beammp-launcher/
|
||||
cd ~/beammp-launcher
|
||||
./BeamMP-Launcher
|
||||
```
|
||||
|
||||
The native Linux BeamMP-Launcher will start and use native Linux BeamNG.drive
|
||||
|
||||
### **2c. Using beamNG.drive with Proton**
|
||||
|
||||
Should you want to use the native linux BeamMP-Launcher together with BeamNG.drive running through Proton, you can do so:
|
||||
|
||||
Run the BeamMP-Launcher using the argument ` --no-launch` (This will prevent the Launcher from starting native linux BeamNG.drive). Further information about launcher arguments can be found in the [Development Environment Setup](../developers/dev-environment-setup.md)
|
||||
|
||||
Change the userfolder location of Proton-BeamNG.drive to the location of Linux-BeamNG.drive (since the native linux BeamMP-Launcher currently only writes into the Linux-BeamNG.drive userfolder)
|
||||
|
||||
This can be done for example by creating a symlink
|
||||
|
||||
- Note the Linux-BeamNG.drive userfolder location (this is usually found in `~/.local/share/BeamNG.drive`) and rename it, for example to `BeamNG.drive_old`
|
||||
- Note the Proton-BeamNG.drive userfolder location (this is usually found in `~/.local/share/Steam/steamapps/compatdata/284160/pfx/drive_c/users/steamuser/AppData/Local/BeamNG.drive`)
|
||||
- Create a symlink between both userfolders `ln -s ~/.local/share/Steam/steamapps/compatdata/284160/pfx/drive_c/users/steamuser/AppData/Local/BeamNG.drive ~/.local/share`
|
||||
|
||||
With the symlink in place between the userfolders and the launcher compiled, you can have Steam run the game via Proton, while also automatically executing the launcher with the following replacement for your launch options for the vanilla game, found in the game's Properties window in its entry in Steam:
|
||||
|
||||
- `~/BeamMP/BeamMP-Launcher --no-launch & %command% ; killall BeamMP-Launcher`
|
||||
|
||||
Note that this assumes you put the launcher's binary you compiled earlier into `/home/user/BeamMP/`, so change it to match where you put the finished binary, and you will need to re-compile the launcher with the correct git branch each time a launcher update is released.
|
||||
|
||||
::: tip "Adding an emoji-font to get in-text emojis"
|
||||
In order to get emojis to show up in either the serverlist (As part of a servers customised name) or in the ingame chat, you need to have a font that contains emojis.
|
||||
|
||||
This can be done for example by adding the [Linux-port of the Windows Segoe-UI emoji font](https://github.com/mrbvrz/segoe-ui-linux)
|
||||
:::
|
||||
|
||||
### **2d. Updating the Launcher**
|
||||
|
||||
If you already built the launcher and want to update it:
|
||||
|
||||
```bash
|
||||
export VCPKG_ROOT="$(pwd)/vcpkg"
|
||||
cd BeamMP-Launcher
|
||||
git fetch --tags
|
||||
```
|
||||
Checkout the tag that was used for the [latest release](https://github.com/BeamMP/BeamMP-Launcher/releases/latest). For example, if `v2.8.0` is used in the latest release, then do `git checkout v2.8.0`
|
||||
```
|
||||
cmake . -B bin -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-linux
|
||||
cmake --build bin --parallel
|
||||
cp bin/BeamMP-Launcher ~/beammp-launcher/
|
||||
cd ~/beammp-launcher
|
||||
./BeamMP-Launcher
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
||||
## **3. Using BeamMP**
|
||||
|
||||
1. Once you have started the launcher, you should see a terminal window. Shortly after, the standard BeamNG launcher should start. **Do not** close the terminal window.
|
||||
2. In the BeamNG.drive main menu, click the `Repository` button and check to make sure that `multiplayerbeammp` is **the only** enabled mod.
|
||||
3. Return to the main menu, click on 'More..' and the 'Multiplayer' button to start multiplayer.
|
||||
4. You will be prompted to login or play as a guest (not all servers will allow guests). You can create an account on our [forum](https://forum.beammp.com) and then login to BeamMP with the same credentials.
|
||||
5. Select any server you like, and press `Connect`. Enjoy!
|
||||
|
||||
---
|
||||
|
||||
## **4. Known Issues**
|
||||
|
||||
- The native linux BeamMP-Launcher currently can only connect to a server once, after disconnecting you need to restart the launcher. You can do that without closing the game inbetween
|
||||
- If you don’t see the “Multiplayer” button. Make sure that the BeamMP mod is present and activated in the “Mod Manager” then try pressing CTRL + L.
|
||||
- VPNs of any type may cause connection issues.
|
||||
- If the Launcher reports any errors, read the [FAQ](https://forum.beammp.com/c/faq/35).
|
||||
|
||||
Should you need further help with installation, you are welcome to create a post on our [forum](https://forum.beammp.com) or ask on our [Discord server](https://discord.gg/beammp).
|
||||
@@ -0,0 +1,179 @@
|
||||
# Getting Started
|
||||
|
||||
## **1. Compatibility**
|
||||
|
||||
BeamMP is fully compatible with Windows and Linux, compatibility with MacOS is being worked on.
|
||||
However, both Linux and MacOS are secondary platforms, this means bugs are to be expected.
|
||||
|
||||
::: warning
|
||||
BeamMP will not work with pirated or outdated versions of BeamNG.drive.
|
||||
The BeamMP support team does not offer support for issues with pirated / outdated copies.
|
||||
:::
|
||||
---
|
||||
|
||||
## **2. Installation**
|
||||
|
||||
### **2a. Windows Installation**
|
||||
|
||||
::: note
|
||||
As of April 1st, 2026, the MSI installer is an "unrecognized app" according to Windows Defender SmartScreen.
|
||||
|
||||
To bypass this warning, click 'More info', then click 'Run anyway'.
|
||||
:::
|
||||
|
||||
1. Go to [beammp.com](https://beammp.com/) and click the 'Download Now' button.
|
||||
2. Run the `BeamMP_Installer.msi` installer and follow the instructions.
|
||||
3. The BeamMP Launcher icon should appear on your desktop. If not, just search for “BeamMP” in the Windows search bar.
|
||||
|
||||
::: note
|
||||
As you are loading into a map with multiple vehicles spawned it might take longer than expected to join.
|
||||
:::
|
||||
|
||||
### **2b. Linux Installation**
|
||||
|
||||
Currently you need to build the Launcher yourself.
|
||||
In order to do this, you need a basic understanding of how to build an application.
|
||||
|
||||
Make sure you have basic development tools installed, often found in packages, for example:
|
||||
|
||||
- Debian/Ubuntu: `sudo apt install build-essential`
|
||||
- Fedora: `sudo dnf install cmake gcc gcc-c++ make perl perl-IPC-Cmd perl-FindBin perl-File-Compare perl-File-Copy kernel-headers kernel-devel`
|
||||
- Arch: `sudo pacman -S base-devel`
|
||||
- openSUSE: `zypper in -t pattern devel-basis`
|
||||
- SteamOS (Arch): `sudo pacman -S base-devel linux-api-headers glibc libconfig` (You also need to do `sudo steamos-readonly disable` but make sure to enable it again after installing the packages)
|
||||
|
||||
|
||||
Clone `vcpkg`, bootstrap it and add it to PATH
|
||||
|
||||
1.
|
||||
```bash
|
||||
git clone https://github.com/microsoft/vcpkg.git
|
||||
```
|
||||
|
||||
2.
|
||||
```bash
|
||||
./vcpkg/bootstrap-vcpkg.sh
|
||||
```
|
||||
|
||||
3.
|
||||
```bash
|
||||
export VCPKG_ROOT="$(pwd)/vcpkg"
|
||||
export PATH=$VCPKG_ROOT:$PATH
|
||||
```
|
||||
|
||||
|
||||
Clone the BeamMP-Launcher Repository to your system using `git`, for example:
|
||||
`git clone https://github.com/BeamMP/BeamMP-Launcher.git`
|
||||
[Additional information about cloning a GitHub Repo](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
|
||||
|
||||
If you've used the example clone command we provided, you can use `cd BeamMP-Launcher` to go to the project's root directory.
|
||||
|
||||
Checkout the tag that was used for the [latest release](https://github.com/BeamMP/BeamMP-Launcher/releases/latest). For example, if `v2.8.0` is used in the latest release, then do `git checkout v2.8.0`
|
||||
|
||||
In the root directory of the project,
|
||||
|
||||
1.
|
||||
```cmake
|
||||
cmake . -B bin -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-linux
|
||||
```
|
||||
|
||||
2.
|
||||
```cmake
|
||||
cmake --build bin --parallel
|
||||
```
|
||||
|
||||
::: note
|
||||
Should you run out of RAM while building, you can ommit the --parallel instruction, it will then use less RAM due to building only on one CPU thread.
|
||||
:::
|
||||
|
||||
:::note ""
|
||||
By not specifying `-DCMAKE_BUILD_TYPE=Release` you are building a debug version, which is larger in filesize but does not contain the launcher-can-only-connect-to-a-server-once bug
|
||||
:::
|
||||
|
||||
:::note Fedora Users
|
||||
If vcpkg fails during OpenSSL compilation with kernel headers errors, ensure all dependencies are installed:
|
||||
```bash
|
||||
sudo dnf install kernel-headers kernel-devel gcc gcc-c++ make perl
|
||||
```
|
||||
Then clean the vcpkg cache:
|
||||
```bash
|
||||
rm -rf $VCPKG_ROOT/buildtrees/openssl
|
||||
```
|
||||
And retry the cmake configuration command.
|
||||
:::
|
||||
|
||||
Move the finished application out of the `/bin` folder into its own folder and run it from there:
|
||||
```bash
|
||||
mkdir -p ~/beammp-launcher
|
||||
cp bin/BeamMP-Launcher ~/beammp-launcher/
|
||||
cd ~/beammp-launcher
|
||||
./BeamMP-Launcher
|
||||
```
|
||||
|
||||
The native Linux BeamMP-Launcher will start and use native Linux BeamNG.drive
|
||||
|
||||
### **2c. Using beamNG.drive with Proton**
|
||||
|
||||
Should you want to use the native linux BeamMP-Launcher together with BeamNG.drive running through Proton, you can do so:
|
||||
|
||||
Run the BeamMP-Launcher using the argument ` --no-launch` (This will prevent the Launcher from starting native linux BeamNG.drive). Further information about launcher arguments can be found in the [Development Environment Setup](../developers/dev-environment-setup.md)
|
||||
|
||||
Change the userfolder location of Proton-BeamNG.drive to the location of Linux-BeamNG.drive (since the native linux BeamMP-Launcher currently only writes into the Linux-BeamNG.drive userfolder)
|
||||
|
||||
This can be done for example by creating a symlink
|
||||
|
||||
- Note the Linux-BeamNG.drive userfolder location (this is usually found in `~/.local/share/BeamNG.drive`) and rename it, for example to `BeamNG.drive_old`
|
||||
- Note the Proton-BeamNG.drive userfolder location (this is usually found in `~/.local/share/Steam/steamapps/compatdata/284160/pfx/drive_c/users/steamuser/AppData/Local/BeamNG.drive`)
|
||||
- Create a symlink between both userfolders `ln -s ~/.local/share/Steam/steamapps/compatdata/284160/pfx/drive_c/users/steamuser/AppData/Local/BeamNG.drive ~/.local/share`
|
||||
|
||||
With the symlink in place between the userfolders and the launcher compiled, you can have Steam run the game via Proton, while also automatically executing the launcher with the following replacement for your launch options for the vanilla game, found in the game's Properties window in its entry in Steam:
|
||||
|
||||
- `~/BeamMP/BeamMP-Launcher --no-launch & %command% ; killall BeamMP-Launcher`
|
||||
|
||||
Note that this assumes you put the launcher's binary you compiled earlier into `/home/user/BeamMP/`, so change it to match where you put the finished binary, and you will need to re-compile the launcher with the correct git branch each time a launcher update is released.
|
||||
|
||||
::: tip "Adding an emoji-font to get in-text emojis"
|
||||
In order to get emojis to show up in either the serverlist (As part of a servers customised name) or in the ingame chat, you need to have a font that contains emojis.
|
||||
|
||||
This can be done for example by adding the [Linux-port of the Windows Segoe-UI emoji font](https://github.com/mrbvrz/segoe-ui-linux)
|
||||
:::
|
||||
|
||||
### **2d. Updating the Launcher**
|
||||
|
||||
If you already built the launcher and want to update it:
|
||||
|
||||
```bash
|
||||
export VCPKG_ROOT="$(pwd)/vcpkg"
|
||||
cd BeamMP-Launcher
|
||||
git fetch --tags
|
||||
```
|
||||
Checkout the tag that was used for the [latest release](https://github.com/BeamMP/BeamMP-Launcher/releases/latest). For example, if `v2.8.0` is used in the latest release, then do `git checkout v2.8.0`
|
||||
```
|
||||
cmake . -B bin -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-linux
|
||||
cmake --build bin --parallel
|
||||
cp bin/BeamMP-Launcher ~/beammp-launcher/
|
||||
cd ~/beammp-launcher
|
||||
./BeamMP-Launcher
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
||||
## **3. Using BeamMP**
|
||||
|
||||
1. Once you have started the launcher, you should see a terminal window. Shortly after, the standard BeamNG launcher should start. **Do not** close the terminal window.
|
||||
2. In the BeamNG.drive main menu, click the `Repository` button and check to make sure that `multiplayerbeammp` is **the only** enabled mod.
|
||||
3. Return to the main menu, click on 'More..' and the 'Multiplayer' button to start multiplayer.
|
||||
4. You will be prompted to login or play as a guest (not all servers will allow guests). You can create an account on our [forum](https://forum.beammp.com) and then login to BeamMP with the same credentials.
|
||||
5. Select any server you like, and press `Connect`. Enjoy!
|
||||
|
||||
---
|
||||
|
||||
## **4. Known Issues**
|
||||
|
||||
- The native linux BeamMP-Launcher currently can only connect to a server once, after disconnecting you need to restart the launcher. You can do that without closing the game inbetween
|
||||
- If you don’t see the “Multiplayer” button. Make sure that the BeamMP mod is present and activated in the “Mod Manager” then try pressing CTRL + L.
|
||||
- VPNs of any type may cause connection issues.
|
||||
- If the Launcher reports any errors, read the [FAQ](https://forum.beammp.com/c/faq/35).
|
||||
|
||||
Should you need further help with installation, you are welcome to create a post on our [forum](https://forum.beammp.com) or ask on our [Discord server](https://discord.gg/beammp).
|
||||
@@ -0,0 +1,255 @@
|
||||
# Mutliplayer Settings
|
||||
|
||||
## **1. General**
|
||||
|
||||
??? setting "Show advanced options"
|
||||
|
||||
If enabled, you will see all multiplayer settings
|
||||
|
||||
If disabled, you will see only basic multiplayer settings
|
||||
|
||||
??? setting "Enable config cloning protection"
|
||||
|
||||
If enabled, your spawned vehicle config will be protected from other players saving it
|
||||
|
||||
If disabled, your spawned vehicle config can be saved by other players
|
||||
|
||||
??? setting "Disable pausing caused by instabilities"
|
||||
|
||||
If enabled, physics instabilities will not cause your game to pause
|
||||
|
||||
If disabled, physics instabilities will cause your game to pause
|
||||
|
||||
::: note ""
|
||||
|
||||
Its advised to leave disabled, since repeated instabilities can cause the game to crash
|
||||
|
||||
??? setting "Use simplified vehicles when available"
|
||||
|
||||
If enabled, the game will replace vehicles of other players with their simplified versions (from AI traffic) if available
|
||||
|
||||
If disabled, the game will use the intended vehicle models
|
||||
|
||||
??? setting "New chat menu"
|
||||
|
||||
If enabled, the ingame chat will be displayed in an [IMGUI](https://github.com/ocornut/imgui) window, that for example can be dragged out of the game onto another monitor
|
||||
|
||||
If disabled, the ingame chat will be displayed in the UI app
|
||||
|
||||
::: note ""
|
||||
|
||||
Dragging IMGUI windows out of the main game window can cause performance issues, as well as trick screen recording software into recording the chat window instead of the main game window
|
||||
|
||||
??? setting "Enable vehicle position smoothing"
|
||||
|
||||
If enabled, beamMP will use an algorithm to smooth vehicle position updates to regular intervalls. Can be beneficial between players with high ping or when a connection experiences a high package drop rate
|
||||
|
||||
If disabled, beamMP will update vehicle locations as they are received
|
||||
|
||||
??? setting "Skip the mod security warning popusp"
|
||||
|
||||
If enabled, the mod security popup will not be shown when trying to connect to a server with mods
|
||||
|
||||
If disabled, the mod security popup will be shown whenever you connect to a server with mods
|
||||
|
||||
??? setting "Enable player vehicle update/edit queuing"
|
||||
|
||||
If enabled, other players vehicle spawns and edits will be put into a queue. See the section `2. Event queue` for further details
|
||||
|
||||
If disabled, other players vehicle spawns and edits will be loaded by the game instantly
|
||||
|
||||
??? setting "Enable automatic part sync"
|
||||
|
||||
If enabled, your vehicles parts will automatically be synced to other players after a few seconds
|
||||
|
||||
If disbaled, you need to click the part sync button in the part picker in order to send a sync out to other players
|
||||
|
||||
??? setting "Disable switching to other players vehicles"
|
||||
|
||||
If enabled, tabbing trough vehicles will skip other players vehicles
|
||||
|
||||
If disabled, tabbing trough vehicles will cycle over every spawned vehicle
|
||||
|
||||
??? setting "Fade out vehicles as they get closer"
|
||||
|
||||
If enabled, other vehicles will fade out as they get closer
|
||||
|
||||
If disbaled, other vehicles will stay fully visible regardless of distance
|
||||
|
||||
::: note ""
|
||||
|
||||
This only affects the visible 3d mesh of a vehicle, not its physics node-beam-mesh. In order to also disable physics, you need to enable `Simplified collision physics` in the Gameplay settings
|
||||
|
||||
??? setting "Show the player ID`s"
|
||||
|
||||
If enabled, the ingame playerlist will have an additional row showing each players ID. Useful for development or moderation
|
||||
|
||||
If disabled, the ingame playerlist will only show the rows for playername and ping
|
||||
|
||||
??? setting "Allow the serverlist to refresh ingame"
|
||||
|
||||
If enabled, the serverlist will update in regular intervalls while playing. This can cause lag spikes
|
||||
|
||||
If disabled, the serverlist will only update once you open the main menu
|
||||
|
||||
## **2. Event queue**
|
||||
|
||||
??? setting "Highlight queued players"
|
||||
|
||||
If enabled, players with a queued event will be highlighted in the ingame playerlist
|
||||
|
||||
If disabled, players will not be individually highlighted
|
||||
|
||||
??? setting "Apply vehicle changes with"
|
||||
|
||||
If set to `Left mouse button`, clicking on a players name in the playerlist using the left mouse button will load the queued events. Clicking with the right mouse button will spectate said player
|
||||
|
||||
If set to `Right mouse button`, clicking on a players name in the playerlist using the right mouse button will load the queued events. Clicking with the left mouse button will spectate said player
|
||||
|
||||
??? setting "Automatically apply queued vehicle changes"
|
||||
|
||||
If enabled, the queued events will be automatically loaded once you've been going under the speed treshold for the amount of time set as the timeout
|
||||
|
||||
If disabled, the queued events will only load manually, by clicking on either the `Events` button at the top of the screen or on a players name in the playerlist
|
||||
|
||||
??? setting "Queue apply speed treshold"
|
||||
|
||||
This setpoint defines the speed treshold of the automatic event queue loading. Your vehicle has to be slower than this for longer than `Queue apply timeout` in order to load the queued events
|
||||
|
||||
??? setting "Queue apply timeout"
|
||||
|
||||
This setpoint defines the time delay of the automatic event queue loading. Your vehicle has to be slower than `Queue apply speed treshold` for this time in order to load the queued events
|
||||
|
||||
??? setting "Skip queue if spectating others"
|
||||
|
||||
If enabled, an event will instantly load if you are spectating another player
|
||||
|
||||
If disabled, an event will be queued just like it would when focused on your own vehicle
|
||||
|
||||
??? setting "Don't queue Unicycles (Snowmen/Beamlings)"
|
||||
|
||||
If enabled, an event concerning a snowmen/beamling will be loaded instantly
|
||||
|
||||
If disabled, snowmen/beamlings will be queued just like other vehicles
|
||||
|
||||
## **3. Set default Unicycle**
|
||||
|
||||
??? setting "Default Unicycle config"
|
||||
|
||||
This setpoint defines the unicycle variant to be loaded by default. You can choose between premade configs and your own should you have saved custom unicycle configs
|
||||
|
||||
??? setting "Automatically save your last used Unicycle"
|
||||
|
||||
If enabled, your last used unicycle will be automatically saved and reloaded once you spawn it again
|
||||
|
||||
If disabled, your default unicycle config will spawn every time
|
||||
|
||||
## **4. Blobs**
|
||||
|
||||
??? setting "Enable blobs for unspawned vehicles"
|
||||
|
||||
If enabled, you will see a placeholder orb, or blob, in place of an unspawned vehicle
|
||||
|
||||
If disabled, an unspawned vehicle will be invisible
|
||||
|
||||
??? setting "Tune colors"
|
||||
|
||||
??? setting "Visible"
|
||||
|
||||
If enabled, a blob will be drawn, using the color below
|
||||
|
||||
If disabled, no blob will be drawn for the specified function
|
||||
|
||||
??? setting "RGB HEX values"
|
||||
|
||||
Queued vehicle: The color a blob will use if a vehicle is queued for spawning. Standard value #FF6400
|
||||
|
||||
Illegal vehicle: The color a blob will use if a vehicle is illegal, for example trough a mod that was sideloaded. Standard value #000000
|
||||
|
||||
Deleted vehicle: The color a blob will use if a vehicle was deleted by the user. Standard value #333333
|
||||
|
||||
## **5. Nametags**
|
||||
|
||||
??? setting "Hide player nametags"
|
||||
|
||||
If enabled, player nametags will not be drawn
|
||||
|
||||
If disabled, player nametags will be drawn according to their vehicles relative position
|
||||
|
||||
??? setting "Show distance from other players"
|
||||
|
||||
If enabled, the nametag will be prepended by the distance to the respective vehicle
|
||||
|
||||
If disabled, no additional distance will be shown in the nametag
|
||||
|
||||
??? setting "Fade nametags in/out"
|
||||
|
||||
If enabled, a nametag will be faded in/out according to `Fade distance` and `Invert nametag fade direction`
|
||||
|
||||
If disabled, anametag will be drawn at standard opacity regardless of distance to the respective vehicle
|
||||
|
||||
??? setting "Fade distance/Invert nametag fade direction"
|
||||
|
||||
::: setting "Fade out"
|
||||
|
||||
Nametags are getting less visible the further away a player is
|
||||
|
||||
`Fade distance` defines the distance at which a nametag will be drawn at minimal opacity
|
||||
|
||||
::: setting "Fade in"
|
||||
|
||||
Nametags are getting more visible the further away a player is
|
||||
|
||||
`Fade distance` defines the distance at which a nametag will be drawn at maximal opacity
|
||||
|
||||
??? setting "Don't fully hide nametags"
|
||||
|
||||
If enabled, a nametag can not get fully invisible, it will retain a minimal opacity regardless of distance
|
||||
|
||||
If disabled, nametags can get fully invisble
|
||||
|
||||
??? setting "Shorten nametag and role tags"
|
||||
|
||||
If enabled, `Nametag length limit` will truncate nametags and roles to the set limit of characters
|
||||
|
||||
If disabled, nametag and role tags will be shown at full length
|
||||
|
||||
??? setting "Show spectators' nametag under vehicle nametags"
|
||||
|
||||
If enabled, a spectators name will be added underneath a players nametag
|
||||
|
||||
If disabled, no spectator names will be added to nametags
|
||||
|
||||
??? setting "Same color for spectator nametags"
|
||||
|
||||
If enabled, a spectators name will always be surrounded by a grey background
|
||||
|
||||
If disabled, a spectators name will be surrounded by a colored background, reflecting the spectators role
|
||||
|
||||
## **6. Others**
|
||||
|
||||
??? setting "Show network activity in the console"
|
||||
|
||||
If enabled, the beamMP network activity will be shown in the console
|
||||
|
||||
If disabled, no further network activity will be shown in the console
|
||||
|
||||
::: danger ""
|
||||
|
||||
Be careful with this setting, since all the console output gets also written into the log files
|
||||
|
||||
They can grow by hundreds of MB in minutes with this setting enabled
|
||||
|
||||
??? setting "Launcher port"
|
||||
|
||||
This setpoint defines the port used for communicating with the launcher
|
||||
|
||||
Should only be changed if the standard port 4444 can not be used
|
||||
|
||||
Dont forget to also change it on the launcher side, by modifying `launcher.cfg`
|
||||
|
||||
::: tip ""
|
||||
|
||||
The port specified is only the first of two, the second port being used is directly following, set port + 1
|
||||
|
||||
The first port carries core network pakets, the second game network pakets, both over TCP
|
||||
+5
-5
@@ -11,7 +11,7 @@ hero:
|
||||
actions:
|
||||
- theme: brand
|
||||
text: Get Started
|
||||
link: /en/game/getting-started
|
||||
link: /en/get-started/index
|
||||
- theme: alt
|
||||
text: View on GitHub
|
||||
link: https://github.com/beammp/docs
|
||||
@@ -20,19 +20,19 @@ features:
|
||||
- icon: 🎮
|
||||
title: For Players
|
||||
details: Learn how to install BeamMP, connect to servers, and get the most out of your multiplayer experience
|
||||
link: /en/game/getting-started
|
||||
link: /en/players/gameplay-basics
|
||||
- icon: 🖥️
|
||||
title: For Server Owners
|
||||
details: Set up and manage your own BeamMP server with our comprehensive guides and troubleshooting resources
|
||||
link: /en/server/create-a-server
|
||||
link: /en/server-owners/host-a-server
|
||||
- icon: 💻
|
||||
title: For Developers
|
||||
details: Create mods, resources, and UI apps with detailed API documentation and code examples
|
||||
link: /en/guides/index
|
||||
link: /en/developers/index
|
||||
- icon: ❓
|
||||
title: FAQ
|
||||
details: Find quick answers to common questions about setup, troubleshooting, and best practices
|
||||
link: /en/FAQ/player-faq
|
||||
link: /en/troubleshooting/index
|
||||
- icon: 📋
|
||||
title: Community Rules
|
||||
details: Learn about our community guidelines and how to report issues or appeal decisions
|
||||
|
||||
@@ -0,0 +1,25 @@
|
||||
# Players FAQ
|
||||
|
||||
## How do I link my Discord account?
|
||||
Linking your Discord and BeamMP account is a new feature to BeamMP. To do this go to your [Forum Account Preferences](https://forum.beammp.com/my/preferences/account) and connect your Discord account under "Associated Accounts" (this is only visible when 2FA for the forum is disabled).
|
||||
|
||||
## How do I get early access?
|
||||
|
||||
Early access (including the purple nametag and other benefits) can be obtained by supporting us financially on [Patreon](https://patreon.com/BeamMP) 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.
|
||||
|
||||
## I subscribed on Patreon. How do I get my perks?
|
||||
|
||||
Please ensure you do the following to automatically receive your perks:
|
||||
|
||||
1. Link your Discord account on [Patreon](https://www.patreon.com/settings/apps/discord) to receive the Roles and Access in the Discord server.
|
||||
2. Please ensure you use the same email address on Patreon as you do for your BeamMP account on the [Forum](https://forum.beammp.com/).
|
||||
|
||||
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.
|
||||
|
||||
## I have more questions!
|
||||
|
||||
If your question or issue relates to the Game or playing please refer to the [Game FAQs](game-faq.md).
|
||||
If your question or issue relates to running a Server please refer to the [Server FAQs](server-faq.md).
|
||||
Otherwise please check out the [forums](https://forum.beammp.com/c/faq/35) where the community can ask questions and get answers.
|
||||
@@ -0,0 +1,179 @@
|
||||
# Getting Started
|
||||
|
||||
## **1. Compatibility**
|
||||
|
||||
BeamMP is fully compatible with Windows and Linux, compatibility with MacOS is being worked on.
|
||||
However, both Linux and MacOS are secondary platforms, this means bugs are to be expected.
|
||||
|
||||
::: warning
|
||||
BeamMP will not work with pirated or outdated versions of BeamNG.drive.
|
||||
The BeamMP support team does not offer support for issues with pirated / outdated copies.
|
||||
:::
|
||||
---
|
||||
|
||||
## **2. Installation**
|
||||
|
||||
### **2a. Windows Installation**
|
||||
|
||||
::: note
|
||||
As of April 1st, 2026, the MSI installer is an "unrecognized app" according to Windows Defender SmartScreen.
|
||||
|
||||
To bypass this warning, click 'More info', then click 'Run anyway'.
|
||||
:::
|
||||
|
||||
1. Go to [beammp.com](https://beammp.com/) and click the 'Download Now' button.
|
||||
2. Run the `BeamMP_Installer.msi` installer and follow the instructions.
|
||||
3. The BeamMP Launcher icon should appear on your desktop. If not, just search for “BeamMP” in the Windows search bar.
|
||||
|
||||
::: note
|
||||
As you are loading into a map with multiple vehicles spawned it might take longer than expected to join.
|
||||
:::
|
||||
|
||||
### **2b. Linux Installation**
|
||||
|
||||
Currently you need to build the Launcher yourself.
|
||||
In order to do this, you need a basic understanding of how to build an application.
|
||||
|
||||
Make sure you have basic development tools installed, often found in packages, for example:
|
||||
|
||||
- Debian/Ubuntu: `sudo apt install build-essential`
|
||||
- Fedora: `sudo dnf install cmake gcc gcc-c++ make perl perl-IPC-Cmd perl-FindBin perl-File-Compare perl-File-Copy kernel-headers kernel-devel`
|
||||
- Arch: `sudo pacman -S base-devel`
|
||||
- openSUSE: `zypper in -t pattern devel-basis`
|
||||
- SteamOS (Arch): `sudo pacman -S base-devel linux-api-headers glibc libconfig` (You also need to do `sudo steamos-readonly disable` but make sure to enable it again after installing the packages)
|
||||
|
||||
|
||||
Clone `vcpkg`, bootstrap it and add it to PATH
|
||||
|
||||
1.
|
||||
```bash
|
||||
git clone https://github.com/microsoft/vcpkg.git
|
||||
```
|
||||
|
||||
2.
|
||||
```bash
|
||||
./vcpkg/bootstrap-vcpkg.sh
|
||||
```
|
||||
|
||||
3.
|
||||
```bash
|
||||
export VCPKG_ROOT="$(pwd)/vcpkg"
|
||||
export PATH=$VCPKG_ROOT:$PATH
|
||||
```
|
||||
|
||||
|
||||
Clone the BeamMP-Launcher Repository to your system using `git`, for example:
|
||||
`git clone https://github.com/BeamMP/BeamMP-Launcher.git`
|
||||
[Additional information about cloning a GitHub Repo](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
|
||||
|
||||
If you've used the example clone command we provided, you can use `cd BeamMP-Launcher` to go to the project's root directory.
|
||||
|
||||
Checkout the tag that was used for the [latest release](https://github.com/BeamMP/BeamMP-Launcher/releases/latest). For example, if `v2.8.0` is used in the latest release, then do `git checkout v2.8.0`
|
||||
|
||||
In the root directory of the project,
|
||||
|
||||
1.
|
||||
```cmake
|
||||
cmake . -B bin -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-linux
|
||||
```
|
||||
|
||||
2.
|
||||
```cmake
|
||||
cmake --build bin --parallel
|
||||
```
|
||||
|
||||
::: note
|
||||
Should you run out of RAM while building, you can ommit the --parallel instruction, it will then use less RAM due to building only on one CPU thread.
|
||||
:::
|
||||
|
||||
:::note ""
|
||||
By not specifying `-DCMAKE_BUILD_TYPE=Release` you are building a debug version, which is larger in filesize but does not contain the launcher-can-only-connect-to-a-server-once bug
|
||||
:::
|
||||
|
||||
:::note Fedora Users
|
||||
If vcpkg fails during OpenSSL compilation with kernel headers errors, ensure all dependencies are installed:
|
||||
```bash
|
||||
sudo dnf install kernel-headers kernel-devel gcc gcc-c++ make perl
|
||||
```
|
||||
Then clean the vcpkg cache:
|
||||
```bash
|
||||
rm -rf $VCPKG_ROOT/buildtrees/openssl
|
||||
```
|
||||
And retry the cmake configuration command.
|
||||
:::
|
||||
|
||||
Move the finished application out of the `/bin` folder into its own folder and run it from there:
|
||||
```bash
|
||||
mkdir -p ~/beammp-launcher
|
||||
cp bin/BeamMP-Launcher ~/beammp-launcher/
|
||||
cd ~/beammp-launcher
|
||||
./BeamMP-Launcher
|
||||
```
|
||||
|
||||
The native Linux BeamMP-Launcher will start and use native Linux BeamNG.drive
|
||||
|
||||
### **2c. Using beamNG.drive with Proton**
|
||||
|
||||
Should you want to use the native linux BeamMP-Launcher together with BeamNG.drive running through Proton, you can do so:
|
||||
|
||||
Run the BeamMP-Launcher using the argument ` --no-launch` (This will prevent the Launcher from starting native linux BeamNG.drive). Further information about launcher arguments can be found in the [Development Environment Setup](../developers/dev-environment-setup.md)
|
||||
|
||||
Change the userfolder location of Proton-BeamNG.drive to the location of Linux-BeamNG.drive (since the native linux BeamMP-Launcher currently only writes into the Linux-BeamNG.drive userfolder)
|
||||
|
||||
This can be done for example by creating a symlink
|
||||
|
||||
- Note the Linux-BeamNG.drive userfolder location (this is usually found in `~/.local/share/BeamNG.drive`) and rename it, for example to `BeamNG.drive_old`
|
||||
- Note the Proton-BeamNG.drive userfolder location (this is usually found in `~/.local/share/Steam/steamapps/compatdata/284160/pfx/drive_c/users/steamuser/AppData/Local/BeamNG.drive`)
|
||||
- Create a symlink between both userfolders `ln -s ~/.local/share/Steam/steamapps/compatdata/284160/pfx/drive_c/users/steamuser/AppData/Local/BeamNG.drive ~/.local/share`
|
||||
|
||||
With the symlink in place between the userfolders and the launcher compiled, you can have Steam run the game via Proton, while also automatically executing the launcher with the following replacement for your launch options for the vanilla game, found in the game's Properties window in its entry in Steam:
|
||||
|
||||
- `~/BeamMP/BeamMP-Launcher --no-launch & %command% ; killall BeamMP-Launcher`
|
||||
|
||||
Note that this assumes you put the launcher's binary you compiled earlier into `/home/user/BeamMP/`, so change it to match where you put the finished binary, and you will need to re-compile the launcher with the correct git branch each time a launcher update is released.
|
||||
|
||||
::: tip "Adding an emoji-font to get in-text emojis"
|
||||
In order to get emojis to show up in either the serverlist (As part of a servers customised name) or in the ingame chat, you need to have a font that contains emojis.
|
||||
|
||||
This can be done for example by adding the [Linux-port of the Windows Segoe-UI emoji font](https://github.com/mrbvrz/segoe-ui-linux)
|
||||
:::
|
||||
|
||||
### **2d. Updating the Launcher**
|
||||
|
||||
If you already built the launcher and want to update it:
|
||||
|
||||
```bash
|
||||
export VCPKG_ROOT="$(pwd)/vcpkg"
|
||||
cd BeamMP-Launcher
|
||||
git fetch --tags
|
||||
```
|
||||
Checkout the tag that was used for the [latest release](https://github.com/BeamMP/BeamMP-Launcher/releases/latest). For example, if `v2.8.0` is used in the latest release, then do `git checkout v2.8.0`
|
||||
```
|
||||
cmake . -B bin -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-linux
|
||||
cmake --build bin --parallel
|
||||
cp bin/BeamMP-Launcher ~/beammp-launcher/
|
||||
cd ~/beammp-launcher
|
||||
./BeamMP-Launcher
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
||||
## **3. Using BeamMP**
|
||||
|
||||
1. Once you have started the launcher, you should see a terminal window. Shortly after, the standard BeamNG launcher should start. **Do not** close the terminal window.
|
||||
2. In the BeamNG.drive main menu, click the `Repository` button and check to make sure that `multiplayerbeammp` is **the only** enabled mod.
|
||||
3. Return to the main menu, click on 'More..' and the 'Multiplayer' button to start multiplayer.
|
||||
4. You will be prompted to login or play as a guest (not all servers will allow guests). You can create an account on our [forum](https://forum.beammp.com) and then login to BeamMP with the same credentials.
|
||||
5. Select any server you like, and press `Connect`. Enjoy!
|
||||
|
||||
---
|
||||
|
||||
## **4. Known Issues**
|
||||
|
||||
- The native linux BeamMP-Launcher currently can only connect to a server once, after disconnecting you need to restart the launcher. You can do that without closing the game inbetween
|
||||
- If you don’t see the “Multiplayer” button. Make sure that the BeamMP mod is present and activated in the “Mod Manager” then try pressing CTRL + L.
|
||||
- VPNs of any type may cause connection issues.
|
||||
- If the Launcher reports any errors, read the [FAQ](https://forum.beammp.com/c/faq/35).
|
||||
|
||||
Should you need further help with installation, you are welcome to create a post on our [forum](https://forum.beammp.com) or ask on our [Discord server](https://discord.gg/beammp).
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: Players
|
||||
description: Player-focused BeamMP guides and FAQs
|
||||
---
|
||||
|
||||
# Players
|
||||
|
||||
If you're playing BeamMP, start here.
|
||||
|
||||
## Quick Links
|
||||
- [Gameplay Basics](./gameplay-basics.md)
|
||||
- [Multiplayer Settings](./multiplayer-settings.md)
|
||||
- [Player FAQ](./faq.md)
|
||||
- [Mod Safety](./mod-safety.md)
|
||||
@@ -0,0 +1,42 @@
|
||||
## Why do I have to deactivate/remove my mods?
|
||||
|
||||
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.
|
||||
|
||||
### 1. Deactivate mods
|
||||
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.
|
||||
|
||||
### 2. Creating a new Userfolder
|
||||
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.
|
||||
|
||||
|
||||
::: warning My settings and configs are gone! How can I restore them?
|
||||
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.
|
||||
|
||||
### 3. Cleaning up the BeamMP-Launcher cache.
|
||||
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.
|
||||
|
||||
### 4. Removing mods from the content folders.
|
||||
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.
|
||||
:::
|
||||
@@ -0,0 +1,254 @@
|
||||
# Mutliplayer Settings
|
||||
|
||||
## **1. General**
|
||||
|
||||
::: setting "Show advanced options"
|
||||
If enabled, you will see all multiplayer settings
|
||||
If disabled, you will see only basic multiplayer settings
|
||||
:::
|
||||
|
||||
??? setting "Enable config cloning protection"
|
||||
|
||||
If enabled, your spawned vehicle config will be protected from other players saving it
|
||||
|
||||
If disabled, your spawned vehicle config can be saved by other players
|
||||
|
||||
??? setting "Disable pausing caused by instabilities"
|
||||
|
||||
If enabled, physics instabilities will not cause your game to pause
|
||||
|
||||
If disabled, physics instabilities will cause your game to pause
|
||||
|
||||
::: note ""
|
||||
|
||||
Its advised to leave disabled, since repeated instabilities can cause the game to crash
|
||||
|
||||
??? setting "Use simplified vehicles when available"
|
||||
|
||||
If enabled, the game will replace vehicles of other players with their simplified versions (from AI traffic) if available
|
||||
|
||||
If disabled, the game will use the intended vehicle models
|
||||
|
||||
??? setting "New chat menu"
|
||||
|
||||
If enabled, the ingame chat will be displayed in an [IMGUI](https://github.com/ocornut/imgui) window, that for example can be dragged out of the game onto another monitor
|
||||
|
||||
If disabled, the ingame chat will be displayed in the UI app
|
||||
|
||||
::: note ""
|
||||
|
||||
Dragging IMGUI windows out of the main game window can cause performance issues, as well as trick screen recording software into recording the chat window instead of the main game window
|
||||
|
||||
??? setting "Enable vehicle position smoothing"
|
||||
|
||||
If enabled, beamMP will use an algorithm to smooth vehicle position updates to regular intervalls. Can be beneficial between players with high ping or when a connection experiences a high package drop rate
|
||||
|
||||
If disabled, beamMP will update vehicle locations as they are received
|
||||
|
||||
??? setting "Skip the mod security warning popusp"
|
||||
|
||||
If enabled, the mod security popup will not be shown when trying to connect to a server with mods
|
||||
|
||||
If disabled, the mod security popup will be shown whenever you connect to a server with mods
|
||||
|
||||
??? setting "Enable player vehicle update/edit queuing"
|
||||
|
||||
If enabled, other players vehicle spawns and edits will be put into a queue. See the section `2. Event queue` for further details
|
||||
|
||||
If disabled, other players vehicle spawns and edits will be loaded by the game instantly
|
||||
|
||||
??? setting "Enable automatic part sync"
|
||||
|
||||
If enabled, your vehicles parts will automatically be synced to other players after a few seconds
|
||||
|
||||
If disbaled, you need to click the part sync button in the part picker in order to send a sync out to other players
|
||||
|
||||
??? setting "Disable switching to other players vehicles"
|
||||
|
||||
If enabled, tabbing trough vehicles will skip other players vehicles
|
||||
|
||||
If disabled, tabbing trough vehicles will cycle over every spawned vehicle
|
||||
|
||||
??? setting "Fade out vehicles as they get closer"
|
||||
|
||||
If enabled, other vehicles will fade out as they get closer
|
||||
|
||||
If disbaled, other vehicles will stay fully visible regardless of distance
|
||||
|
||||
::: note ""
|
||||
|
||||
This only affects the visible 3d mesh of a vehicle, not its physics node-beam-mesh. In order to also disable physics, you need to enable `Simplified collision physics` in the Gameplay settings
|
||||
|
||||
??? setting "Show the player ID`s"
|
||||
|
||||
If enabled, the ingame playerlist will have an additional row showing each players ID. Useful for development or moderation
|
||||
|
||||
If disabled, the ingame playerlist will only show the rows for playername and ping
|
||||
|
||||
??? setting "Allow the serverlist to refresh ingame"
|
||||
|
||||
If enabled, the serverlist will update in regular intervalls while playing. This can cause lag spikes
|
||||
|
||||
If disabled, the serverlist will only update once you open the main menu
|
||||
|
||||
## **2. Event queue**
|
||||
|
||||
??? setting "Highlight queued players"
|
||||
|
||||
If enabled, players with a queued event will be highlighted in the ingame playerlist
|
||||
|
||||
If disabled, players will not be individually highlighted
|
||||
|
||||
??? setting "Apply vehicle changes with"
|
||||
|
||||
If set to `Left mouse button`, clicking on a players name in the playerlist using the left mouse button will load the queued events. Clicking with the right mouse button will spectate said player
|
||||
|
||||
If set to `Right mouse button`, clicking on a players name in the playerlist using the right mouse button will load the queued events. Clicking with the left mouse button will spectate said player
|
||||
|
||||
??? setting "Automatically apply queued vehicle changes"
|
||||
|
||||
If enabled, the queued events will be automatically loaded once you've been going under the speed treshold for the amount of time set as the timeout
|
||||
|
||||
If disabled, the queued events will only load manually, by clicking on either the `Events` button at the top of the screen or on a players name in the playerlist
|
||||
|
||||
??? setting "Queue apply speed treshold"
|
||||
|
||||
This setpoint defines the speed treshold of the automatic event queue loading. Your vehicle has to be slower than this for longer than `Queue apply timeout` in order to load the queued events
|
||||
|
||||
??? setting "Queue apply timeout"
|
||||
|
||||
This setpoint defines the time delay of the automatic event queue loading. Your vehicle has to be slower than `Queue apply speed treshold` for this time in order to load the queued events
|
||||
|
||||
??? setting "Skip queue if spectating others"
|
||||
|
||||
If enabled, an event will instantly load if you are spectating another player
|
||||
|
||||
If disabled, an event will be queued just like it would when focused on your own vehicle
|
||||
|
||||
??? setting "Don't queue Unicycles (Snowmen/Beamlings)"
|
||||
|
||||
If enabled, an event concerning a snowmen/beamling will be loaded instantly
|
||||
|
||||
If disabled, snowmen/beamlings will be queued just like other vehicles
|
||||
|
||||
## **3. Set default Unicycle**
|
||||
|
||||
??? setting "Default Unicycle config"
|
||||
|
||||
This setpoint defines the unicycle variant to be loaded by default. You can choose between premade configs and your own should you have saved custom unicycle configs
|
||||
|
||||
??? setting "Automatically save your last used Unicycle"
|
||||
|
||||
If enabled, your last used unicycle will be automatically saved and reloaded once you spawn it again
|
||||
|
||||
If disabled, your default unicycle config will spawn every time
|
||||
|
||||
## **4. Blobs**
|
||||
|
||||
??? setting "Enable blobs for unspawned vehicles"
|
||||
|
||||
If enabled, you will see a placeholder orb, or blob, in place of an unspawned vehicle
|
||||
|
||||
If disabled, an unspawned vehicle will be invisible
|
||||
|
||||
??? setting "Tune colors"
|
||||
|
||||
??? setting "Visible"
|
||||
|
||||
If enabled, a blob will be drawn, using the color below
|
||||
|
||||
If disabled, no blob will be drawn for the specified function
|
||||
|
||||
??? setting "RGB HEX values"
|
||||
|
||||
Queued vehicle: The color a blob will use if a vehicle is queued for spawning. Standard value #FF6400
|
||||
|
||||
Illegal vehicle: The color a blob will use if a vehicle is illegal, for example trough a mod that was sideloaded. Standard value #000000
|
||||
|
||||
Deleted vehicle: The color a blob will use if a vehicle was deleted by the user. Standard value #333333
|
||||
|
||||
## **5. Nametags**
|
||||
|
||||
??? setting "Hide player nametags"
|
||||
|
||||
If enabled, player nametags will not be drawn
|
||||
|
||||
If disabled, player nametags will be drawn according to their vehicles relative position
|
||||
|
||||
??? setting "Show distance from other players"
|
||||
|
||||
If enabled, the nametag will be prepended by the distance to the respective vehicle
|
||||
|
||||
If disabled, no additional distance will be shown in the nametag
|
||||
|
||||
??? setting "Fade nametags in/out"
|
||||
|
||||
If enabled, a nametag will be faded in/out according to `Fade distance` and `Invert nametag fade direction`
|
||||
|
||||
If disabled, anametag will be drawn at standard opacity regardless of distance to the respective vehicle
|
||||
|
||||
??? setting "Fade distance/Invert nametag fade direction"
|
||||
|
||||
::: setting "Fade out"
|
||||
|
||||
Nametags are getting less visible the further away a player is
|
||||
|
||||
`Fade distance` defines the distance at which a nametag will be drawn at minimal opacity
|
||||
|
||||
::: setting "Fade in"
|
||||
|
||||
Nametags are getting more visible the further away a player is
|
||||
|
||||
`Fade distance` defines the distance at which a nametag will be drawn at maximal opacity
|
||||
|
||||
??? setting "Don't fully hide nametags"
|
||||
|
||||
If enabled, a nametag can not get fully invisible, it will retain a minimal opacity regardless of distance
|
||||
|
||||
If disabled, nametags can get fully invisble
|
||||
|
||||
??? setting "Shorten nametag and role tags"
|
||||
|
||||
If enabled, `Nametag length limit` will truncate nametags and roles to the set limit of characters
|
||||
|
||||
If disabled, nametag and role tags will be shown at full length
|
||||
|
||||
??? setting "Show spectators' nametag under vehicle nametags"
|
||||
|
||||
If enabled, a spectators name will be added underneath a players nametag
|
||||
|
||||
If disabled, no spectator names will be added to nametags
|
||||
|
||||
??? setting "Same color for spectator nametags"
|
||||
|
||||
If enabled, a spectators name will always be surrounded by a grey background
|
||||
|
||||
If disabled, a spectators name will be surrounded by a colored background, reflecting the spectators role
|
||||
|
||||
## **6. Others**
|
||||
|
||||
??? setting "Show network activity in the console"
|
||||
|
||||
If enabled, the beamMP network activity will be shown in the console
|
||||
|
||||
If disabled, no further network activity will be shown in the console
|
||||
|
||||
::: danger ""
|
||||
|
||||
Be careful with this setting, since all the console output gets also written into the log files
|
||||
|
||||
They can grow by hundreds of MB in minutes with this setting enabled
|
||||
|
||||
??? setting "Launcher port"
|
||||
|
||||
This setpoint defines the port used for communicating with the launcher
|
||||
|
||||
Should only be changed if the standard port 4444 can not be used
|
||||
|
||||
Dont forget to also change it on the launcher side, by modifying `launcher.cfg`
|
||||
|
||||
::: tip ""
|
||||
|
||||
The port specified is only the first of two, the second port being used is directly following, set port + 1
|
||||
|
||||
The first port carries core network pakets, the second game network pakets, both over TCP
|
||||
@@ -0,0 +1,40 @@
|
||||
How to check for CGNAT?
|
||||
## Issue
|
||||
|
||||
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/create-a-server/#partnered-hosting-services-paid) (Server setup documentation).
|
||||
|
||||
# What even is CGNAT?
|
||||
|
||||
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](https://en.wikipedia.org/wiki/Carrier-grade_NAT).
|
||||
|
||||
# How to check for CGNAT?
|
||||
|
||||
## Method 1:
|
||||
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``
|
||||
|
||||
## Method 2:
|
||||
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.
|
||||
|
||||
## Method 3/Solution:
|
||||
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
|
||||
@@ -0,0 +1,22 @@
|
||||
# Error Codes
|
||||
|
||||
This page contains all the error codes that the server may display.
|
||||
|
||||
---
|
||||
|
||||
| Code | Description | Possible solution |
|
||||
|-------|--------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
|
||||
| 10022 | There is an issue with binding to the port | Check if the port for the server is already in use by another service, if it is use another one. |
|
||||
| 10048 | Address already in use | Another BeamMP server or program is running on that port, use another one. |
|
||||
| 10051 | Network unreachable | Bad port forwarding or similar issues, verify that it is all set up correctly. |
|
||||
| 10052 | Network reset | Happens if the network drops connection while a connection is being established. Retry the connection. |
|
||||
| 10053 | Connection aborted | Caused by timeout or network error, retry the connection. |
|
||||
| 10054 | Connection reset by peer | A client has disconnected from your server. |
|
||||
| 10060 | Connection timed out | There is an issue with your port forwarding, please refer to the [guide steps](create-a-server.md#1-port-forwarding). |
|
||||
| 10061 | Connection refused | There is an issue with your port forwarding, please refer to the [guide steps](create-a-server.md#1-port-forwarding). |
|
||||
| 10064 | Host down | Unlikely error, but it means that the host is down because either it's shutdown or ports were closed. |
|
||||
| 10065 | Host not reachable | No internet or bad port forwarding, please refer to the [guide steps](create-a-server.md#1-port-forwarding). |
|
||||
|
||||
::: note
|
||||
For any other code not in this list, you can refer to <https://learn.microsoft.com/en-us/windows/win32/winsock/windows-sockets-error-codes-2> if you know a bit how networks / sockets work.
|
||||
|
||||
@@ -0,0 +1,83 @@
|
||||
# F.A.Q. and Known Issues
|
||||
List of commonly asked questions and known bugs.
|
||||
|
||||
---
|
||||
## **Server**
|
||||
|
||||
---
|
||||
### **How can I setup my own servers**
|
||||
|
||||
All the information to set up your own server can be found [here](https://docs.beammp.com/server/create-a-server/).
|
||||
|
||||
---
|
||||
### **Can you make a server using linux?**
|
||||
|
||||
We provide binaries for many Linux distributions [here](https://github.com/BeamMP/BeamMP-Server/releases/latest).
|
||||
If there are no binaries for your Operating System/Distribution, you can build it yourself by downloading the source on our [GitHub](https://github.com/BeamMP/BeamMP-Server), a tutorial can be found [here](https://github.com/BeamMP/BeamMP-Server#build-instructions).
|
||||
|
||||
---
|
||||
### **What are the minimum system requirements to run a BeamMP server?**
|
||||
|
||||
- RAM: 50+ MiB usable (not counting OS overhead)
|
||||
- CPU: >1GHz, preferably multicore
|
||||
- OS: Windows, Linux (theoretically any POSIX)
|
||||
- GPU: None
|
||||
- HDD: 10 MiB + Mods/Plugins
|
||||
- Bandwidth: 5-10 Mb/s upload
|
||||
|
||||
---
|
||||
## **Players outside my network can not join my self-hosted server**
|
||||
|
||||
Read the port forwarding guide that's available [here](https://docs.beammp.com/server/port-forwarding/). 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:
|
||||
|
||||
- Forward port 30814 (or whichever port you set in your ServerConfig.toml), both TCP and UDP protocols.
|
||||
- Allow BeamMP through the Windows Firewall, allow both incoming and outgoing connections. Turning off the firewall will usually NOT work.
|
||||
- Make sure you're not using a VPN (this can cause issues).
|
||||
- Make sure the server is actually running, without any errors or warnings.
|
||||
|
||||
You can check if you have successfully portforwarded using CheckBeamMP whilst the server is running.
|
||||
|
||||
<form action="https://check.beammp.com/api/v2/beammp" method="get" target="_blank">
|
||||
<label for="ip">IP adress:</label>
|
||||
<input type="text" id="ip" name="ip"><br>
|
||||
<label for="port">Port:</label>
|
||||
<input type="text" id="port" name="port"><br>
|
||||
<input type="submit" value="CheckBeamMP">
|
||||
</form>
|
||||
|
||||
Notes:
|
||||
|
||||
- Some internet providers do not offer dedicated IPv4 addresses to your connection (CGNAT), so port forwarding may not be possible, despite it being available in the router.
|
||||
- Port forwarding is not possible if you are using a mobile (4G/5G) internet connection.
|
||||
|
||||
---
|
||||
### **I can see my self-hosted server in the server-list, but i cannot join it myself**
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
## **Miscellaneous**
|
||||
|
||||
---
|
||||
### **Where can I find the code?**
|
||||
|
||||
All the source code can be found on our [GitHub](https://github.com/BeamMP).
|
||||
Before doing anything keep in mind that the code is subject to our [Terms of Use](https://forum.beammp.com/t/terms-of-use-v1-0/43) and licenses:
|
||||
|
||||
| Code | License |
|
||||
|------------|:--------------------------------------------------------------------------:|
|
||||
| Server | [LICENSE](https://github.com/BeamMP/BeamMP-Server/blob/master/LICENSE) |
|
||||
| Launcher | [LICENSE](https://github.com/BeamMP/BeamMP-Launcher/blob/master/README.md) |
|
||||
| Client Lua | [LICENSE](https://github.com/BeamMP/BeamMP/blob/development/LICENSE.md) |
|
||||
|
||||
---
|
||||
### **I have found a bug or an exploit what should I do?**
|
||||
|
||||
If the issue is code related and you know how to use Github, create a new "Issue" in the appropriate repository on our [GitHub](https://github.com/BeamMP). 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](https://github.com/BeamMP/BeamMP/blob/development/CONTRIBUTING.md).
|
||||
|
||||
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 it is not something sensitive, you can create a post on our [BeamMP Forum](https://forum.beammp.com) or you can report this on our [Official Discord](https://discord.gg/beammp).
|
||||
- If the information is sensitive you can directly report the issue to a Staff member on our [Discord](https://discord.gg/beammp).
|
||||
@@ -0,0 +1,296 @@
|
||||
# Server Installation
|
||||
|
||||
## **Creating a Server**
|
||||
Basics of setting up the server application
|
||||
|
||||
---
|
||||
### **Overview**
|
||||
|
||||
**Creating a Home Server is free, hosting one with a VPS is easier and more secure**
|
||||
|
||||
Servers are an integral part of BeamMP; players are connected to each other through the server. They run natively on Windows and Linux.
|
||||
|
||||
You can make private servers, which only people you invite can join, or public servers, which will show in our official server list.
|
||||
|
||||
Getting a server up and running is a process of a few steps! If you run into any issues, feel free to ask on our [Forum](https://forum.beammp.com) or on our [Discord server](https://discord.gg/beammp) in the `#support` channel. Also refer to the [Server Maintenance](server-maintenance.md) section for more info.
|
||||
|
||||
Please make sure to read the [LICENSE](https://raw.githubusercontent.com/BeamMP/BeamMP-Server/master/LICENSE) of the server before use.
|
||||
|
||||
Note: _The server only supports IPv4\. If you don't know which one you have, look at the IP address you see on [_whatsmyip.org_](https://www.whatsmyip.org/) - if it contains_ `_:_` _colons, it's **IPv6**. In that case, you should investigate further whether you also have an IPv4\. You can call your ISP to find this out, or ask someone who lives with you (if they're tech-savvy, they might know!). IPv6 support is planned._
|
||||
|
||||
## Setting up the Server
|
||||
|
||||
The setup consists of the following steps, you should follow all of them.
|
||||
|
||||
### **1. Port forwarding**
|
||||
|
||||
::: info
|
||||
|
||||
If you are on a VPS (Virtual Private Server), Rootserver, or plan on hosting this server locally (with players in the same house as you), you can skip this step.
|
||||
This step is necessary if you want someone **outside** of your household to join your home-hosted server (outside of your local network).
|
||||
|
||||
::: danger ":material-scale-balance: DISCLAIMER:"
|
||||
|
||||
**Port forwarding is a risk**.
|
||||
|
||||
By port forwarding, you understand the risks of 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.
|
||||
|
||||
It is therefore recommended to host a server with one of our partnered services!
|
||||
|
||||
*Please see [this guide on how to port forward](port-forwarding.md)*
|
||||
|
||||
#### Partnered Hosting Services (paid):
|
||||
|
||||
* [Horizon Hosting](https://hrzn.link/beammp)
|
||||
* [RackGenius](https://rackgeni.us/beammp-plans)
|
||||
* [Connect Hosting](https://connecthosting.net/beammp)
|
||||
* [Assetto Hosting](https://assettohosting.com/en/games/beamng)
|
||||
* [ZAP-Hosting](https://zap-hosting.com/itsbeammp)
|
||||
* [HostHavoc](https://hosthavoc.com/)
|
||||
* [PedalHost](https://pedal.host/)
|
||||
* [Vyper Hosting](https://vyperhosting.com/r/beammp)
|
||||
* [BisectHosting](https://www.bisecthosting.com/beammp-server-hosting)
|
||||
* [Four Seasons Hosting](https://fourseasonshosting.com)
|
||||
* [Vertuo Hosting](https://vertuohosting.com)
|
||||
* [Winheberg](https://winheberg.fr/offres/gaming/beammp?lang=en)
|
||||
* [Wabbanode](https://wabbanode.com/partner/beammp)
|
||||
* [Iceline Hosting](https://iceline-hosting.com/games/beammp)
|
||||
|
||||
|
||||
#### 1.1 Firewall
|
||||
|
||||
Depending on your setup, you may need to let BeamMP-Server through your firewall. This is the case on Windows (turning the firewall off usually does **not** work), and on a lot of preinstalled Linux servers.
|
||||
|
||||
There you want to allow the BeamMP-Server through the firewall, **both incoming and outgoing connections**, and **both TCP and UDP**. If your firewall asks for a port instead, that will have to be the same port you used in step “1\. Port Forwarding” (usually 30814).
|
||||
|
||||
For a more detailed guide, refer to [this documentation page](https://docs.beammp.com/FAQ/Defender-exclusions/).
|
||||
If you have issues, also feel free to ask on our [Forum](https://forum.beammp.com) or on our [Discord server](https://discord.gg/beammp) in the `#support` channel.
|
||||
|
||||
### **2. Obtaining an Authentication Key**
|
||||
|
||||
The “Authentication Key”, often called “AuthKey”, is necessary for making a **public** server accessible by the serverlist. Though it is recommended to add the authkey to private servers as well.
|
||||
You have a limited number of keys. One key can be used on one server at a time, so you cannot start two servers at the same time with the same key.
|
||||
More keys can be obtained by supporting the project. Read [this article](https://docs.beammp.com/support/player-faq/) for more information.
|
||||
|
||||
::: warning
|
||||
|
||||
DO NOT EVER SHARE THIS KEY OR SHOW IT TO ANYONE. TREAT THIS LIKE A PASSWORD.
|
||||
|
||||
You will need a [Discord](https://discord.com) account for this step. This is necessary to prevent spam.
|
||||
|
||||
#### 2.1. Accessing the keys page
|
||||
|
||||
Login with Discord to the [Keymaster](https://keymaster.beammp.com).
|
||||
From the Keymaster homepage click on "Keys" on the left of the screen:
|
||||
|
||||
<figure markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
#### 2.2. Creating a key
|
||||
|
||||
To create your key, click on the green "+" button in the top right.
|
||||
|
||||
<figure markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
#### 2.3. Filling out the key information
|
||||
|
||||
Next, fill out the Server Name field (this is just the keys name and not the actual name of the server on the list), then click "Create". Example:
|
||||
|
||||
<figure class="image image_resized" style="width:44.84%;" markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
It should, in the end, look something like this:
|
||||
|
||||
<figure markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
#### 2.4. Copying the key
|
||||
|
||||
Now copy the text in the “Key” field, in this example that is `3173a2e-6az0-4542-a3p0-ddqq5ff95558` and hold onto it for the next step. You can do this by clicking the clipboard on the right of the key:
|
||||
|
||||
<figure markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
### **3. Installation**
|
||||
|
||||
The BeamMP-Server is available for Windows and Linux. The next two sections are dedicated to Windows and Linux each.
|
||||
|
||||
#### 3.a. Installation on Windows
|
||||
|
||||
For the Linux installation, see the next step.
|
||||
|
||||
Please ensure you have port-forwarded before attempting to host a server at home! Without you ports being forwarded, you cannot host a server to the public!
|
||||
|
||||
1. Ensure you have installed the [Visual C++ Redistributables](https://aka.ms/vs/17/release/vc_redist.x64.exe) in order to run the server.
|
||||
2. Download the server executable from [beammp.com](https://www.beammp.com/). You should end up with an executable file, called something like `BeamMP-Server.exe`.
|
||||
3. Once downloaded, make a folder somewhere and put the `BeamMP-Server.exe` there. This is where your server will live.
|
||||
4. Start the server once by double-clicking on it. This will generate all the necessary files for you, once you see text you can close it and proceed to the next step. You should see a `ServerConfig.toml` file next to your `BeamMP-Server.exe`.
|
||||
5. (optional) For quick access in the future you can easily create a desktop shortcut to `BeamMP-Server.exe` using **[Right click]** > **Send to** > **Desktop (create shortcut).**
|
||||
|
||||
Now proceed to step [4. Configuration](#4-configuration).
|
||||
|
||||
#### 3.b. Installation on Linux
|
||||
|
||||
##### Using our build (recommended)
|
||||
|
||||
This step will work on all distributions we provide binaries for [here](https://github.com/BeamMP/BeamMP-Server/releases/latest). If you're on a different distribution or architecture, refer to the "Building from source” step below.
|
||||
|
||||
1. Ensure you have the dependencies installed which are listed [here](https://github.com/BeamMP/BeamMP-Server#runtime-dependencies).
|
||||
2. Go to [beammp.com](https://beammp.com/) and click the “Download Server” button, you will be redirected to the server's Github release page.
|
||||
3. Download the correct version for your distro. For sake of semplicity it will be called `BeamMP-Server-xxx` from now on, where `xxx` denotes the version for the distro you're using.
|
||||
4. Once downloaded, you should see one file called `BeamMP-Server-xxx`, among others which you can ignore for now. Make a folder somewhere and put the `BeamMP-Server-xxx` there. This is where your server will live.
|
||||
5. Open a terminal, go to that folder you put the `BeamMP-Server-xxx` in, and run `chmod +x BeamMP-Server-xxx`. This ensures that you have permissions to run it.
|
||||
6. Start the server once by running it with `./BeamMP-Server-xxx`. This will generate all the necessary files for you, once you see text you can close it and proceed to the next step. You should see a `ServerConfig.toml` file next to your `BeamMP-Server-xxx`.
|
||||
7. (optional) It is heavily recommended to set up a user called `beammpserver` (or similar), as we do NOT recommend running the server as root, sudo or with your personal user account. You should then take steps to make sure that you start the server as this user only.
|
||||
|
||||
Now proceed to step "4\. Configuration".
|
||||
|
||||
##### Building from source
|
||||
|
||||
Other distributions in addition to the ones that already have a binary [here](https://github.com/BeamMP/BeamMP-Server/releases/latest) are likely to work too, but aren't officially supported. If you want to build it yourself you can do it by downloading the source on our [GitHub](https://github.com/BeamMP/BeamMP-Server), a tutorial can be found [here](https://github.com/BeamMP/BeamMP-Server#build-instructions).
|
||||
|
||||
At the end, make sure to run your server once with `./BeamMP-Server` and then proceed to the next step.
|
||||
|
||||
### **4. Configuration**
|
||||
|
||||
Now that you ran the server once, it should have created some files and probably uttered an error or two. This is because we are not yet done. Your folder should have these files:
|
||||
|
||||
<figure markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
They are called “ServerConfig.toml”, “Server.log” and “BeamMP-Server.exe”! (Depending on your settings, you might not see the [.toml] [.log] [.exe] extentions)
|
||||
|
||||
Open the `ServerConfig.toml` with a text editor such as `Notepad`. You can do this with [Right Click] → “Open With…” and then selecting a text editor.
|
||||
|
||||
Here is an example configuration:
|
||||
|
||||
```TOML
|
||||
[General]
|
||||
Port = 30814
|
||||
AuthKey = "auth-key"
|
||||
AllowGuests = false
|
||||
LogChat = false
|
||||
Debug = false
|
||||
IP = "::"
|
||||
Private = true
|
||||
InformationPacket = true
|
||||
Name = "Test Server"
|
||||
Tags = "Freeroam,Modded,Racing,Police"
|
||||
MaxCars = 2
|
||||
MaxPlayers = 10
|
||||
Map = "/levels/ks_nord/info.json"
|
||||
Description = "Total Random Beam MP Server"
|
||||
ResourceFolder = "Resources"
|
||||
```
|
||||
|
||||
::: info
|
||||
|
||||
This is your configuration file. It uses a format called TOML. Refer to the [Server Maintenance](server-maintenance.md) section for more info on this file and the variables.
|
||||
Your server will **NOT** show in the server list as long as `Private = true`. _If_ you want it to show in the list, set that to **`Private = false`**.
|
||||
|
||||
For now, we only care about the `AuthKey` field. Between the quotes `''`, you want to paste in your AuthKey you copied in the first step.
|
||||
|
||||
For our example key, it should then look like this:
|
||||
```TOML
|
||||
AuthKey = '3173a2e-6az0-4542-a3p0-ddqq5ff95558'
|
||||
```
|
||||
Give your server a name, too, in the `Name` field. You can format this with colors and more, please refer to [this section on Name customization](server-maintenance.md#customize-the-look-of-your-server-name) in the server maintenance page.
|
||||
|
||||
If you picked a different **Port** other than **30814**, make sure to replace it here under `Port`.
|
||||
|
||||
### **5. Validation**
|
||||
|
||||
Now run your server again, and see if it spits out any more `[ERROR]` or `[WARN]` messages. The server should stay open now. In the following steps (6.) below you can find out how to join the server.
|
||||
|
||||
---
|
||||
|
||||
#### 5.1 How to add mods to your server
|
||||
|
||||
Vehicle mods and map mods are different to install, but both require you to put them in your server's (`Resources/Client`) folder. Simply slide any mod you want to add in that folder.
|
||||
|
||||
::: warning
|
||||
|
||||
Should you receive a "done" or "start" message when trying to join your server after adding mods, you likely added an incompatible or broken mod to your server.
|
||||
Mod incompatibilities can also occur between 2 or more mods. If you have client mods installed, check [this guide](../../FAQ/How-to-deactivate-mods.md) about removing mods from your game.
|
||||
|
||||
#### 5.2 General Mods
|
||||
|
||||
If you only wanted to add modded vehicles, you simply put the zip file of the mod in the `Resources/Client` folder. They will automatically be downloaded by anyone who joins your server.
|
||||
|
||||
#### 5.3 Maps
|
||||
|
||||
All default maps (maps which aren't mods) work out-of-the-box and do not have to be installed. You simply change the `Map` setting in the `ServerConfig.toml` file to any of [these](server-maintenance.md#all-vanilla-maps-names). For any other modded maps, do this:
|
||||
|
||||
1. Put your map's `.zip` file in your server's (`Resources/Client`) folder.
|
||||
2. Next, have a look inside the map's zip file (don't extract it) and open the `levels` folder. In this folder there should be simply one other folder with the name of the map, for example “myawesomedriftmap2021”. Make sure to copy or remember this name _exactly as it is written in that folder's name._
|
||||
3. Open your `ServerConfig.toml`. In the `Map` setting, you should see `/levels/MAPNAME/info.json`, where `MAPNAME` is likely something like `gridmap_v2`. You want to now replace this `MAPNAME` with the name of the folder from the last step, in that example it was `myawesomedriftmap2021`. In the end it should look like this (for this example) and _**should**_ have `/info.json` at the end.
|
||||
|
||||
```TOML
|
||||
Map = '/levels/myawesomedriftmap2021/info.json'
|
||||
```
|
||||
|
||||
Now, when someone joins your server, it should download the map automatically and work as expected.
|
||||
|
||||
**If this does NOT work**, install the map in your singleplayer BeamNG.drive, launch it and enter the map. Then, open the Console by pressing the `~` (_tilde_) key (if you're on a non-US keyboard, look at the **Toggle System Console** action in the **Options > Controls > Bindings** menu, under the **General Debug** section), and run `print(getMissionFilename())`. This should then show you the name to use.
|
||||
|
||||
That's it! Your modded map should now be available to join!
|
||||
|
||||
### **6. How to join your server**
|
||||
|
||||
How you and other players can join your server.
|
||||
|
||||
#### 6.a. Joining your own server (both private and public)
|
||||
|
||||
If your server is hosted on the same PC as the game runs on, you must join your server by direct connecting, to do this, click the **Direct Connect Tab** on the left from the server list. Leave the default info in there (should be 127.0.0.1 and corresponding port) then hit connect.
|
||||
|
||||
If your server is hosted on another PC in your local network, you must find the local IP of that machine and direct connect using this local IP.
|
||||
|
||||
If your server is hosted outside of your house (e.g. VPS) you must find the [public IP](https://whatismyipaddress.com/) of that machine and direct connect that way.
|
||||
|
||||
#### 6.b. Other people joining your private server
|
||||
|
||||
You have to give other users the public IP Address of your Server. However, be careful sharing your public IP address with strangers! To join your private server the players must go to the **Direct Connect Tab** in BeamMP, then type your IP and Port.
|
||||
|
||||
#### 6.c. Other people joining your public server
|
||||
|
||||
To join your public server they can simply go to the server list, type the name of the server, and click connect. If you are unsure of what your server name is, it will be the name you put in the `ServerConfig.toml`.
|
||||
Make sure search filters are disabled and the Map set to "Any" if you can't find it.
|
||||
You can also check the [Keymaster](https://keymaster.beammp.com/) Website for the Servers IP Address.
|
||||
|
||||
Should you or your friends experience a "Connection Failed!" Error, check the Launcher Window for codes like 10060, 10061, 10030.
|
||||
This means you eihter have a CGNAT IPv4, or you have done something wrong during Step **1 Port Forwarding** or **1.1. Firewall**.
|
||||
To check if you have a CGNAT IPv4, look up the WAN IP Address on your routers interface. Compare it to your [public IP](https://www.whatsmyip.org/). If they're the same, you are not behind a CGNAT.
|
||||
IPv6 Support is **NOT** yet implemented.
|
||||
|
||||
### **7. How to check the connectivity of your BeamMP-Server**
|
||||
|
||||
Enter the servers public IPv4 and Port below, then click "CheckBeamMP".
|
||||
<form action="https://check.beammp.com/api/v2/beammp" method="get" target="_blank">
|
||||
<label for="ip">IP adress:</label>
|
||||
<input type="text" id="ip" name="ip"><br>
|
||||
<label for="port">Port:</label>
|
||||
<input type="text" id="port" name="port"><br>
|
||||
<input type="submit" value="CheckBeamMP">
|
||||
</form>
|
||||
|
||||
::: warning "I want to use a VPN such as RadminVPN, Hamachi, or similar."
|
||||
|
||||
BeamMP does not support these VPNs, as they often cause issues. One of these issues is UDP traffic not being forwarded. To resolve this, refer to section 1.
|
||||
|
||||
::: question "But why has it worked in the past?"
|
||||
|
||||
This is due to the developers of these applications updating their software and implementing changes which BeamMP has no control over.
|
||||
It is up to the developers of these applications to provide support for specific use cases like a BeamMP-Server.
|
||||
|
||||
## Still facing issues?
|
||||
|
||||
Open a Thread on the [Forum](https://forum.beammp.com) or on our [Discord server](https://discord.gg/beammp) in the `#support` channel.
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
title: Server Owners
|
||||
description: Hosting, networking, and server operations for BeamMP
|
||||
---
|
||||
|
||||
# Server Owners
|
||||
|
||||
Everything needed to host and maintain a BeamMP server.
|
||||
|
||||
## Quick Links
|
||||
- [Host a Server](./host-a-server.md)
|
||||
- [Port Forwarding](./port-forwarding.md)
|
||||
- [Check for CGNAT](./cgnat.md)
|
||||
- [Server Maintenance](./maintenance.md)
|
||||
- [Server FAQ](./faq.md)
|
||||
- [Server Error Codes](./error-codes.md)
|
||||
@@ -0,0 +1,237 @@
|
||||
# Server Maintenance
|
||||
|
||||
Guides, tips and tricks on how to configure and take care of a BeamMP Server.
|
||||
|
||||
## How to install
|
||||
|
||||
For installation instructions, please see [server installation](create-a-server.md).
|
||||
|
||||
## The ServerConfig file
|
||||
|
||||
The server config, which is a file called `ServerConfig.toml`, uses the [TOML format](https://toml.io/en/).
|
||||
|
||||
*NOTE*: The *old* server config file was called `Server.cfg`, but this is no longer used, and the server will warn when this is still present. Please also note that the two config formats are **not** compatible with each other.
|
||||
|
||||
The config has one section by default, called `[General]`, which holds the following values:
|
||||
|
||||
| Key | Value Type | Description |
|
||||
|-------------------|----------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| Port | 1024-65535 | The networking port on which the server will be reachable. (Must be unique and not be used by another service on the same host). |
|
||||
| AuthKey | AuthKey format `xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` where all x's are alphanumeric characters (numbers and letters) | Used to identify a public set server with the backend. |
|
||||
| AllowGuests | true/false | Determines wether guests are allowed to join the server or not. |
|
||||
| LogChat | true/false | When enabled (true), chat messages are logged in the server.log file. |
|
||||
| Debug | true /false | When enabled (true), will show more messages in the log and provide more information. Enable this if you run into issues. Enabling this will drastically increase the size of the log file. |
|
||||
| IP | A local class address of one of the NICs connected to the host. (Default: "0.0.0.0" or "::" | The server will try to bind to the supplied IP. Please do not mess with the IP field unless you know what you are doing. This value does not need to be changed in order for the server to work. |
|
||||
| Private | true/false | When enabled (true), your server will not be shown in the server list. Anyone with the correct IP and port can still connect. |
|
||||
| InformationPacket | true/false | When enabled (true), the server is going to allow unauthenticated clients to get the same info as on the server listing but directly via the server. |
|
||||
| Name | Any "text" | Shown as the name / title of your server in the server list. You can use special characters to format this with colors and styles. |
|
||||
| Tags | See list of allowed tags further below. | Tags for search e.g. Police, Racing etc... |
|
||||
| MaxCars | Any number ≥ 1 | The maximum number of cars per player. Any additional cars a player tries to spawn will be deleted instantly. |
|
||||
| MaxPlayers | Any Number ≥ 1 | The maximum amount of players per server. This does not affect vehicle count. |
|
||||
| Map | A valid map location, such as `/levels/gridmap_v2/info.json` | The map your server will host. Has to be installed either by default (a list can be found below) or as a server mod. |
|
||||
| Description | Any "text" | Shown as the description of the server in the server list (if the server is public). You can use special characters to format this with colors and styles. |
|
||||
| ResourceFolder | A valid folder location, such as "D:\Server\BeamMP\Resources" | Useful to store the server and the resource folder seperately. |
|
||||
| ImScaredOfUpdates | true/false | This sets the Server to either auto update or not when a new version is released. |
|
||||
| UpdateReminderTime| Any number with s, min, h, d appended. (30s) | Sets the interval of the update reminder message printed in the terminal.
|
||||
|
||||
|
||||
Other sections can and should be used by server plugins (Lua API coming soon), like so: `[MyMod]`.
|
||||
|
||||
The AuthKey **HAS** to be set by you. It will be empty by default, and needs to be filled with your AuthKey from the installation step earlier. Do not share this Key with anyone and, in screenshots, blur it fully.
|
||||
|
||||
### All vanilla maps names
|
||||
|
||||
Here are all the stock maps:
|
||||
|
||||
- /levels/gridmap_v2/info.json
|
||||
- /levels/johnson_valley/info.json
|
||||
- /levels/automation_test_track/info.json
|
||||
- /levels/east_coast_usa/info.json
|
||||
- /levels/hirochi_raceway/info.json
|
||||
- /levels/italy/info.json
|
||||
- /levels/jungle_rock_island/info.json
|
||||
- /levels/industrial/info.json
|
||||
- /levels/small_island/info.json
|
||||
- /levels/smallgrid/info.json
|
||||
- /levels/utah/info.json
|
||||
- /levels/west_coast_usa/info.json
|
||||
- /levels/driver_training/info.json
|
||||
- /levels/derby/info.json
|
||||
|
||||
### Customize the look of your server name
|
||||
|
||||
Use these special symbols before your text and it'll apply an effect to that text in the server list:
|
||||
|
||||
| Value | Description |
|
||||
|:-----:|-----------------------------|
|
||||
| `^r` | Reset |
|
||||
| `^p` | Newline (descriptions only) |
|
||||
| `^n` | Underline |
|
||||
| `^l` | Bold |
|
||||
| `^m` | Strike-through |
|
||||
| `^o` | Italic |
|
||||
| `^0` | Black |
|
||||
| `^1` | Blue |
|
||||
| `^2` | Green |
|
||||
| `^3` | Light blue |
|
||||
| `^4` | Red |
|
||||
| `^5` | Pink |
|
||||
| `^6` | Orange |
|
||||
| `^7` | Grey |
|
||||
| `^8` | Dark grey |
|
||||
| `^9` | Light purple |
|
||||
| `^a` | Light green |
|
||||
| `^b` | Light blue |
|
||||
| `^c` | Dark orange |
|
||||
| `^d` | Light pink |
|
||||
| `^e` | Yellow |
|
||||
| `^f` | White |
|
||||
|
||||
### Customize your server tags
|
||||
|
||||
Tags can be used to allow people to search for a specific type of server. Your serverConfig.toml will generate with the freeroam tag `Tags = "Freeroam"`.
|
||||
|
||||
You can add multiple tags separated by comma `Tags = "Events,Offroad,lang:english"`, they are not case sensitive.
|
||||
|
||||
You can choose from the following list:
|
||||
|
||||
- Age/Content:
|
||||
- `Mature/18+`
|
||||
|
||||
- Gameplay Types:
|
||||
- `Freeroam`
|
||||
- `Roleplay`
|
||||
- `Economy`
|
||||
- `Traffic`
|
||||
|
||||
- Racing Categories:
|
||||
- `Racing`
|
||||
- `Racing:NASCAR`
|
||||
- `Racing:Track`
|
||||
- `Racing:Drag`
|
||||
- `Racing:Rally`
|
||||
- `Touge`
|
||||
|
||||
- Off-Roading and Challenges:
|
||||
- `Offroad`
|
||||
- `Crawling`
|
||||
- `Dakar`
|
||||
- `Challenge`
|
||||
|
||||
- Destruction Events:
|
||||
- `Derby`
|
||||
- `Arena`
|
||||
|
||||
- Weather and Time Conditions:
|
||||
- `Snow/Ice`
|
||||
- `Rain`
|
||||
- `Night`
|
||||
- `Weather`
|
||||
|
||||
- Gamemodes:
|
||||
- `Gamemode`
|
||||
- `Gamemode:Racing`
|
||||
- `Gamemode:Rally`
|
||||
- `Gamemode:Drag`
|
||||
- `Gamemode:Derby`
|
||||
- `Gamemode:Infection`
|
||||
- `Gamemode:Cops-Robbers`
|
||||
- `Gamemode:Delivery`
|
||||
- `Gamemode:Sumo`
|
||||
|
||||
- Community and Events:
|
||||
- `Scenarios`
|
||||
- `Events`
|
||||
- `Leaderboard`
|
||||
|
||||
- Mods:
|
||||
- `Modded`
|
||||
- `Mod:BeamPaint`
|
||||
- `Mod:BeamJoy`
|
||||
- `Mod:CEI`
|
||||
|
||||
- Languages:
|
||||
- `Lang:English`
|
||||
- `Lang:Russian`
|
||||
- `Lang:French`
|
||||
- `Lang:Spanish`
|
||||
- `Lang:Portuguese`
|
||||
- `Lang:German`
|
||||
- `Lang:Polish`
|
||||
- `Lang:Arabic`
|
||||
|
||||
- Other:
|
||||
- `Vanilla`
|
||||
- `Moderated`
|
||||
|
||||
|
||||
Should a tag be missing from this list, you can submit a request for it to be added [here](https://forum.beammp.com/t/introducing-server-tags/1320081)
|
||||
|
||||
## The Server.log file
|
||||
|
||||
This file will be generated when the server runs. It's a mirror of the messages you see in the console when you run the server. You should attach this file every time you need support from our support staff, and it will never show your AuthKey, so you can usually send it without modifications.
|
||||
|
||||
The format is as follows ($ prefix means “variable”, explained below):
|
||||
|
||||
```
|
||||
[$DATE $TIME] $CONTEXT [$LOG_LEVEL] $MESSAGE
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
- `$DATE` is the date of the message, for example 21/07/2021
|
||||
- `$TIME` is the time of the message, for example 11:05:23
|
||||
- `$CONTEXT` (only visible if in Debug mode and mostly relevant to developers) is the context of the message, which is either:
|
||||
- `(Player ID) “Player Name”`, where the Player's ID is useful for moderation
|
||||
- A short name such as “HeartbeatThread”
|
||||
- `$LOG_LEVEL` is one of the levels of importance of a message:
|
||||
- `DEBUG`: Only visible in Debug mode, usually spammy and only important to developers
|
||||
- `INFO`: General information
|
||||
- `LUA`: Message from a Lua plugin
|
||||
- `WARN`: Describes something that isn't supposed to happen, usually
|
||||
- `ERROR`: Something went very wrong, or was very unexpected
|
||||
- `FATAL`: Something happened that causes the server to shut down
|
||||
- `$MESSAGE` the message itself, usually something that you should pay attention to and understand. In some cases this might be cryptic, but the general rule is that, as long as nothing is visibly wrong with the server and there are no ERRORs, all is good.
|
||||
|
||||
## Updating the server
|
||||
|
||||
### Why to update
|
||||
|
||||
Whenever a new update is released, you're advised to update your server. Usually this involves bug fixes, stability improvements and security improvements, next to the general new features etc. that are introduced.
|
||||
|
||||
To receive news about updates when they come out, either follow the discord server's “update” channel, look out for it on the forums, or look at / ask the [GitHub releases page](https://github.com/BeamMP/BeamMP-Server/releases).
|
||||
|
||||
### How to update
|
||||
|
||||
#### If you are using a BeamMP partnered hosting provider
|
||||
|
||||
If you are using a BeamMP partnered hosting provider, the instructions below likely won't work. We recommend waiting for more details from your hosting provider, or contacting them for assistance.
|
||||
|
||||
#### Managing the server yourself
|
||||
|
||||
The server is updated by replacing the old executable with the new one. If you are unsure how to do this, there are step-by-step instructions for Windows and Linux below.
|
||||
|
||||
If you built from source, you just rebuild. Make sure to run `git submodule update --init --recursive` before you rebuild.
|
||||
|
||||
#### On Windows
|
||||
|
||||
1. Ensure you have installed the [Visual C++ Redistributables](https://aka.ms/vs/17/release/vc_redist.x64.exe) in order to run the server.
|
||||
2. Go to [BeamMP.com](https://beammp.com/) and click the “Download Server” button.
|
||||
3. Once downloaded, you should see one file called `BeamMP-Server.exe`. We will call this one the “new executable”.
|
||||
4. Go to the folder where your current `BeamMP-Server.exe` executable is located (same folder where your `ServerConfig.toml` is, usually). We will call this one the “old executable”.
|
||||
5. Replace the old executable with the new executable (for example by copying or moving the new executable into the folder).
|
||||
|
||||
#### On Linux
|
||||
|
||||
1. Go to [BeamMP.com](https://beammp.com/) and click the “Download Server” button, you will be redirected to the server's Github release page.
|
||||
2. Download the correct version for your distro. For simplicity, it will now be called `BeamMP-Server-xxx` from now on, where `xxx` denotes the version for the distro you're using.
|
||||
3. Once downloaded, you should see one file called `BeamMP-Server-xxx` depending on the version you've downloaded. We will call this one the “new executable”.
|
||||
4. Go to the folder where your current `BeamMP-Server-xxx` executable is located (same folder where your `ServerConfig.toml` is, usually). We will call this one the “old executable”.
|
||||
5. Replace the old executable with the new executable (for example by copying or moving the new executable into the folder).
|
||||
6. Open a terminal in that folder where you just replaced the executable, and run `sudo chmod +x BeamMP-Server-xxx`. This will make sure the server can be run.
|
||||
|
||||
### Automated updates
|
||||
|
||||
The server does not support automatic updates or update notifications (yet).
|
||||
|
||||
You can, however, ask the GitHub API for the lastest release by checking the server's version against the tags. You can get that by GET'ing from `https://api.github.com/repos/BeamMP/BeamMP-Server/git/refs/tags`.
|
||||
@@ -0,0 +1,251 @@
|
||||
# Port Forwarding
|
||||
|
||||
::: danger ":material-scale-balance: DISCLAIMER:"
|
||||
|
||||
**Port forwarding is a risk**.
|
||||
|
||||
By Port forwarding you understand the risks of 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.
|
||||
|
||||
<u>**If you do not understand this guide, please consider using one of our partners.**</u>
|
||||
|
||||
::: warning
|
||||
|
||||
Please make sure your Router is not a 4G/5G exclusive device. If it is a hybrid device, make sure to select the cable connected adapter later in section 3 of this guide!
|
||||
|
||||
## How to set up port forwarding.
|
||||
|
||||
Creating a port forwarding rule involves a few detailed network terms. Be prepared to write down a few notes as you go through the process.
|
||||
|
||||
There are 4 major steps in this guide.
|
||||
|
||||
## A quick guide. (A more detailed guide is below)
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :material-dns:{ .lg .middle } __Assign a static IP address to your computer or devices__
|
||||
|
||||
---
|
||||
This is needed to prevent the IP of your device changing and breaking the port forwarding rule.
|
||||
|
||||
|
||||
[:octicons-arrow-right-24: See info about your router](https://portforward.com/router.htm#1)
|
||||
|
||||
- :material-router-wireless:{ .lg .middle } __Log in to your router__
|
||||
|
||||
---
|
||||
|
||||
This can normally be done by finding the 'Default Gateway' IP, which can be found when executing `ipconfig` in a command prompt and entering it in a web browsers address bar.
|
||||
|
||||
- :material-lan-connect:{ .lg .middle } __Forward ports to your computer__
|
||||
|
||||
---
|
||||
|
||||
Find the port forwarding section in your routers web interface. Most routers list the port forwarding section under Network, Advanced, or LAN.
|
||||
|
||||
- :material-test-tube:{ .lg .middle } __Test that your port is forwarded properly__
|
||||
|
||||
---
|
||||
|
||||
Use a tool such as CheckBeamMP to test if the rule is working.
|
||||
|
||||
<form action="https://check.beammp.com/api/v2/beammp" method="get" target="_blank">
|
||||
<label for="ip">IP address:</label>
|
||||
<input type="text" id="ip" name="ip"><br>
|
||||
<label for="port">Port:</label>
|
||||
<input type="text" id="port" name="port"><br>
|
||||
<input type="submit" value="CheckBeamMP">
|
||||
</form>
|
||||
|
||||
</div>
|
||||
|
||||
## The detailed guide
|
||||
|
||||
### 1. Assigning a static IP address
|
||||
|
||||
### Method 1: Set Up a Static IP Address Using DHCP reservations
|
||||
|
||||
Another way to set a static IP address in your local network is to use your router's DHCP reservation feature. Not all routers have this feature, so this may not be an option for you. Please search the internet with the model of your router to find a manual.
|
||||
|
||||
If you have managed to do this, please skip directly to [step 2](port-forwarding.md#2-log-in-to-your-router)
|
||||
|
||||
### Method 2: Assign a static IP in Windows
|
||||
|
||||
#### 1.1. Find your current IP Address, Gateway and DNS servers:
|
||||
|
||||
Before we can set up a static IP address, we need to know your current network settings.
|
||||
You are going to want to write these down, so get a notepad window ready.
|
||||
For this step, we are going to use command prompt.
|
||||
|
||||
Open up a command prompt. The 3 main ways are:
|
||||
|
||||
- Windows Key, then start typing the phrase "cmd", then press Enter when you see "Command Prompt" highlighted.
|
||||
|
||||
|
||||
<figure class="image image_resized" style="width:62%;" markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
Once you are in the command prompt, run the following command:
|
||||
|
||||
```
|
||||
ipconfig /all
|
||||
```
|
||||
|
||||
You will see a lot of data.
|
||||
If you have virtual or multiple network adapters, then you will see even more data.
|
||||
It is common to see many virtual adapters if you have either Hyper-V or Docker installed.
|
||||
|
||||
<figure class="image image_resized" style="width:62%;" markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
It is recommended to use a wired network connection which will be running this server, however, it will work over a wireless connection.
|
||||
You will need to look for an adapter in this list which has an active internet connection. Scroll through the list and find one that has a Default Gateway assigned.
|
||||
Many of the virtual adapters will not have a Default Gateway.
|
||||
|
||||
Below are local IPv4 address examples, which atleast one of the adapters should have.
|
||||
You will need to note down the information of your adapter.
|
||||
|
||||
- 192.168.x.x
|
||||
- 10.x.x.x.
|
||||
- 172.16.x.x - 172.31.x.x
|
||||
|
||||
Subnet Mask (most likely 255.255.255.0)
|
||||
</br>
|
||||
Default Gateway (most likely 192.168.0.1 or 192.168.1.1)
|
||||
|
||||
::: info "Please Note"
|
||||
BeamMP currently does not support IPv6 for hosting a server.
|
||||
|
||||
#### 1.2. Modify Adapter Settings
|
||||
|
||||
Now we need to change the settings on your network adapter in order for your PC to keep the IP configuration it currently has. To get to the settings for your network, the fastest method is:
|
||||
|
||||
- Single tap the Windows key
|
||||
- Type the phrase "network connections" until you see "View network connections".
|
||||
- Press the Enter key
|
||||
|
||||
|
||||
<figure class="image image_resized" style="width:62%;" markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
You should see a list of network connections on your computer.
|
||||
If you have Hyper-V or Docker installed, there can be many.
|
||||
Look for any adapters that are not named "Hyper-V".
|
||||
|
||||
<figure class="image image_resized" style="width:62%;" markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
|
||||
Right-click on your adapter and choose properties. If `Internet Protocol Version 4` is not checked, then this is the wrong adapter. Choose a different one.
|
||||
|
||||
<figure class="image image_resized" style="width:62%;" markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
Double click on `Internet Protocol Version 4`. Change `Obtain an IP address automatically` to `Use the following IP address`.
|
||||
|
||||
Fill out the IP address, Subnet mask, Default gateway, and Preferred DNS server with the information from command prompt (ipconfig /all).
|
||||
|
||||
Alternatively, instead of using your DNS servers, you can use either the CloudFlare or Google DNS servers:
|
||||
|
||||
- CloudFlare DNS: 1.1.1.1, 1.0.0.1
|
||||
- Google DNS: 8.8.8.8, 8.8.4.4
|
||||
|
||||
|
||||
<figure class="image image_resized" style="width:62%;" markdown>
|
||||
|
||||
</figure>
|
||||
|
||||
Click Ok, then click Ok again, and your adapter is now changed from DHCP to static. Surf the web to make sure that you still have internet connectivity. If you do not, then change your settings back to Obtain an IP address automatically and try the next method.
|
||||
|
||||
### 2. Log in to your router
|
||||
|
||||
Now that you have a static IP address on your device, you are ready to forward the port for BeamMP!
|
||||
|
||||
To start, we need to log in to your router. Earlier, one of the settings that you wrote down is your Default Gateway. That is the IP address of your router.
|
||||
|
||||
Most routers use a locally hosted web page for management. To view your router's menu and settings:
|
||||
|
||||
- Open up a web browser. Firefox, Chrome or Edge should work fine.
|
||||
- In the address bar, type your Default Gateway IP address, such as 192.168.0.1 or 192.168.1.1 and press enter
|
||||
|
||||
You should now see your router's login screen. Not all routers require a login, but most do. You need to know your router's username and password. If you have never logged in before, your username and password are most likely set to the factory default values or, in some cases, written on a sticker your router.
|
||||
|
||||
Some of the most common factory usernames and passwords are listed here:
|
||||
|
||||
| Username | Password |
|
||||
| ----------- | --------- |
|
||||
| admin | admin |
|
||||
| admin | password |
|
||||
| {blank} | admin |
|
||||
| {blank} | password |
|
||||
|
||||
Try various combinations of admin, password, and leaving the entries blank. *Where it says blank, try leaving the value blank.*
|
||||
|
||||
### 3. Create the forwarding rules!
|
||||
|
||||
#### 3.1. Find the forwarding section
|
||||
|
||||
Find the port forwarding section in your router web interface. Navigate around in your router by clicking the tabs or links at the top or left of each page. Most routers list the port forwarding section under Network, Advanced, or LAN. Look for the following keywords to help you find it:
|
||||
|
||||
- Port Forwarding
|
||||
- Forwarding
|
||||
- Port Range Forwarding
|
||||
- Virtual Servers
|
||||
- Apps & Gaming
|
||||
- Advanced Setup/Settings
|
||||
- NAT
|
||||
|
||||
#### 3.2. Enter in the details
|
||||
|
||||
Once you find your router's port forwarding section, you are ready to enter the necessary information.
|
||||
Your router will have a place to enter the ports to be forwarded and the destination IP address to point those forwarded ports. If your router lists both Internal and External ports, make them the same.
|
||||
|
||||
BeamMP requires both UDP and TCP port 30814 (Unless you have changed this in your [ServerConfig.toml](create-a-server.md#4-configuration)).
|
||||
|
||||
::: info "Note"
|
||||
While the default **Port** is **30814**, you can choose any other number greater than 1024 but less than 65535, but you need to note down what you picked if it's not 30814\. You need to forward both **TCP** and **UDP**.
|
||||
</br>
|
||||
It is recommended to stick to the default port as that one is very unlikely to be used by another service on your PC.
|
||||
</br>
|
||||
However, If you are hosting multiple servers on one machine, each server needs a different Port. Server 1: 30814, Server 2: 30815 for example.
|
||||
|
||||
On some routers you may need to create 2 rules, one for UDP and one for TCP, whilst others are nice and allow you to do both with a single rule!
|
||||
|
||||
Most routers have a 'save' button, and some routers require a restart or reboot for the changes to take effect.
|
||||
|
||||
### 4. Time to test!
|
||||
|
||||
There are a few different ways to test the connection.
|
||||
|
||||
Our recommend way is to use our tool **CheckBeamMP** as this tests for BeamMP specific issues and protocols.
|
||||
|
||||
<form action="https://check.beammp.com/api/v2/beammp" method="get" target="_blank">
|
||||
<label for="ip">IP address:</label>
|
||||
<input type="text" id="ip" name="ip"><br>
|
||||
<label for="port">Port:</label>
|
||||
<input type="text" id="port" name="port"><br>
|
||||
<input type="submit" value="CheckBeamMP">
|
||||
</form>
|
||||
|
||||
This can be done by getting your public IPv4 Address, this once again can be done in a few different ways. The main way is to use a website called [whatsmyip.org](https://whatsmyip.org/). This is a simple website which displays your public IP Address. You should be looking for an IP address with the formatting: xxx.xxx.xxx.xxx
|
||||
|
||||
Visit the following Link and replace "IP" with your actual IPv4 address, and the "Port" with your servers port. Be sure to leave no spaces.
|
||||
https://check.beammp.com/api/v2/beammp/ip/port
|
||||
|
||||
::: success "status: ok"
|
||||
|
||||
If you get the output above you can now join your server!
|
||||
There are 2 ways to join, either directly with the details you entered into Probably UP, or, if your server is set to 'public', through the server-list.
|
||||
Since you are hosting a server on-premise, use 127.0.0.1 (localhost) if the Server is running on the same PC as you play, or the LAN IPv4 of the local machine that is running the server.
|
||||
|
||||
::: failure "status: error"
|
||||
|
||||
If the connection fails entirely, your ISP could be using CGNAT (Carrier Grade Network Address Translation). For more details, please check [How to check for CGNAT?](./cgnat.md),
|
||||
or open a Server Support ticket on our [Discord server](https://discord.gg/beammp) in the `#support` channel and one of our staff will get to your ticket!
|
||||
Should you only see TCP working and UDP failing, check Firewall and Port forwarding rules again.
|
||||
@@ -0,0 +1,26 @@
|
||||
# How can I find the IP of my Server?
|
||||
|
||||
## For VPS Hosted Servers
|
||||
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](https://keymaster.beammp.com/login) Website.
|
||||
|
||||
## For Home-Hosted Servers
|
||||
For Servers hosted at home, open [whatsmyip.org](https://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](https://docs.beammp.com/server/port-forwarding/) as well as CheckBeamMP
|
||||
|
||||
<form action="https://check.beammp.com/api/v2/beammp" method="get" target="_blank">
|
||||
<label for="ip">IP adress:</label>
|
||||
<input type="text" id="ip" name="ip"><br>
|
||||
<label for="port">Port:</label>
|
||||
<input type="text" id="port" name="port"><br>
|
||||
<input type="submit" value="CheckBeamMP">
|
||||
</form>
|
||||
|
||||
## How to check for CGNAT?
|
||||
Have a look at [this page](https://docs.beammp.com/FAQ/How-to-check-for-CGNAT/) to determine wether you can host a server at home or not.
|
||||
|
||||
|
||||
Tags: IP, Server, Connection Failed, 10060/10061
|
||||
@@ -0,0 +1,50 @@
|
||||
# How to create exclusions in the Windows Defender Firewall and Antivirus?
|
||||
|
||||
::: 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).
|
||||
|
||||
::: danger ":material-scale-balance: 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.
|
||||
|
||||
## 1. Defender Firewall exclusion for the BeamMP-Launcher.
|
||||
|
||||
1. Open the `Windows Defender Firewall with advanced setting`.
|
||||
2. In the Window, click `Inbound` to open the inbound exclusions tab.
|
||||
3. Click `Create new rule` in the top right to create a new exclusion.
|
||||
4. Select `Program` to create a program specific exclusion.
|
||||
5. Enter the full qualified path towards the `BeamMP-Launcher.exe`. The default would be `%appdata%\BeamMP-Launcher\BeamMP-Launcher.exe` (without quotes).
|
||||
6. Make sure to allow the connection
|
||||
7. Give the exclusion a name (e.g. "BeamMP-Launcher") and save it.
|
||||
9. Restart your PC.
|
||||
|
||||
## 1.1 Defender Firewwall exclusion for the BeamMP-Server.
|
||||
|
||||
1. Open the `Windows Defender Firewall with advanced setting`.
|
||||
2. In the Window, click `Inbound` to open the inbound exclusions tab.
|
||||
3. Click `Create new rule` in the top right to create a new exclusion.
|
||||
4. Select `Port` to create a program specific exclusion.
|
||||
5. Enter the same port as in the ServerConfig.toml.
|
||||
6. Enter the full qualified path towards the `BeamMP-Server.exe`. The file is located whereever you placed it after downloading it.
|
||||
7. Make sure to allow the connection
|
||||
8. Give the exclusion a name (e.g. "BeamMP-Server") and save it.
|
||||
9. Restart your PC.
|
||||
|
||||
## 2. Defender Antivirus exclsuion for the BeamMP-Launcher/Server.
|
||||
|
||||
1. Open the `Windows Security` app.
|
||||
2. Click the first item `virus and threat protection`.
|
||||
3. Click `Manage settings` beneath "Virus & threat protection settings".
|
||||
4. Scroll down to navigate to the `Exclusions` tab.
|
||||
5. There, click 'Add an exclusion' and select `process`.
|
||||
6. Enter `BeamMP-Launcher.exe` or `BeamMP-Server.exe`into the field and save it.
|
||||
7. Restart your PC.
|
||||
|
||||
## Still facing issues?
|
||||
|
||||
Open a Thread on the [Forum](https://forum.beammp.com) or on our [Discord server](https://discord.gg/beammp) in the `#support` channel.
|
||||
@@ -0,0 +1,22 @@
|
||||
# Error Codes
|
||||
|
||||
This page contains all the error codes that the server may display.
|
||||
|
||||
---
|
||||
|
||||
| Code | Description | Possible solution |
|
||||
|-------|--------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
|
||||
| 10022 | There is an issue with binding to the port | Check if the port for the server is already in use by another service, if it is use another one. |
|
||||
| 10048 | Address already in use | Another BeamMP server or program is running on that port, use another one. |
|
||||
| 10051 | Network unreachable | Bad port forwarding or similar issues, verify that it is all set up correctly. |
|
||||
| 10052 | Network reset | Happens if the network drops connection while a connection is being established. Retry the connection. |
|
||||
| 10053 | Connection aborted | Caused by timeout or network error, retry the connection. |
|
||||
| 10054 | Connection reset by peer | A client has disconnected from your server. |
|
||||
| 10060 | Connection timed out | There is an issue with your port forwarding, please refer to the [guide steps](create-a-server.md#1-port-forwarding). |
|
||||
| 10061 | Connection refused | There is an issue with your port forwarding, please refer to the [guide steps](create-a-server.md#1-port-forwarding). |
|
||||
| 10064 | Host down | Unlikely error, but it means that the host is down because either it's shutdown or ports were closed. |
|
||||
| 10065 | Host not reachable | No internet or bad port forwarding, please refer to the [guide steps](create-a-server.md#1-port-forwarding). |
|
||||
|
||||
::: note
|
||||
For any other code not in this list, you can refer to <https://learn.microsoft.com/en-us/windows/win32/winsock/windows-sockets-error-codes-2> if you know a bit how networks / sockets work.
|
||||
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: Troubleshooting
|
||||
description: Common BeamMP issues and how to resolve them
|
||||
---
|
||||
|
||||
# Troubleshooting
|
||||
|
||||
## Common Issues
|
||||
- [Launcher Update Issues](./launcher-update.md)
|
||||
- [Connection / Networking](./connection-networking.md)
|
||||
- [Defender Exclusions](./defender-exclusions.md)
|
||||
- [Error Codes](./error-codes.md)
|
||||
@@ -0,0 +1,20 @@
|
||||
# Issue
|
||||
|
||||
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](https://beammp.com) before continuing.
|
||||
|
||||
# Downloading and installing a new Launcher
|
||||
|
||||
1. Download the latest Launcher from [GitHub](https://github.com/BeamMP/BeamMP-Launcher/releases/latest/download/BeamMP-Launcher.exe) directly.
|
||||
2. Head to the BeamMP-Launcher.exe directory. By default, this folder is placed in ```C:\Users\<username>\AppData\Roaming\``` . Replace <username> with the username of your windows user.
|
||||
If you have installed BeamMP elsewhere, for example ```D:\BeamMP-Launcher```, then place the Launcher in the respective BeamMP-Launcher folder.
|
||||
4. If applicable, replace the existing Launcher with the new one in the BeamMP-Launcher folder.
|
||||
5. Start the BeamMP-Launcher as usual to see if it works.
|
||||
|
||||
## Still facing issue?
|
||||
Create a support ticket on our [Discord Server](https://discord.gg/BeamMP).
|
||||
Tags: Launcher, download,
|
||||
Reference in New Issue
Block a user