ServerSystem

Homes, warps, teleports, kits, money and moderation. 133 commands, every one of them switchable, and a way in and out of EssentialsX.

---

Essentials is the plugin almost every server installs first and almost nobody is happy with. It works, and it has worked since 2011, which is also the problem: one YAML file per player, a /give you cannot turn off without renaming it, and no idea what Folia is.

ServerSystem is the same job done with the last decade in mind. Player data lives in a database. Every command can be switched off individually. Every player reads in their own language. And if you decide it was a mistake, one command writes everything back out in Essentials' own format.

---

Requirements

• Paper 1.21.x or newer, or a fork of it (Purpur, Pufferfish, Leaves)
• Folia works, the whole plugin uses the region scheduler
• Java 21
• Vault - optional, only so other plugins can see the economy
• PlaceholderAPI - optional, only if you want the placeholders

On first start Paper downloads HikariCP and the database drivers by itself. That is why the jar is half a megabyte instead of twenty.

---

EssentialsX migration

/serversystem migrate here --dry-run
/serversystem migrate here

The dry run reads everything and tells you what it found without writing anything. It carries over balances, homes, warps, spawns, jails, kits, worth prices, nicknames, ignore lists, mail, active mutes and the vanilla ban list Essentials shares.

Your Essentials folder is not touched. Nothing is deleted on either side, and running the import twice updates the same rows rather than doubling them, so you can import, look around, and import again after fixing something.

What has no equivalent is reported rather than dropped in silence. Numeric item ids from 1.12 kits cannot be resolved on a modern server, and a home in a world that is no longer loaded cannot be checked, so both are named in the report instead of being guessed at.

Exporting back

/serversystem migrate to essentials
/serversystem migrate to essentials --apply

The first writes a complete Essentials data folder into plugins/ServerSystem/essentials-export. The second writes it straight into plugins/Essentials, after copying whatever is there into a timestamped backup.

This is not there because anybody should want to go back. It is there because a server that cannot leave a plugin has not chosen it.

---

Switchable commands

commands.yml has one entry per command:

  give:
    enabled: true
    aliases: []
    permission: serversystem.command.give
    cooldown: 0
    cost: 0.0

enabled: false does not hide the command or refuse it - it is never registered with the server at all. It disappears from /help and from tab completion, and the name is free for another plugin to claim. That is the part Essentials cannot do: a command it owns stays owned.

Commands are registered at runtime rather than listed in plugin.yml, which is what makes all of that configuration instead of a jar edit. Names that vanilla already owns, such as /give and /tp, are taken over on purpose. Names another plugin owns are left alone and reported in the console, unless you list them under override-commands in config.yml.

A command added by a later version appends itself to the bottom of the file with its defaults. Nothing you changed is ever rewritten, and comments you add stay.

---

Storage

Essentials keeps one YAML file per player. On a server with thirty thousand of them, /baltop means opening thirty thousand files, and it does it on the server thread.

Here everything is one table. Online players are held in memory, so no command waits for a query. Offline lookups hit the database once and stay cached for five minutes, which is what makes /balance SomeoneWhoLeftLastYear finish instantly. /baltop is one ORDER BY, so it costs the same whether a hundred players exist or a hundred thousand.

SQLite by default and no setup at all. MySQL when several servers should share balances, homes and punishments.

---

Money

Balances are BigDecimal, not double. A double is fine until a server has been trading for a few months and a shop plugin quietly rounds a payout, and by then the only evidence is a player insisting they were short-changed.

Every change is recorded: how much, what it left behind, who did it and why. So "where did my money go" has an answer that does not depend on anybody's memory.

ServerSystem registers itself with Vault, so shops, jobs and crate plugins talk to it the way they already expect. A purchase made through a shop is logged exactly like one made with /pay.

---

Languages

Players are served in the language their Minecraft client is set to. A Spanish player reads Spanish on a German server without anybody configuring anything, and /language overrides it for anyone whose client language is not the one they want to read.

