StaffCore Handbook

Orientation

The idea

StaffCore is panel-first. Every tool lives behind /staff, in a chest menu you can operate without remembering a single command.

That is the whole design argument. Moderation happens under time pressure, usually while someone is actively causing the problem, and a staff member who has to recall the argument order of /tempban is a staff member who is not watching the griefer. So the panel is the primary interface and the commands are the escape hatch — for free text, for speed, and for people who prefer typing.

Three consequences worth knowing up front:

• Nothing irreversible happens without a confirm screen. Bans, rollbacks, history wipes and inventory restores all show you what is about to happen and make you click again.
• Punishment reasons are presets, not free text. A chest menu has nowhere to type, and a fixed vocabulary makes history comparable across a whole staff team. The command form is there when you genuinely need something bespoke.
• Punishments work on offline players, and so does the inventory view. Both resolve a name through the server's own records rather than requiring the target to be online — which is usually the entire point.
• Every command starts with /staff. One word to remember, and the rest is tab-complete.

The hub

The panel

/staff opens a six-row menu split into three bands, in the order a shift actually runs: what you switch on about yourself, what you do to other people, and what you do to the whole server.

Anything you lack permission for is drawn as an iron-bars "Locked" bar naming the node you need, rather than hidden. Staff can see what exists and ask for it, instead of concluding the mod is broken.

How the screens connect

/staff  Staff Panel
 ├─ Players ─────────── Player List ─┬─ left-click  → whatever you came in for
 │                                   └─ right-click → the player's file
 ├─ Player file ──┬─ Punish ─── Duration ─── Reason ─── Confirm
 │                ├─ History          paged, wipe sits behind a confirm
 │                ├─ Notes            paged, delete sits behind a confirm
 │                ├─ Inventory        live, read-only or editable
 │                ├─ Snapshots ────── Snapshot view
 │                └─ Security check   paged findings
 ├─ Reports ─────────── claim / resolve / teleport
 ├─ Server control ──── chat lock · clear · broadcast · maintenance · TPS
 ├─ Grief log ───────── paged block history ─── Rollback (preview → confirm)
 └─ Analytics ───────── staff leaderboard

The player list is the junction. Whichever door you came in through — Punish, Notes, Inventories — a right-click on any head opens that player's full file, so you are never more than one click from everything else you might need.

Your shift

On duty

Staff Mode

Clocking on does four things at once: it stashes your real inventory, hands you the staff toolset, grants flight, and vanishes you. Clocking off reverses all four.

Your inventory goes to the database, not to memory. That was the one genuine data-loss risk in the mod: a restart while anyone was clocked on used to destroy their items outright. Now clocking on writes the stash before clearing anything — if the write fails, staff mode refuses to start rather than emptying an inventory it cannot put back — and the stash is cleared only after a successful hand-back. The failure mode is a duplicate restore attempt, never a loss.

Disconnecting on duty now keeps you on duty. A staff member who crashes mid-incident comes back with their tools, and their real inventory is still waiting.

The duty gamemode is creative by default, because that is what being on duty actually needs: fly to the report, phase through the base you are inspecting, and put back the block you just proved was griefed. staffModeGameMode defaults to survival. Creative was the old default, and it is the reason four separate containment layers exist: staff tools are refused on drop, stripped on death, destroyed if they reach the ground, and swept every two seconds — all of it work to stop an unlimited item source leaking into the economy. Survival removes the source instead of containing it, and every layer stays as defence in depth.

Very little is lost. Flight comes from being on duty rather than from creative, so staff still fly to a report; noclip is its own toggle; and putting back a griefed block is what rollback is for. Creative is still available and costs three things: staff become an unlimited item source, so anything they hand out is outside the economy and indistinguishable from a duplication bug; they stop looking like ordinary players to an anti-cheat, so their own behaviour goes unchecked; and the containment layers become load-bearing rather than belt-and-braces. spectator is the least intrusive and stops the staff toolset working — the tools are items used by right-clicking, and vanilla drops interactions for spectators before they reach any of this mod's code. Whichever you pick, the gamemode somebody was in before clocking on is stored and handed back when they clock off, so changing this strands nobody. On duty you are also invulnerable, vanished or not, so investigating a mob farm does not make you part of the incident. Set staffModeInvulnerable to false if you would rather staff stayed killable.

Movement

The panel carries a Movement control: noclip and a fly-speed cycle (1× / 2× / 4× / 8×).

Vanish

Vanish is not invisibility. It is the absence of every trace a player leaves.

When you vanish, everyone without staff.vanish sees "<name> left the game" — the real vanilla message, same translation key, same yellow. Un-vanishing sends the matching join line. A staff member who simply blinks out tells every observant player that vanish exists and somebody is watching; one who leaves is indistinguishable from somebody who actually did. Staff who can see through vanish get the truth instead.

The fake message and the real one have to be kept from stacking, and getting that wrong is very visible. Logging off while vanished must not print a second "left the game" on top of the one your vanish already sent, and rejoining must not print "joined the game" or put you back in the tab list. Both took two attempts to get right, and both failures came from the same mistake — assuming an ordering instead of checking it.

