Skip to content

Players and moderation

Every moderation action in BeamJoy is in two places: the Players tab of the main window, and chat commands. They do the same things and obey the same rules. This page is those rules.

One rule governs everything on this page, and it is the one that surprises people:

So mute, kick, ban, temp ban, unban and group changes each need three things at once: you are staff, you hold the permission, and your group outranks theirs. Fail any of the three and you get “You don’t have enough permissions”. The teleports are the exception — they check their permission and nothing else, so a moderator can summon an admin.

The server console is outside all of it. A command typed there is not a player and has no group, so it can act on anybody — which is why ownership is claimed from the console and why it is the way back in if you lock yourself out.

Action Permission Default group What it does
Mute / Unmute Mute mod Stops them using chat. Takes an optional reason, which is kept and shown as the previous mute reason next time.
Kick Kick mod Drops them from the server. They can come straight back. The reason is stored on their record.
Ban Ban admin Permanent until lifted. Clears any temp ban.
Tempban TempBan mod Banned until a moment in the future. Clears any permanent ban.
Unban Ban admin Lifts either. Works by exact name on someone who is not here.
Promote / Demote SetGroup mod Moves them one group up or down the hierarchy.
Freeze / Unfreeze staff (see below) — Their car cannot move. Per car, or all of someone’s at once.
Stop engine / Start engine staff (see below) — Cuts or restores the engine.
Remove staff — Deletes a car. Queue deleted vehicles to respawn puts them back.
Explode / Launch staff — What they sound like.
Summon TeleportFrom mod Brings a player to you. No rank check.
Teleport to TeleportTo player Takes you to a player. Rate-limited, 30 seconds by default, and blocked mid-race.

Ban sits at admin, TeleportTo at player, and everything else in that list is mod by default. Every one of them can be moved — see Groups and permissions.

Freeze and engine are the odd ones. From the player list they need only that you are staff, and no permission of their own. From chat, /freeze and /engine additionally require FreezePlayers and EnginePlayers. If you want the chat commands restricted but the buttons open, that is already how it behaves.

Ban, temp ban and unban all look the player up in the database if they are not connected, so you can ban someone who left ten minutes ago and unban someone who has not been back for a month. The Database tab of the config window is the list to do it from, and it needs DatabasePlayers.

A temp ban is a moment in time, not a countdown that pauses: it expires whether the server is up or not, and the player’s own kick message tells them how long is left.

Durations. In the window the slider runs from two minutes to twelve months, with ±1m, 1h, 1d and 1M buttons either side of it. From chat the duration is plain seconds: /tempban PlayerName 3600 reason.

The Players tab carries bulk versions of four actions: Freeze all, Unfreeze all, Stop all engines, Start all engines and Remove all.

These act on every player ranked below you and skip the rest, which includes you. They set rather than toggle, so a server where half the cars are frozen ends up all frozen rather than inverted. You get a count back of how many players it actually touched.

Removing all vehicles skips AI traffic.

Off by default. When it is on, only whitelisted players get in — and a group can be whitelisted as a group, which is what vip is for on a shipped install.

It lives in Config → General → Whitelist, needs the Whitelist permission rather than SetConfig, and offers Add all connected players for the common case of locking a server down mid-session. Adding someone who is not connected needs their exact name — it is case sensitive.

The list is kept in its own file, separate from the rest of the config, and is re-read when it changes on disk, so it can be edited while the server runs. See where your data lives.

Starting one needs VoteKick, which is a player-group permission by default. Joining or cancelling a vote already running needs nothing, so the whole server can vote even where starting one has been moved up to staff.

/votekick PlayerName
/votekick join
/votekick cancel

The vote passes when enough of the eligible voters have joined it, where eligible means connected and not the person being voted on. The threshold is a percentage of that count, 51% by default, and the vote runs for 30 seconds. Both numbers are in Config → General → Voting.

A kick vote is visible to everyone, whether or not they may vote.

A server can hand out staff or owner rank by password, which is the way in when you cannot reach the console. Set them in the server console:

Terminal window
bj staffpassword your-password-here
Terminal window
bj ownerpassword your-password-here

A player then types /login your-password-here in chat and is moved into that group. Wrong passwords are rate-limited: too many in a row and they are told to wait a few minutes.

From chat, with SetGroup:

/setgroup PlayerName mod

From the console, where no permission applies:

Terminal window
bj group PlayerName mod

Leave the group off to read their current one back. Promote and Demote in the player list do the same thing one step at a time, and obey the rank rule — you cannot promote anybody to your own group or above.

Where What is kept
The player’s record Their group, whether they are muted and why, whether they are banned and why, the time a temp ban expires, and the last kick reason.
Database tab All of the above, for every player the server has seen, plus arbitrary key/value player data.
Chat Joins, leaves, mutes, kicks, bans and votes appear as event messages.
Discord Joins and leaves, and votes, if a webhook is set to carry them — see Discord integration.

Private messages sent with /pm are copied to staff. That is deliberate and players should be told, not discovered.