How to Configure Roles and Privileges on Your Vintage Story Server

Roles control what each player can do on your server. Every player gets a role when they join, and that role carries a set of privileges. Privileges decide who can build, who can fly, who can ban, and who can claim land.

Your Vintage Story server ships with nine roles out of the box. You can assign them, edit them, or build your own from scratch.

Default Roles

Code	Name	Privilege Level	What It Does
`suvisitor`	Survival Visitor	-1	Can look around and chat. Cannot build or interact.
`crvisitor`	Creative Visitor	-1	Can look around, chat, and fly. Cannot build or interact.
`limitedsuplayer`	Limited Survival Player	-1	Can build and interact. Cannot claim land.
`limitedcrplayer`	Limited Creative Player	-1	Same as above plus flight and game mode control.
`suplayer`	Survival Player	0	The default role. Can build, interact, and claim land.
`crplayer`	Creative Player	100	Survival Player plus flight and game mode control.
`sumod`	Survival Moderator	200	Can kick, ban, announce, and build inside claimed areas.
`crmod`	Creative Moderator	500	Survival Moderator plus flight, game mode, and player commands.
`admin`	Admin	99999	Every privilege, including granting admin to others.

Privilege Level

Privilege level ranks the role. A player can only act on players at a lower level, so a moderator cannot kick an admin.

Assigning a Role to a Player

1
Log in to Bropanel and select your Vintage Story server.
2
In the sidebar, go to Console.
3
Type /player Username role rolecode. For example, /player Steve role sumod.

To make someone an admin, use the shortcut /op Username. To demote a player, assign the standard player role with /player Username role suplayer. Swap in your own DefaultRoleCode if you changed it. Our adding admins guide covers this in more detail.

Tip

Run /list role to see every role on your server, and /list privileges to see every privilege.

Changing the Default Role for New Players

New players join with the role set in DefaultRoleCode. Change it to control what first-time visitors can do.

1
Log in to Bropanel and Stop your server.
2
In the sidebar, go to Files.
3
Open the data folder and edit serverconfig.json.
4
Find DefaultRoleCode and set it to the role code you want.
5
Save the file and Start your server.

Set it to suvisitor to hold new players in a read-only state until you promote them.

Granting and Revoking Privileges

You can change privileges on a whole role or on a single player.

To change a role, which affects every player in it:

1
Log in to Bropanel and select your Vintage Story server.
2
In the sidebar, go to Console.
3
Type /role rolename privilege grant privilegename to add a privilege.
4
Type /role rolename privilege revoke privilegename to remove one.

To change one player without touching their role:

1
In the sidebar, go to Console.
2
Type /player Username privilege grant privilegename to add a privilege.
3
Type /player Username privilege revoke privilegename to remove one.

Note

Player privileges stack on top of the role. Use them for one-off exceptions and use roles for everything else.

Available Privileges

Privilege	Description
`announce`	Send server-wide announcements.
`areamodify`	Claim and manage land areas.
`attackcreatures`	Attack creatures.
`attackplayers`	Attack other players.
`ban`	Ban and unban players.
`build`	Place and break blocks in unprotected areas.
`buildblockseverywhere`	Place and break blocks inside claimed areas.
`chat`	Send messages in chat.
`commandplayer`	Run commands that target other players.
`controlplayergroups`	Join and leave player groups.
`controlserver`	Change server settings and stop the server.
`freemove`	Fly and move through blocks.
`gamemode`	Change game mode.
`give`	Spawn items and blocks.
`grantrevoke`	Grant and revoke privileges.
`kick`	Kick players from the server.
`manageotherplayergroups`	Manage groups owned by other players.
`manageplayergroups`	Create and manage their own player groups.
`pickingrange`	Use an extended block reach distance.
`readlists`	View server lists such as clients, bans, and roles.
`root`	Full access that bypasses privilege checks.
`selfkill`	Use the `/kill` command on themselves.
`setspawn`	Set the world spawn point.
`setwelcome`	Set the welcome message.
`time`	Change world time and time speed.
`tp`	Teleport.
`useblock`	Interact with blocks in unprotected areas.
`useblockseverywhere`	Interact with blocks inside claimed areas.
`whitelist`	Manage the whitelist.