The leave line. Suppression is driven by a record of who to stay quiet about, and that record was being cleared from Fabric's disconnect event. Fabric fires that event from the head of the connection teardown, which is before the server builds the "left the game" message — so the state was gone before the message it was meant to suppress existed. The cleanup now happens on the far side of the broadcast instead, driven by the player-list removal that vanilla performs immediately after it.

The tab list. Joining broadcasts your list entry to every client. The old fix sent that entry and then chased it with a removal packet a tick later. That is a race, and a race is exactly the wrong guarantee for a feature whose entire job is that nobody notices — it works most of the time, which is worse than not working at all, because you stop checking. The entry is now simply never sent to clients that should not have it. Same technique as the entity tracker: refuse the decision at the source rather than undo its consequences.

What is covered

Freeze

Pins a player where they stand. Every tick, a frozen player who has drifted more than a few centimetres is snapped back, and every ten seconds they get a reminder not to log out. The small dead zone is deliberate — snapping on any movement fights the client's own prediction and produces rubber-banding; a little slack reads cleanly as "you cannot walk".

Return

Every staff teleport records where you came from, so /back puts you exactly where you were, in the right dimension.

Staff mode

The toolset

Staff mode replaces your hotbar with nine fixed tools. Slots 1, 2, 8 and 9 act when you right-click the air; slots 3 through 6 act on whichever player you right-click; slot 7 acts on whichever block you right-click.

Jump To teleports you to a random player who is not staff. Staff are excluded on purpose: the point of the tool is landing somewhere something might be happening, and staff cluster at spawn.

Inspect Block is the CoreProtect-style inspector: left-click or right-click any block to open the grief log centred on it — who broke it, who placed it, who opened it and when. Left-click is the one to reach for on a chest, since right-clicking one would open it.

On a container it opens the item history instead — who took what out and who put what in, each row showing the actual stack that moved. That is almost always the real question, because the chest is usually still standing and the diamonds are not. A button switches across to the block view.

Per player

A player's file

One screen holding everything StaffCore knows about somebody and everything you can do to them. It opens from the player list, the Inspect tool, or /lookup <player>.

The file is keyed on a profile, not a live player, so it works for someone who has already logged off. Actions that genuinely need them present — teleport, freeze, live inventory — are drawn greyed with the reason stated, rather than silently missing.

The header alone tells you: online or offline, health, dimension, coordinates, punishment count, note count, and an explicit warning line for any ban or mute currently in force. Two status cards below spell out the active ban and mute in full — type, reason, who issued it, when, and what is left to run.

What you can do from here

Enforcement

Punishments

You pick what they did. The ladder picks what happens.

This is the change that matters most to a staff team. Choosing a punishment from scratch every time produces drift — the new moderator who bans for swearing, the veteran who lets their friends off with a warning — and neither is visible until somebody complains. Here the server decides once, in config, that a second instance of chat abuse is a one-day mute, and every staff member applies that identically.

The rung comes from how many times this player has already been done for that specific offence, so escalation is per-offence rather than one global counter: three warnings for spam do not make their first griefing report a permanent ban. The target's prior record sits on the same screen as the decision.

The flow

Two clicks for the common case. The icon tells you the rung before you press it — how many priors they have, what applies now, and what it escalates to next time.

"Something else" drops into the old manual ladder — pick rung, then duration, then reason — for anything the offences do not cover. It is deliberately not the default route.

Offences, their ladders, their icons and their descriptions all come from config/staffcore.json. Add an offence there and a new button appears; change a duration and every staff member's next punishment follows it.

Nothing is written anywhere until you press Confirm. Abandoning the flow at any point leaves no trace.

What happens on confirm

One code path handles every punishment, whether it came from the panel or a command: record it, enforce it, announce it, mirror it to Discord. Staff hear a thunderclap when a ban lands — deliberately the loudest thing in the mod. By default bans and mutes are announced to the whole server; set publicPunishmentBroadcast to false to keep them to staff.

Lifting and history

/unban and /unmute, or the Lift buttons on a player's file, deactivate what is in force and record who lifted it. History keeps everything — spent, expired and lifted entries stay in the list, dimmed, with the name of whoever revoked them.

Records

Notes

The informal half of a player's record — the things that are not punishments but that the next person on shift needs to know. Every note carries its author and a timestamp.

Notes cannot be edited, only deleted. That is deliberate: the value of a note six months later is that it says what somebody actually thought at the time. Deleting one needs staff.notes.remove and goes through a confirm showing the note you are about to lose.

Writing a note needs free text, so it is a command: /notes <player> add <text>. The notes screen tells you so rather than leaving you hunting.

Player-facing

Reports

Open to everyone /report <player> <reason> is the one command in the mod that is not staff-only, and it stays that way even on a server with no permissions plugin installed.

Filing a report pings every subscribed staff member with a bell, mirrors to Discord, and drops into a queue. A per-reporter cooldown (60 seconds by default) stops spam, and a second report against someone already in the queue is merged — the reporter still gets thanked, because their report is real information, but staff attention is not split across duplicates.

The queue

Open reports first, oldest at the top, then claimed ones. Claiming is the whole point of the screen: an unclaimed queue is two staff teleporting to the same player while a third report ages out. One click claims, the claimant's name goes on the icon, and clicking your own claimed report resolves it behind a confirm.

• Left-click — claim it, or resolve it if it is already yours
• Right-click — open the reported player's file
• Shift-click — teleport straight to them

The other side

Appeals

