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.
The rank rule
Section titled “The rank rule”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.
The actions
Section titled “The actions”| 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.
Bans work on people who are not here
Section titled “Bans work on people who are not here”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.
Acting on everyone at once
Section titled “Acting on everyone at once”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.
The whitelist
Section titled “The whitelist”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.
Vote-kicks
Section titled “Vote-kicks”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 cancelThe 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.
Staff passwords
Section titled “Staff passwords”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:
bj staffpassword your-password-herebj ownerpassword your-password-hereA 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.
Moving someone between groups
Section titled “Moving someone between groups”From chat, with SetGroup:
/setgroup PlayerName modFrom the console, where no permission applies:
bj group PlayerName modLeave 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.
What gets recorded
Section titled “What gets recorded”| 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.
- Groups and permissions — the six groups and what each may do.
- Chat and console commands — every command, with its usage line.
- The config window, tab by tab — where the whitelist and voting settings are.
- Permission reference — every key, one line each.