Role Settings

Each role in serverconfig.json uses the settings below.

Setting	Description
`Code`	The role ID used in commands. Must be unique.
`Name`	The role name shown in game.
`Description`	A short explanation of the role shown in game.
`PrivilegeLevel`	The rank of the role. Higher levels outrank lower ones.
`Privileges`	The list of privileges granted to the role.
`RuntimePrivileges`	Privileges granted at runtime and not saved to the config.
`DefaultSpawn`	A spawn point for the role that replaces the world spawn.
`ForcedSpawn`	A spawn point that overrides every other spawn type.
`DefaultGameMode`	The starting game mode. 0 is Guest, 1 is Survival, 2 is Creative, 3 is Spectator.
`Color`	The color of the player name in chat.
`LandClaimAllowance`	Total volume in cubic meters each player may claim.
`LandClaimMinSize`	The smallest cuboid a player may claim, set with X, Y, and Z.
`LandClaimMaxAreas`	The number of separate areas a player may claim.
`AutoGrant`	Grants every registered privilege when set to `true`.

Editing Roles in serverconfig.json

1
Log in to Bropanel and Stop your server.
2
In the sidebar, go to Files.
3
Open the data folder and edit serverconfig.json.
4
Find the Roles section and edit the role you want.
5
Save the file and Start your server.

Here is the default suplayer role for reference:

{
  "Code": "suplayer",
  "PrivilegeLevel": 0,
  "Name": "Survival Player",
  "Description": "Can use/place/break blocks in unprotected areas (priv level 0), create/manage player groups and chat. Can claim an area of up to 8 chunks.",
  "DefaultSpawn": null,
  "ForcedSpawn": null,
  "Privileges": [
    "controlplayergroups",
    "manageplayergroups",
    "chat",
    "areamodify",
    "build",
    "useblock",
    "attackcreatures",
    "attackplayers",
    "selfkill"
  ],
  "RuntimePrivileges": [],
  "DefaultGameMode": 1,
  "Color": "White",
  "LandClaimAllowance": 262144,
  "LandClaimMinSize": {
    "X": 5,
    "Y": 5,
    "Z": 5
  },
  "LandClaimMaxAreas": 3,
  "AutoGrant": false
}

Caution

Stop your server before you edit serverconfig.json. A running server rewrites the file on shutdown and wipes your changes.

Creating a Custom Role

Add a new object to the Roles array with a unique Code. The example below builds a trusted builder role that sits above a normal player and below a moderator.

{
  "Code": "builder",
  "PrivilegeLevel": 50,
  "Name": "Builder",
  "Description": "Trusted builder with a larger land claim allowance and creative mode.",
  "DefaultSpawn": null,
  "ForcedSpawn": null,
  "Privileges": [
    "controlplayergroups",
    "manageplayergroups",
    "chat",
    "areamodify",
    "build",
    "useblock",
    "gamemode",
    "freemove",
    "attackcreatures",
    "attackplayers",
    "selfkill"
  ],
  "RuntimePrivileges": [],
  "DefaultGameMode": 2,
  "Color": "Cyan",
  "LandClaimAllowance": 1048576,
  "LandClaimMinSize": {
    "X": 5,
    "Y": 5,
    "Z": 5
  },
  "LandClaimMaxAreas": 10,
  "AutoGrant": false
}

Save the file, start your server, then assign it with /player Username role builder.

Tip

Copy an existing role and edit it instead of writing one from scratch. That keeps the formatting valid and saves you from a broken config.

Setting Land Claim Limits

You can change land claim limits from the console without editing files.

Command	Description
`/role rolename landclaimallowance value`	Sets the total claimable volume in cubic meters.
`/role rolename landclaimmaxareas value`	Sets how many separate areas a player may claim.
`/role rolename landclaimminsize x y z`	Sets the smallest cuboid a player may claim.
`/role rolename spawnpoint x y z`	Sets a spawn point for the role.

For example, /role suplayer landclaimmaxareas 5 lets every survival player hold five separate claims.

If you get stuck at any time, you can reach out to us on Discord.