A banned player with nowhere to argue has exactly one move left, and it is an alt.

The ban screen now carries your Discord invite (set discordInvite in config; leave it empty to hide the line). Players who are muted rather than banned can also file in game with /appeal <text> — reachable while muted on purpose, because a mute stops you talking in chat, it is not meant to stop you contesting the mute.

Appeals land in a queue beside reports. Accepting one lifts the punishment it was made against — an appeal that is "accepted" but leaves the ban in place is worse than no appeal system at all. Rejecting closes it with your name attached, so a second appeal arrives carrying the history of the first.

• Left-click — accept, and lift their ban and mute
• Right-click — reject; the punishment stands
• Shift-click — open the player's file first

Either way the player is told the outcome the moment they are next online.

Who is who

Identity & logs

Every connection records the account, the name and the address it came from. From that fall three things staff repeatedly need and previously had to guess at.

Linked accounts

Other accounts that look like they might be the same person, banned ones pulled to the top and marked. On join, a link to a banned account raises a staff alert automatically.

Two kinds of link are found. An exact address match is the strong one. A range match — the same /24, or /64 on IPv6 — catches what exact matching cannot see at all: a home address that moved within its provider's block between one session and the next, and so stopped matching itself. That is not exotic. It is what happens when a router reboots, and it was most of what "a VPN defeats it" really meant.

Each link carries a confidence out of a hundred and the reasoning that produced it. Repeated use of the shared address counts for; a single stray connection counts against. The signal that does most of the work is whether the two accounts have ever been online at the same moment: one person switching between accounts never can be, and two siblings routinely are. Neither is proof, but they point in opposite directions, and a screen that only said "same address" could not tell you which one you were looking at.

Session replay

Watching where somebody went, from inside their own path. Off by default, and the most invasive thing in this mod.

/staff replay <player> [timespan] reconstructs a window from the position history and puts you in spectator at the start of it, moving along the route the player took. pause, resume, speed 0.25–16, restart and exit do what they say. A sidebar carries the time, the coordinates, the speed and how far through you are.

It only shows what was recorded. Switching positionTracking on does not fill in the past — a replay of last week on a server that started recording yesterday is empty, and says so rather than showing an incomplete path as though it were the whole one.

staff.replay is its own permission node and is in the admin group by default, not moderator. Everything else here shows what somebody did; this shows where they were, continuously, whether or not they did anything. A server that wants its moderators to have it can grant it — the default should not be the permissive one for this.

What is stored about a person, and for how long

Two categories here are personal data rather than a record of conduct. They are worth being exact about.

Everything else StaffCore records — punishments, notes, blocks broken, items moved, commands run — is conduct on the server. That belongs to the server in a way somebody's home address does not, and it follows the retention setting for its own feature.

Session log

Every join and leave with a timestamp and address — the fastest way to answer "were they even online when this happened?"

Death log

Cause, killer, world and coordinates for every death, with a click to teleport to the spot. An argument about lost items becomes something you can check.

Ender chest

Its own screen, because the ender chest is where anything worth hiding ends up: it follows the player, survives death, and is invisible to a normal inventory check. Read-only unless you hold security.invsee.edit, and opening it in edit mode is announced to staff chat just like the main inventory.

Evidence

Inventories

/staff invsee opens a genuinely live window: the slots are the player's real inventory, not a copy, so what you see is what they are holding at that instant. Main storage, hotbar, armour and offhand are all laid out in the same geometry every time.

Offline players work too. If the target is not on the server, their inventory is decoded straight out of their save file and shown in the same layout. Those views are always read-only — writing NBT back under somebody who might reconnect mid-edit is a corruption risk no amount of care makes safe — and the header says so rather than leaving you to wonder why the slots will not move.

The footer carries the rest of the file without leaving the screen: the ender chest, snapshots, freeze, a security check, the contraband vault and the punish ladder. The ender chest link is new in both directions — the ender chest screen has always linked back here, but there was no way in, and the one button on this screen that looked like an ender chest was the snapshot button.

Snapshots

Frozen copies of an inventory, capped per player and configurable. They settle the arguments a live view cannot: what somebody had ten minutes ago, before they emptied a shulker into lava.

Several are taken automatically: the instant before a player dies, when they log out, before a staff member opens their inventory to edit, and before a rollback debits them. Automatic captures are ranked below deliberate ones, so they are discarded first when the cap bites — switching them on can never cost you a snapshot you would otherwise have kept.

The death one is the piece of evidence that cannot be reconstructed afterwards — and you can force one from the inventory view or a security check. Restoring a snapshot onto a player takes a snapshot of what they currently have first, so an accidental restore is itself undoable, and the player is told it happened.

A snapshot is the whole inventory — storage, hotbar, armour, offhand and the equipment slots past them. Somebody who died in full enchanted netherite has all of it, not just what was in the nine slots along the bottom, and restoring puts every piece back in the slot it came out of.

Working the slots

In edit mode the window behaves like any other container. Click to pick up and place, and shift-click to move a stack across — from their inventory into yours, or from yours into theirs. Armour and offhand are excluded from shift-click targets, so a stack never lands somewhere it would silently equip.

Confiscation is a deliberate act, not a shortcut. Pick the stack up and drop it on the bundle in the footer, which vaults it and logs it. Only stacks picked up from the target's own slots can be vaulted this way — dropping something of your own on the bundle is refused, because confiscating an item off a player who never had it is not a thing that should be one misclick away.