Missing lines fall back per line, not per file, so a half-finished translation is usable rather than a wall of blank text. English, German and French are included. Drop another file into plugins/ServerSystem/lang and it appears in /language on the next reload.

---

Teleporting

One place decides the warmup, the cooldown, whether moving cancels it, and whether the destination is somewhere a player can survive. Doing that per command is how plugins end up with a /home that respects the warmup and a /warp that does not.

Destinations are checked before the player is moved. A home in a room somebody filled with lava is refused rather than being a death sentence, because coordinates do not stay safe.

Teleports are asynchronous, which is a requirement on Folia and a courtesy on Paper: the destination chunk loads off the tick instead of stalling it.

---

Moderation

Nothing is deleted. Lifting a ban marks the row inactive and records who lifted it, so a staff team can see that a player was banned three times and unbanned by the same person each time.

Bans are recorded against the account, not the name, so a rename does not lift one. The login check runs on the async pre-login event, before the server has built a player object, and is a single indexed query rather than a walk over a banlist file.

Warnings can act on themselves. warnings.actions in config.yml maps a count to a command, so a team that agrees "three warnings is a day ban" writes that down once instead of relying on whichever moderator is online to remember it.

---

Setup

/serversystem setup

A checklist of what a new server still needs, with the missing steps clickable.

/serversystem doctor

Checks the database, Vault, PlaceholderAPI, the spawn point, plugins that would conflict, translation gaps and settings that are new in this version.

---

Permissions

serversystem.player is on by default and covers the everyday commands. serversystem.staff and serversystem.admin default to operators. Every command also has its own node, so any of it can be split apart.

Home limits come from permissions rather than a group list in the config: serversystem.homes.<number>, highest wins, serversystem.homes.unlimited beats all of them. A rank that already exists in LuckPerms does not have to be described a second time here.

---

Configuration

Nothing has to be touched. A brand new server can install the jar and leave every file alone.

Five things land in plugins/ServerSystem:

File	Holds
config.yml	every setting, each one commented in place
commands.yml	one entry per command, all 133 of them
kits.yml	the kits, in a readable format or captured with /createkit
worth.yml	what each item sells for
lang/	one file per language

What config.yml covers:

Section	Decides
language	the default language, and whether to follow each player's client
storage	SQLite or MySQL, and how often to save
economy	symbol, decimals, starting balance, floor and ceiling, Vault, transaction log
teleport	warmup, cooldown, whether moving or taking damage cancels, safe destinations
homes warps spawn	home limit, per-warp permissions, per-world spawns, respawn behaviour
chat	message format, command spy, which commands a mute blocks, offline messages as mail
nickname	length, prefix, whether the tab list changes too
moderation warnings jail	default reasons, broadcasts, automatic action at N warnings, jail radius
afk vanish	idle timeout, kick timer, what vanish actually hides

Each command's entry looks like this, and enabled: false means the command is never registered at all:

give:
  enabled: true
  aliases: []
  permission: serversystem.command.give
  cooldown: 0
  cost: 0.0

---

Placeholders

With PlaceholderAPI installed:

Placeholder	Shows
%serversystem_balance%	the raw balance
%serversystem_balance_formatted%	the balance with the currency symbol
%serversystem_balance_compact%	the balance as 1.23M
%serversystem_nickname%	nickname, or the account name
%serversystem_homes% / %serversystem_homes_max%	homes used and allowed
%serversystem_playtime% / %serversystem_playtime_hours%	time played
%serversystem_afk% %serversystem_vanished% %serversystem_god% %serversystem_flying% %serversystem_jailed%	state
%serversystem_language%	the language this player reads in
%serversystem_mail_unread%	unread messages
%serversystem_warps%	how many warps exist

---

Support

Questions, bug reports and translations: dc.gg/paperstream

Licensed under GPL-3.0.