TShock server: groups and permissions

TShock is a replacement Terraria server that keeps the game identical for players and adds what the vanilla server lacks: user accounts, groups with permissions, protected regions, item and projectile bans, bans that survive name changes, server-side characters, plugins and a REST interface. You install it in place of TerrariaServer, claim ownership with a one-time setup code, create your account in the owner group, and then shape the group ladder to match how much you trust each kind of player. Its one real cost is that it must be rebuilt for every Terraria release, so it trails each update by days or weeks. This guide goes through installation, accounts, groups and permissions in detail, then regions, bans, server-side characters, plugins and the config file.

If you have not decided between vanilla, tModLoader and TShock yet, Terraria and tModLoader server setup compares the three. The vanilla serverconfig.txt and console commands are covered in Terraria server config and commands; this post is about everything TShock adds on top.

What TShock is, and what it cannot do#

TShock is built on OTAPI, a patched copy of the official Terraria server that exposes hooks, and it runs on .NET. Clients connect to it with the normal, unmodified game. From a player's point of view it is a Terraria server that answers slash commands and occasionally tells them they are not allowed to break a block.

What it adds:

• Accounts. Players register a password and log in, so identity is not just a character name anyone can copy.
• Groups and permissions. Every account belongs to a group; every command and many actions need a permission.
• Regions. Protected rectangles where only allowed users or groups can build.
• Anti-grief and anti-cheat checks. Limits on how fast tiles can be broken or placed, damage caps, range checks, and bans on specific items and projectiles.
• Server-side characters. Optional storage of inventories on the server.
• Plugins written in C#, loaded from ServerPlugins.
• A REST API for remote administration and web panels.

What it cannot do: run tModLoader mods. TShock and tModLoader are two separate patched servers, and a modded server with Calamity and friends cannot also be a TShock server. If you want content mods, see running a Calamity modded server instead. TShock also cannot be ahead of the game: a client that updated to a new Terraria version cannot join until a matching TShock release exists.

Installing and the first start#

TShock is distributed as release archives on its GitHub releases page, built per platform and per Terraria version - a file named along the lines of TShock-5.x-for-Terraria-1.4.4.9-linux-x64-Release.zip. The version in the name is the Terraria version it accepts. Download the one that matches the game version your players have, unpack it, and run the server binary.

$ mkdir -p ~/tshock && cd ~/tshock$ unzip TShock-*-linux-x64-Release.zip$ lsTShock.Server  ServerPlugins/  ...$ ./TShock.Server -port 7777 -maxplayers 16 \    -world ~/tshock/worlds/Blossom.wld -autocreate 2 -worldname Blossom

Recent Linux releases are self-contained, so the .NET runtime ships inside the archive; older ones expected the runtime installed separately. Check the release notes of the version you download.

The vanilla start arguments still work - -port, -maxplayers, -world, -autocreate (1 small, 2 medium, 3 large) and -worldname. On the first start TShock creates its own folder beside the binary:

tshock/  config.json        TShock's own settings  sscconfig.json     server-side character settings  motd.txt           the message shown on join  setup-code.txt     one-time ownership code  tshock.sqlite      accounts, groups, bans, regions, warps  logs/              one log file per startServerPlugins/       plugin .dll files

tshock.sqlite is the important one. Every account, group change, ban, region and warp lives in it. Back it up together with the world, because a world restored without its database has regions that no longer match their buildings and bans that have gone.

On a panel-based host, check what the Terraria server actually runs before you replace anything: the console prints TShock's version banner on start if it is already TShock. The start command on a panel is part of the server's configuration, so if your server is vanilla, ask support about running TShock rather than uploading a new binary over the old one.

Claiming the server: the setup code#

The first time TShock starts with no owner account, it prints a setup code in the console and writes it to tshock/setup-code.txt. That code makes whoever uses it a temporary superadmin. Join the server with a normal client and run, in this order:

/setup 12345678/user add yourname a-long-password owner/login yourname a-long-password/setup

The first line grants temporary superadmin. The second creates a permanent account in the owner group. The third logs you into it. The last line, /setup on its own, ends setup mode so the code stops working.

Do all four in one go. A server left in setup mode with the code still valid can be taken over by anyone who reads the console or guesses the code. If you lose access to the owner account later, deleting setup-code.txt and the owner accounts from the database is the recovery route, so keep the owner password somewhere safe.

The server console itself always has full rights. Anything you would type in game, you can type into the panel console, which is the easiest way to administer a server you are not playing on.

Accounts and logging in

Players create accounts themselves:

By default a player can play without logging in, as a guest. RequireLogin in config.json forces login before they can do anything meaningful, and on a public server it should be on - otherwise a griefer simply never registers. New registrations go to the group named in DefaultRegistrationGroupName, default unless you change it; players who are not logged in are in DefaultGuestGroupName, normally guest.

TShock can also log returning players in automatically by their client UUID, which is convenient and a little weaker than a password. Leave it on for a friends' server; consider turning it off for a public one.

Groups and the permission ladder#

Every account is in exactly one group. Every group has a list of permissions and, optionally, a parent group whose permissions it inherits. Out of the box TShock builds a ladder roughly like this:

The exact defaults have moved between major versions, so check yours with /group list and /group listperm <group> before relying on this table. Changes are made with /group:

/group add builder/group parent builder default/group addperm builder tshock.world.editspawn/group prefix builder "[Builder] "/group color builder 120,200,255/user group alice builder

That creates a builder group that inherits everything default has, adds the ability to build inside spawn protection, gives it a chat prefix and colour, and moves Alice into it.

Permissions are dotted strings. A few that come up on every server:

Two syntax details matter. A leading ! negates a permission, which is how you remove something a parent group grants: /group addperm vip !tshock.npc.spawnboss. And * grants everything, which is what owner and the console have; never give * to a group other people are in.