Snapshots are kept in the database and survive a restart, so an incident that spans one is still answerable. They are pruned by the per-player cap and by retention, with deliberate captures outliving automatic ones.

Automated checks

Security checks

Three checks, run against one player, answering "is this person's stuff possible?" Every finding is a flag, never an action.

Contraband watch

Every two seconds, online players are checked for items that cannot exist in survival — bedrock, spawners, barriers, command blocks, over-stacked stacks — and staff are alerted the moment one appears, with coordinates. Each player-and-item pair alerts once, so somebody carrying contraband around for an hour does not generate an alert every two seconds.

Waiting for somebody to run a manual check means the first person to notice a duplicated spawner is whoever it gets used on. The scan also recurses into shulkers and bundles and covers the ender chest, because hiding contraband one layer deeper is the obvious response to learning that inventories get scanned.

World containers are checked too. The watch only ever saw what somebody was carrying, so the way to keep a banned item was simply not to carry it — leave it in a chest and nothing noticed until it came back out. Chests, barrels and shulkers are now checked as they are opened and as they are closed, which costs nothing extra: the grief log already copies the contents of every container anyone opens, and the check rides along on a copy it has taken anyway. A staff tool found sitting in one goes to the vault, exactly as it would if it were found on a player.

X-ray

The x-ray check reads the grief log rather than watching players, and it will not fire at all until the dig reaches a volume of at least 512 blocks of rock.

A single ratio is a bad detector, so it is not one. Four independent signals are scored into a confidence percentage with the evidence attached:

• Ore fraction — the blunt signal, kept but no longer decisive.
• Directness — filler blocks dug between one vein and the next. This is the signal that actually separates a lucky player from a guided one: luck changes what you find, not how far you tunnel to reach it.
• Beelines — veins reached by a near-straight run of breaks.
• Ancient debris — never generates exposed, so every one found had to be tunnelled to blind.

Ore a player placed themselves is excluded from their own score. Placing a block and breaking it again is an ordinary thing to do — moving a vein, decorating, testing silk touch — and every one of those breaks used to read as a find. It also meant anybody could inflate their own ore fraction to whatever they liked with a stack of iron ore and a wall, which is a poor property for a detector to have.

A background sweep scores online players every five minutes and alerts above 55%, re-alerting only when the score climbs. That matters because x-ray has no victim: nobody files a report saying somebody else found diamonds too easily. Staff who are clocked on are skipped; staff mining on their own time are not, because staff cheat too.

The screen has no punish shortcut on a flag, on purpose. "The scanner said so" is not a reason. The route to acting is back through the player's file, where their record is visible alongside. /itemscanner sweeps every online player at once and reports who is worth a look.

Evidence

Contraband & the vault

Taking somebody's items is the most contestable thing staff do. It should be the easiest thing to undo.

Confiscation used to mean deletion. That makes every mistake permanent and unprovable at once: the item is gone, the player insists it was legitimate, and there is nothing left to look at. Everything taken now goes to the vault instead — a real stack, held, with who it came off, who took it, when and why.

Each row offers exactly two endings. Give it back puts the stack straight into the owner's inventory. Destroy is deliberate, confirmed, and keeps the record — a destroyed item still leaves a row saying it existed and who ended it.

Giving something back no longer requires the owner to be online. It cannot be pushed into their save file — writing player data underneath somebody who might reconnect mid-write is a corruption risk no amount of care makes safe — so the decision is booked instead of the delivery. The row moves to awaiting return, and the item is handed over the moment they next log in. Until then the queued return can be cancelled and the item put back in the vault.

The screen pages straight from the database rather than reading a capped block, so there is no ceiling on what it can show, and the filter in the footer walks through held, awaiting return, returned and destroyed. That last pair matters: the table has always kept a row after an item was handed back or ended, and this is what finally makes that history something you can look at.

Four ways to take something

Confiscation used to be one button that took whatever the scan disliked, and nothing else. That is the right tool when the scan is right and the wrong one every other time — so there are now four, and all of them end in the vault rather than in deletion.

The bundle icon appears on both the inventory and the ender chest screens, and with an empty cursor it opens the vault — so it means the same thing whichever direction you approach it from: this is where confiscated items live.

Repair

Grief log & rollback

Every block broken and placed is logged with who, what, where, which world and when — and so is every container opened, because most "griefing" reports are actually theft and a log that only records broken blocks cannot answer who emptied the chest.

Reading the log

The screen has four controls that decide what you are looking at, and they sit together along the bottom rather than scattered around it.

Repeats are collapsed. Tearing down a wall writes one row per block, so a page could be twenty-eight lines all saying the same thing while the row you came for sat on page four. Consecutive identical actions by one player, in one place, within a couple of minutes now show as a single row with a count — "Steve broke 28× oak planks" — and the rest of the page is free for everything else.

Right-clicking a row filters to that player; the header says who you are scoped to and clicking it clears the filter. Shift-clicking a row previews a rollback of that player at that spot.

Searching the log

The area screen answers "what happened near me, recently", which is the right question most of the time and the wrong one the moment you already know what you are looking for. /staff search takes key:value filters and queries both logs at once:

/staff search player:Steve action:break time:2d
/staff search block:minecraft:spawner radius:200
/staff search Steve container:yes

player: action: block: time: radius: world: and container: are the filters; a bare word is read as a player name, since that is what people type first. Leaving out radius: searches the whole world rather than guessing one. An unrecognised filter is reported rather than ignored — silently dropping half a query and returning confident results would be worse than refusing.

/staff purge <age> [player] deletes history early. Retention already runs daily and unattended; this is for the other reason to delete, which is that somebody asked. It previews what it would remove and does nothing until you add confirm.

The Grief Log screen shows activity within 24 blocks of wherever you are standing, newest first. It is paged on the server — twenty-eight rows and a count per query, read off the main thread and handed back on it — so opening it on a busy world cannot become the cause of the lag you opened it to investigate.

Mass-grief detection alerts staff when somebody breaks an implausible number of blocks in a short window (120 in 20 seconds by default). The threshold sits well above normal mining on purpose: a detector that fires on every strip-miner is one staff learn to ignore.

• Left-click an entry — teleport to that exact spot
• Shift-click — roll back everything that player did in this radius
• Right-click — filter the list to just that player
• The TNT — roll back the whole area, whoever did it
• The clock — double or halve the time window
• The compass — re-centre on your current position

How rollback behaves

Works by player when you know who did it, and by area when several accounts hit one build and naming them one at a time is hopeless. Either way it previews first: you see how many changes will be undone before anything is written. Replay runs newest-first and inverts each action — a logged break puts the block back, a logged place clears it. Order matters: somebody who broke a wall and then built on the rubble has to be undone in the opposite order to how they did it.

Rolled-back entries are marked rather than deleted, so running the same rollback twice is a no-op and the audit trail survives.

Undoing a rollback

Rollback is the most destructive thing here and used to be the only destructive thing with no way back. A ban is revoked, a confiscation handed back, a vaulted item is one click from its owner — but a rollback aimed at the wrong radius overwrote whatever was standing there and that was simply the end of it. The predictable result is staff who hesitate to repair grief at all, which costs a server more than the occasional bad call does.

Every rollback now writes a restore point before it touches anything, recording the blocks it is about to overwrite and the contents of any container it is about to replace.

Doing it from the panel

1. Open the Grief Log and click Rollback history in the top-right corner. The badge on it counts how many rollbacks can still be taken back.
2. Each row is one rollback: who ran it, how many changes, the centre and radius, and how long ago. Rows already undone stay on the list, greyed, showing who undid them — because "has somebody already fixed this?" is the second question people ask.
3. Left-click a row to teleport to where it happened, so you can look before deciding.
4. Shift-click to undo it. A confirm screen names what is coming back; nothing is written until you accept.

Doing it from chat

/staff rollback undo          # reverse the most recent rollback
/staff rollback undo list     # see what is available, with ids
/staff rollback undo 14       # reverse a specific one

The bare form is the one that matters in practice. When somebody watches a repair land on the wrong build they want it back in the next few seconds, not after looking up a number.

Restore points are kept for rollbackPointRetentionDays, seven by default; set it to 0 to record nothing and disable undo entirely. This is a safety net for a mistake noticed shortly after it is made, not an archive — a week is long enough for somebody to log in and find their build missing. Undoing also un-retires the log rows the rollback consumed, so the grief log stops claiming a repair that has since been reversed and the same rollback can be run again if it turns out it was right after all.

When somebody owes items

A rollback takes back what the offender gained by it, or the restore prints items. If they cannot pay — offline, or they spent the loot — the shortfall is booked against their next login rather than written off, and they are told about it when they join.

That debt can outlive the reason for it: a rollback run while testing, or one aimed at the wrong player, leaves somebody nagged on every login with no way to settle it. So it can be written off.

Somebody emptied a chest

This is the most common report on most servers, and until now the log answered only half of it. Click the chest with the inspector and the container log shows every stack that has moved through it — who opened it, what they took, what they put back, and when. That names the thief. It did not give the items back.

Now it does. On any take row:

Server-wide

Server control

Switches that everyone online feels the moment you press them, which is exactly why the two that change what other players can do go through a confirm.

Clearing the server

Blocking new logins alone was half a feature: everybody already online stayed online, and whatever you turned maintenance on to fix carried on being played through. Switching it on now announces the change, then disconnects every player without control.maintenance.

The disconnect screen is the same component the login gate shows, so somebody kicked and somebody refused at the door read one explanation rather than two different ones — including your Discord invite, when discordInvite is set.

The maintenance notice

Turning maintenance on also swaps the server-list MOTD, because a refusal at the login screen only reaches players who already clicked connect — the MOTD is what everybody else actually reads. The real MOTD is captured the first time it is replaced and restored when maintenance ends, so repeated toggles can never leave the notice stuck on.

"maintenanceMotd": "§6§lSERVER IN MAINTENANCE
§7Please wait while we update things — back shortly."

Legacy formatting codes work: §6 gold, §l bold, §r reset, §7 grey, and splits the two lines the server list gives you. Nothing is written to server.properties, so a crash mid-maintenance heals itself — the next start reads your real MOTD back.

TPS watchdog

Samples every thirty seconds and alerts staff when TPS crosses below the configured floor — then once more when it recovers. It is edge-triggered on purpose: a watchdog that repeats every sample is a watchdog people switch off.

Coordination

Staff chat & alerts

Staff chat

/sc <message> for one line, or /staffchat to toggle the channel on and route everything you type there. Messages carry a quiet experience-orb ping so they sit under conversation rather than over it.

One handler governs all chat, in a fixed order: a mute beats everything including the staff channel, then staff chat, then the global lock. That ordering is the point — a muted player must not be able to reach staff chat, and a chat lock must not silence the staff coordinating through it.

Alerts

Reports, security flags, performance warnings and staff actions. Subscription is opt-out: anyone with staff.alerts receives everything until they turn it off, because the failure mode of a quiet alert system is that nobody notices the thing it was built to catch.

Punishments are the deliberate exception — they are already broadcast by the punishment system, and hearing the same event twice trains people to ignore both. They still reach Discord.

The team

Analytics

Per-staff totals — punishments issued, reports claimed, commands logged, last activity — plus server-wide counts, ranked by punishments issued.

Three numbers that are not volume sit alongside them, because counting actions on its own rewards whoever does the most of them:

• Seen through — reports they claimed that actually reached a conclusion. Claiming a queue and leaving it claimed is the failure mode a raw count cannot see at all.
• Typical response — the median gap between a report arriving and them acting. It separates somebody working the queue as it fills from somebody clearing it once a week.
• Later revoked — how many of their punishments were lifted afterwards. The closest thing the database holds to "was this call right".

Anyone with no logged command for two weeks is flagged as quiet. Bear in mind the command log only records StaffCore commands, so somebody who works mostly through the panel will look quieter than they are — the screen says so itself.

Outbound

Discord

Set discordWebhookUrl in the config and punishments, reports and alerts mirror into a channel. Leave it empty and the bridge is simply off; the panel shows which state you are in.

It is fire-and-forget by design — a slow or dead webhook can never stall a tick, and failures are logged once rather than retried. Payloads are built as real JSON, so a player name containing a quote cannot break the message, and @everyone is stripped whatever a staff message contains.

Reference

Command list

Everything lives under /staff. Tab-complete the one word and the whole tree is there, and nothing StaffCore adds can collide with another mod's /ban or /kick. Two commands deliberately stay at the root: /report, because it belongs to players rather than staff, and /sc, because it is typed dozens of times a shift.

/staff <name> with no subcommand opens that player's file. Brigadier tries every literal first, so /staff ban Notch still hits the ban subcommand — only a bare name falls through to the file.

Durations are 30m, 6h, 7d, 1h30m or perm. Anything unparseable is refused, not silently treated as zero.

Reading the placeholders

Everything in angle brackets is something you type; everything in square brackets is optional and has a sensible default if you leave it out. The names are not decoration — each one expects a particular kind of value, and the commonest reason a command "does nothing" is a placeholder filled in with the wrong sort of thing.

Placeholders in the config

One config value takes markup rather than a value: maintenanceMotd is what the server list shows while maintenance is on, and it accepts the game’s own formatting codes. §6 is gold, §c red, §7 grey, §l bold and §r resets back to plain. A literal splits the two lines the server list gives you. Nothing else in the config is a template — every other value is a number, a boolean, or a plain string used as-is.

Reference

Permissions

Install fabric-permissions-api alongside LuckPerms and StaffCore picks it up automatically. That is still the best answer, and it wins outright wherever it is present.

Without one, config/staffcore-permissions.json answers instead. It is written with the starter groups below on first run, and holds node lists — with @other to inherit from another group and staff.* wildcards — plus a map of players to groups. Assign somebody with /staff perms set <player> <group>, and /staff reload re-reads the file after a hand edit.

Op level remains the last resort, for a node no group mentions. report.use is the exception to all of it: it resolves default-true, so /report stays open to everyone rather than quietly becoming admin-only.

Suggested groups

These ship as the defaults in that file.

Reference

Icon key

Chosen so a screen reads at a glance without reading a word. Player heads carry the real skin, and anything currently switched on gets an enchantment shimmer — state is visible in peripheral vision.

Menu frames are black stained glass. The invsee frame turns red in edit mode.

Reference

Sound key

One voice across the whole suite: navigation is quiet and high, state changes are pitched — up for on, down for off — and anything that lands on another player is loud and low. Every sound is sent to a single client, so a vanished admin clicking through menus is silent to everyone else.

Setup

Config

Written with defaults on first run to config/staffcore.json. The file carries a configVersion: when a default changes in a way existing servers should inherit, the value is moved only if it still holds the old default, so anything you deliberately set is left alone and every change is logged. /staff reload re-reads it without a restart.