For the general principle behind this - give each person the least they need - see server rules, moderation and staff.

Regions, spawn protection and warps#

Spawn protection is on by default: SpawnProtection and SpawnProtectionRadius (10 tiles) in config.json stop anyone without tshock.world.editspawn building near the world spawn. It is the first thing that confuses new players on a TShock server, who discover they cannot dig next to where they arrived.

Regions are the general version. To protect a base:

/region set 1        then hit the top-left block/region set 2        then hit the bottom-right block/region define TownHall/region allow alice TownHall/region allowg builder TownHall

Regions are protected when created. Other useful subcommands are /region list, /region info <name>, /region protect <name> false to open one up, /region remove <user> <name> and /region delete <name>. /region name followed by hitting a block tells you which region it belongs to, which settles most "why can't I build here" arguments in seconds.

Warps are named teleport points: /warp add Market saves your position, /warp Market takes a player there, /warp del Market removes it. Like everything else, they live in tshock.sqlite.

Bans, mutes and item bans#

TShock's ban system tracks players by account, client UUID and IP address together, so a banned player cannot come back by renaming their character. In TShock 5:

/ban add griefer42 "Destroyed the hellevator" 7d/ban list/ban details 14/ban del 14

Each ban gets a ticket number; /ban details and /ban del take that number. A duration such as 7d or 12h makes it temporary; leave it out for a permanent ban. /kick <player> [reason], /mute <player> and /unmute <player> cover the lighter end.

Item, projectile and tile bans stop specific things being used at all:

/itemban add "Dirt Rod"/itemban allow "Dirt Rod" builder/projban add 17/tileban add 4

Item bans take the item name; projectile and tile bans take numeric IDs, which the Terraria wiki lists. Common candidates on public servers are explosives, liquid-spreading items and anything that can flood or blow up other people's builds. /itemban allow exempts a group, so trusted builders keep tools you have banned for everyone else.

Server-side characters#

By default, a Terraria character lives on the player's PC and comes with them to any server. That means a player can walk onto your progression server with a character from a cheated single-player world, holding endgame weapons on day one. TShock's only real answer is server-side characters (SSC).

SSC is configured in tshock/sscconfig.json:

{  "Settings": {    "Enabled": true,    "StartingHealth": 100,    "StartingMana": 20,    "StartingInventory": []  }}

With Enabled set to true, each account's inventory, health and mana are stored in tshock.sqlite. Players start with what you define, and what they carry is what they earned on your server. Logging in becomes mandatory in practice, since the character is tied to the account.

Turn SSC on before the server opens, not halfway through: every existing player starts again from the starting inventory, and that conversation is easier on day one. Players who also play elsewhere will notice that their character on your server is separate, which is the point.

config.json: the settings that matter#

TShock's own settings are in tshock/config.json, inside a Settings object since TShock 4.5. The file is long; these are the keys worth knowing.

Key names and defaults have changed between major versions, so treat this as a map rather than gospel and read the file your version wrote. After editing, /reload re-reads the config without a restart for most settings; port and slot changes need one.

MaxSlots deserves a note: MaxSlots and the vanilla -maxplayers both exist, and TShock's own setting is the one that decides who gets in. Set both to the same number to avoid confusion.

Plugins and the REST API

Plugins are .dll files in ServerPlugins. They are compiled against a specific TShock API version, and a plugin built for an older TShock usually fails to load on a newer one - the console says so on start. Before updating TShock, check every plugin you rely on has a release for the new version, and keep the old ServerPlugins folder until you know the update worked. Plugins run with the server's full rights, so take them from their authors' release pages, not from re-uploads; keeping a modded server clean has the reasoning.

The REST API, when enabled, is an HTTP interface on RestApiPort that can run commands, list players and manage bans with a token. Web dashboards and Discord bots use it. It is also an admin interface reachable over the network, so if you enable it, use long tokens and do not leave the port open to everyone - firewall rules that matter and RCON, safely cover the same problem for other games.

Updates, saving and backups#

TShock's release cycle follows Terraria's. When Re-Logic ships an update, players' games update automatically and they cannot join an older TShock until a new release appears. For a small patch that is usually days; for a major one it can be longer. Tell your players before it happens rather than after.

Saving works as on vanilla - the world is written periodically with AutoSave on, and /save forces one. Stop the server with /off, which saves and shuts down, rather than killing it; /off-nosave exists for the rare case where you want to throw away what is in memory.

Back up three things together: the .wld world file, tshock/tshock.sqlite, and tshock/config.json. On RE:NODE, backup slots are included on every Terraria plan, stored off the machine, and the Schedules tab can send /save as a console command and take a backup straight after on a cron expression. Terraria world backup and transfer covers the world-file side in detail.

FAQ#

Can players join a TShock server with the normal game?

Yes. TShock is server-side only and clients use the unmodified game. The one condition is version: the client must be on the Terraria version that TShock release was built for.

Can I run TShock and tModLoader together?

No. They are separate patched servers. A server is either TShock with vanilla content, or tModLoader with mods. Some TShock-style admin features exist as tModLoader mods, but not TShock itself.

I lost access to my owner account. How do I get it back?

Use the server console, which always has full rights: /user password <name> <newpass> resets the password. If the account is gone, /user add <name> <pass> owner from the console recreates it.

Why can new players not break blocks near spawn?

Spawn protection. Either move the spawn point away from where people build, reduce SpawnProtectionRadius, or give trusted groups tshock.world.editspawn.

Does TShock make the server slower?

Slightly, in that it checks more things per action, but a TShock server runs comfortably in the same memory as vanilla - 512 MB to 1 GB for a typical world. Plugins are where cost appears.