{
  "discordWebhookUrl": "",            // empty = bridge off
  "requireReason": true,
  "publicPunishmentBroadcast": true,  // false = announce to staff only
  "presetReasons":   [ … ],           // becomes the buttons in the Reason menu
  "presetDurations": [ { "label": "7 days", "spec": "7d" }, … ],
  "reportCooldownSeconds": 60,
  "rootAliases": false,              // /ban, /vanish etc. at the root, if free
  "xrayRatioThreshold": 0.12,         // ore fraction that trips the heuristic
  "xraySampleFloor": 200,             // blocks needed before it fires at all
  "tpsAlertFloor": 17.0,
  "defaultRollbackMinutes": 60,

  "rollbackReclaimsDrops": true,      // without this, every rollback duplicates items
  "rollbackChasesBankedLoot": false,  // follow loot stashed in chests outside the radius
  "rollbackPointRetentionDays": 7,    // how long a rollback stays undoable; 0 disables undo
  "watchContraband": true,            // alert the moment a player is seen holding one
  "watchContainers": true,            // check chests as they are opened and closed
  "scanEnderChests": true,
  "maxSnapshotsPerPlayer": 10,        // 0 keeps every one
  "snapshotRetentionDays": 30,
  "altSubnetMatching": true,          // also link accounts sharing an address range
  "connectionRetentionDays": 90,      // personal data; 0 keeps forever
  "hashConnectionAddresses": true,    // matching still works; the plaintext goes
  "altMinConfidence": 40,             // below this, a link is not worth an alert
  "vanishLoadsChunks": true,          // false = vanish leaves no trace, and you fly into void

  // Shown in the server list while maintenance mode is on
  // \n splits the two server-list lines; §6 gold, §l bold, §7 grey.
  "maintenanceMotd": "§6§lSERVER IN MAINTENANCE\n§7Please wait while we update things — back shortly."
}

The punish flow is entirely preset-driven — add a reason or a duration here and a new button appears, no code change.

Operations

Where data lives

SQLite at <world>/staffcore.db, opened when the server starts, with write-ahead logging on. Schema changes are numbered migrations recorded in the file itself, so an existing install upgrades in place, once, in order, and never has to be deleted to move forward. If it fails to open, every feature that needs it degrades quietly and the rest of the mod carries on.

Survives a restart:

• Vanish state
• Freeze anchors — logging out no longer clears a freeze
• Staff mode, including the duty gamemode you came from
• The on-duty inventory stash
• Inventory snapshots, and everything in the vault
• Anything owed to a player who was offline when staff decided it

In memory only, and cleared by a restart:

• /back return points
• Mass-grief burst counters
• Inspect mode — deliberately, so it cannot eat your first pickaxe swing after a restart

Keeping it safe

The database is the evidence. A punishment record with a hole in it is worse than no record, because somebody will act on the half that survived. Four things stand between you and that:

Security

Anti-cheat bridge

StaffCore does not detect cheating. It gives whatever does the detecting somewhere useful to say so.

An anti-cheat that logs to console is a tool nobody reads. The finding that changes a decision is the one a staff member sees next to everything else they know about that player — the punishment history, the alt links, the mining report. A flag on its own is ambiguous. A flag alongside three others is not.

What arrives

Every provider has its own vocabulary. These are the four things they all say:

These stay separate on purpose. A detection is an opinion; a punishment already happened. Collapsing them is how staff end up either ignoring everything or punishing somebody twice for one offence.

Wiring one up

StaffCore cannot compile against an anti-cheat it does not ship with, so there is one supported integration point and it is a plain method call. Any mod, bridge or script does this:

StaffCore.antiCheat().report(new AntiCheatEvent(
        "Polar",                       // which provider said it
        player.getUUID(),              // or null if you only have a name
        player.getName().getString(),
        AntiCheatEvent.Kind.DETECTION, // or CLOUD_DETECTION, MITIGATION, PUNISHMENT
        "Speed",                       // the provider's own name for the check
        82,                            // confidence 0-100, or -1 if it has none
        "moved 4.2 blocks in one tick",
        System.currentTimeMillis()));

There is a shorter form taking a name instead of a UUID, which resolves the account itself. Either way the call is safe to make from another mod's event thread: a malformed event is dropped with a warning rather than thrown back at you, because an exception there becomes somebody else's crash report.

Reference

Every module

StaffCore is nineteen modules behind one panel. Each owns one job, keeps its own data, and can be switched off without taking anything else with it. This is the whole list, in roughly the order a shift uses them.

Operations

Checking the mod is healthy

StaffCore hooks into the game in thirty-one places. Most of them are allowed to fail without stopping the server, which is the right trade — and it means a broken feature looks exactly like a feature nobody used today. These are the three ways to tell the difference.

1. The startup line

Every boot prints one line. On a healthy server it reads like this:

[StaffCore] Health check: 19/19 hooks present, 15 verified applied.

Hooks present is the number of places in the game StaffCore expects to find. If that first number is lower than the second, an update has moved or removed something and the affected features are off — each one is named on its own line underneath.

Verified applied is the stricter question: not just “is the target still there”, but “did our code actually get injected into it”. It is normally lower than the first number, and that is not a fault. Some hooks cannot be positively confirmed from inside the running game, so the check reports only what it can prove and stays quiet about the rest. A check that cried wolf on a healthy server would teach everybody to ignore it.

2. The Diagnostics screen

/staff → Server Status opens it, or type /staff status for the same information in chat. Every hook is listed with a coloured state:

Each row names the feature it belongs to, so a red entry tells you what stopped working rather than leaving you to map a class name onto a menu.

3. The self test

/staff selftest is the difference between “it started” and “it works”. The health check proves our hooks attached; it cannot prove the code behind them runs. A malformed query, a table missing a column, a command that never registered — all three start cleanly, pass the health check, and fail the first time somebody uses them.

The self test uses the mod and reports eight things:

A failing check names what is broken rather than just failing, and the server keeps running either way — everything that still works is unaffected. Continuous integration runs the same checks on a real server on every change, which is what makes this the layer that catches things before a release does.

4. Module and storage state

Hooks are only half of it. /staff status also reports:

• Modules — which are enabled. A module switched off in the config is off deliberately; one missing from the list entirely is a bug.
• Storage — whether the database opened. If it did not, every feature that needs it degrades quietly and the rest carries on, so this is worth reading rather than assuming.
• TPS — the server’s own tick rate, for context.
• Anti-cheat bridge — which providers, if any, are wired up.

A two-minute check after an update

After any Minecraft, Fabric or StaffCore update, this is the whole routine:

1. Read the startup line. 14/14, or whatever the current total is, on both sides of the slash.
2. If it is short, read the named lines under it — they say which features are affected.
3. Open /staff → Server Status and confirm nothing is red.
4. Run /staff selftest. Eight checks, all passing.
5. Run the manual checks in Known limits — vanish with a second account, break and roll back a chest. Those cover the behaviour no automatic check can see.

The build also runs this automatically: continuous integration boots a real server on every change and fails if any hook is missing, and a scheduled job repeats it against the newest Minecraft snapshot so a breaking change surfaces before a release reaches anybody’s server.

Honesty

Known limits

Stated plainly rather than papered over.

Recovery and evidence

• Rollback only reaches the area and window you give it. That is the scope you asked for, and widening it silently would be worse than not widening it. What is followed beyond the radius is the offender's own loot: ground drops are reclaimed, a live inventory is debited, chests they filled during the same window are emptied back, and whatever an offline offender still owes is collected the next time they log in. Loot handed to somebody else is gone.
• Container rollback still needs somewhere to put things. A full chest cannot take the stack back. The log row is left un-retired so retrying after clearing space works, and the number of stacks that would not fit is now reported rather than left for you to spot.

Detection

• Alt detection is a lead, never a verdict. It links accounts by exact address and by address range, scores each link out of a hundred from how often the address was shared and whether the two accounts have ever been online at the same moment, and shows its reasoning on the screen. A shared household still trips it. A determined evader with a clean VPN still beats it. Only an exact address match can ever ban anybody automatically.
• The x-ray check is a heuristic. It flags, it never acts, and by default it will not commit to a verdict below a 512-block volume of rock. It no longer counts ore a player placed themselves, but it is still inference drawn from a block log. Its thresholds are measured against generated mining patterns, not against real player data — docs/decisions.md records exactly what that does and does not establish.
• Analytics cannot read judgement. Follow-through, response time and overturn rate sit beside the raw counts now, so the leaderboard is no longer purely a volume ranking — but no number here can tell you whether a ban was the right call. Read it as a prompt to go and look at someone's work.

Not built

• Discord is outbound only. Punishments, reports and alerts go out through a webhook; nothing comes back. Two-way needs a gateway connection, a bot token and roughly 10 MB of JDA, which belongs in a separate jar.
• No map integrations. BlueMap, Dynmap and Squaremap would each need that mod present as a compile dependency.

Structural

• Almost every mixin is non-fatal. Exactly one (the login gate behind bans and maintenance) is required; the rest use defaultRequire: 0, so an update that moves an injection point costs you that feature rather than your server. The startup check asks two questions of each hook — is the target still there, and did our code actually get injected into it — so a mixin that quietly fails to apply is named in the log instead of passing as healthy. The second question is answered conservatively: it reports only what it can positively establish, and stays silent on anything it cannot, because a check that fires on a healthy server teaches everybody to ignore it.
• Some of it is still only verified by construction. Every 26.2 API change was read out of the real jar with javap, and the mod now proves rather more of itself at runtime: continuous integration boots a real server and runs the self test, so storage, migrations, the command tree, the contraband list, the detector, backups and exports are all confirmed working on every change. What still is not covered is the behaviour that needs a live client and a second account — vanish being seen, the maintenance kick landing, an inventory screen redrawing. Those are reasoned about and checked by hand.
• The tests cover logic and wiring, not visibility. The automated suite runs the headless half — storage and its migrations, corruption recovery, rollback arithmetic, the x-ray scoring, the contraband list against the real item registry, log parsing — and continuous integration then boots a real server, checks every hook, and runs the self test against a real database. What is still not automated is the half that needs two clients standing in a world: a test per visibility leak (tab list, selectors, sound, waypoints), and killing the server mid-write to prove every state transition survives it. Minecraft's own test framework runs server-side and cannot drive two connected clients, so this is a real gap rather than an oversight, and claiming coverage that is not there would be worse than the gap itself. The manual checks below cover the same ground by hand and are worth running after any Minecraft or Fabric update.
• There are more mixins now, not fewer. Thirty-one classes, thirty of them non-fatal. The vanish rework did remove the fragile one — a hook that reached into a package-private inner class by name — and replaced it with vanilla's own public methods, then added more of those. Each is individually sturdier and each is one more thing a Minecraft update can move. Reducing the count was on the list and did not happen; what happened instead was reducing how badly any one of them can fail, which the startup line reports every boot.

Checks worth running by hand

These are the ones automation does not cover, and they are the ones most likely to break after a Minecraft or Fabric update. Each needs two accounts and a couple of minutes.

Recently closed

Things that used to sit on this list, and what replaced them.