Skip to content

ShottyCore

A staff toolkit for a Velocity network. One plugin on the proxy does the staff work for every server: punishments, reports, tickets, staff chat, staff mode, chat filtering and logs, private messages and mail, friends, parties, nicknames and maintenance mode, with a staff web panel that adds appeals, staff applications, a store and a public API for your website. A small companion on each Paper or Fabric game server carries out what a proxy can’t, and brings the everyday server commands (money, homes, teleport requests, spawn, AFK, kits).

Part Jar Goes in
Proxy plugin ShottyCore-Velocity.jar the Velocity proxy’s plugins/
Paper companion ShottyCore-Paper.jar each Paper server’s plugins/
Fabric companion ShottyCore-Fabric.jar each Fabric server’s mods/ (with Fabric API)
  • Requirements: Velocity 4.3, Paper or Fabric for Minecraft 26.3, Java 25, MariaDB.
  • Recommended: LuckPerms on the proxy and the game servers, sharing one storage.
  • Optional: Velocitab, SignedVelocity, GrimAC, Vault, NuVotifier, EconomyShopGUI.

Set-up is in Getting started, the web panel in The staff web panel.

Everything is a module you can switch off under modules: in config.yml. A module that needs the database is skipped while the database is down.

Module What it does
staff-chat Staff chat and admin chat across all servers, # and % shortcuts, a toggle mode, and alerts when another member of staff joins, leaves or changes server.
player-data Sessions, IP history, client brand and version, playtime, alt detection and staff notes. Alerts staff when someone joins from an IP shared with a banned account.
chat-log Chat and commands from every server, searchable in game and on the panel. Commands that may carry a password are never stored.
reports A clickable report menu for players, and a staff queue with claim, jump and close. Staff in exempt-groups can’t be reported.
helpop A quick call for help to the staff who are online.
tickets Support tickets as a conversation, in game and on the panel.
watchlist Alerts when a watched player joins, moves, leaves or is reported.
punishments Bans, temporary bans, IP bans, mutes, kicks and warnings, a silent flag, preset reasons with lengths, and actions at a number of warnings.
chat-filter Blocked or flagged words and regex rules. A plain word is found however it is disguised (spacing, repeated letters, digits and look-alike letters).
staff-tools Freeze, staff mode (vanish, flight, a tool hotbar) and inventory checks. Needs the companion.
maintenance Network-wide maintenance mode with a list of who may still join.
vpn-check VPN and proxy detection through proxycheck.io: alert staff, or also kick.
web-panel The staff web panel, the public appeal form and the public API.
statistics The panel’s Statistics page, with countries from a free IP-to-country file the proxy downloads and reads locally.
messaging /msg, /r, /ignore, /msgtoggle, /socialspy and /mail, across the whole network. Mutes, the chat filter and the chat log cover them.
player-commands /seen, /playtime, /list, /ping, /broadcast, /lobby and /hub, and text commands such as /rules.
quiet-joins Drops the public “joined the game” and “left the game” lines on every server.
monitor Checks every public message, private message, mail and party chat against watched words in eleven categories, and lists matches on the panel’s Flagged page. Records, never blocks.
friends /friend across the network; friends are told when a friend joins, changes server or leaves.
party /party and /pc across the network; members follow the leader between servers.
nicknames One nickname per player, kept by the proxy and shown on every server, always with a mark in front so nobody can pass for someone else.
server-switches The panel’s Servers page: each server’s features and command groups switched on or off.
staff-tasks Work handed to staff members, with status and notes, on the panel and with /tasks.
anticheat Collects GrimAC alerts from every server into the player’s history, and can kick a player who keeps tripping one kind of check.

/shottycore (/sco) and /reasons are always there, as are the companion link and the LibertyBans import.

Command Aliases What it does
/report <player> Opens the report menu.
/helpop <message> Asks the staff online for help.
/ticket Opens and follows support tickets.
/msg <player> <message> /tell, /w, /whisper, /m, /pm, /dm A private message to a player on any server.
/r <message> /reply Answers the last private message.
/ignore <player>, /unignore <player> Stops or allows messages, mail, friend and party requests from someone.
/msgtoggle Private messages off or on.
/mail read|send|clear Mail for players who are offline.
/friend add|accept|deny|remove|list|requests /friends, /fr Friends across the network.
/party <player> /p Invites a player (leader only).
/party accept|deny|leave|kick|transfer|disband|list|warp Answers invitations and runs the party. warp brings everyone online to the leader.
/party follow on|off, /party invites anyone|friends|nobody Whether you follow the leader between servers, and who may invite you.
/pc <message> /pchat Party chat.
/nick <name>, /nick off /nickname Sets or clears your nickname.
/realname <nickname> Who is behind a nickname.
/seen <player>, /playtime [player], /ping [player] /pt About yourself and your friends (staff: anyone).
/list /online, /who Who is online where (needs shottycore.list by default).
/lobby /hub Back to the lobby server from anywhere.
/rules, /info, /motd Text commands from text-commands:; add your own.
/apply A one-time link to the staff application form on your website.

Each group can be given a permission in config.yml (empty means everyone), and the command names themselves can be changed (messaging.msg-commands, party.commands, player-commands.lobby-commands …). Remove a name to leave it to another plugin.

Command Aliases Permission What it does
/sc [message] /staffchat shottycore.staffchat Staff chat, or toggle it. #message also works.
/ac [message] /adminchat shottycore.adminchat Admin chat, or toggle it. %message also works.
/profile <player> /whois shottycore.profile Everything about a player.
/sessions <player> shottycore.sessions Their sessions; IPs need shottycore.sessions.ip.
/alts <player> /checkalts shottycore.alts Accounts that shared an IP.
/find <player>, /goto <player> shottycore.find, shottycore.goto Where they are, and go there.
/staff /stafflist shottycore.stafflist Staff online and where.
/note <player> <text>, /notes <player> shottycore.notes Staff notes on a player.
/chatlog <player> shottycore.chatlog Their recent chat and commands.
/reports [open|mine|all|view|claim|close] shottycore.report.manage The report queue.
/tickets shottycore.ticket.manage Open tickets: list, read, claim, close.
/watch <player>, /unwatch <player>, /watchlist shottycore.watchlist The watchlist.
/freeze <player> /ss shottycore.freeze Freezes a player for a screenshare.
/staffmode /sm shottycore.staffmode Vanish, flight and a tool hotbar.
/invsee <player> shottycore.invsee Their inventory; changing it needs shottycore.invsee.modify.
/ban <player> [length] <reason> [-s] shottycore.ban Ban (with a length, a temporary one). -s tells staff only.
/tempban <player> <length> <reason> [-s] shottycore.ban Temporary ban.
/ipban <player> <reason> /banip shottycore.ban.ip IP ban.
/mute, /tempmute, /kick, /warn shottycore.mute, .kick, .warn As /ban.
/unban, /unmute, /unwarn /pardon shottycore.undo Lifts a punishment.
/check <player>, /history <player>, /warns <player>, /banlist /warnings shottycore.history Punishment history.
/reasons [add|remove|list] shottycore.reasons The preset reasons and their lengths.
/chatfilter add|remove|list shottycore.chatfilter The chat filter.
/maintenance on|off|add|remove|list|status shottycore.maintenance Maintenance mode and who may still join.
/socialspy shottycore.socialspy See every private message.
/broadcast <message> /bc, /alert shottycore.broadcast A message to the whole network.
/nick <player> <name|off> shottycore.nick.others Sets or clears someone else’s nickname.
/tasks [start|done <id>] /mytasks shottycore.panel Your staff tasks.
/anticheat <player> /flags, /acflags shottycore.history Their anticheat flags.
/panel login|logout shottycore.panel Sign in to the web panel.
/shottycore reload|status|version|import libertybans [--dry-run] /sco shottycore.admin Reload, status, and importing from LibertyBans.

Lengths are written like 30m, 12h, 7d, 2w. When a reason from the preset list is typed without a length, its own length is used (/ban Notch Cheating). Staff without shottycore.punish.custom can only ban, mute and kick for a reason from the list; warnings are always in the staff member’s own words.

shottycore.* grants everything. Players need nothing for the player commands above (except /list).

Node Lets you
shottycore.staffchat (.toggle) Staff chat, and alerts when other staff join, leave or change server
shottycore.adminchat (.toggle) Admin chat
shottycore.profile, .sessions, .alts, .find, .goto, .stafflist, .chatlog, .notes Look players up
shottycore.sessions.ip See IP addresses
shottycore.report.manage, .helpop.receive, .ticket.manage Work reports, help requests and tickets
shottycore.watchlist (.alerts) Manage and hear about the watchlist
shottycore.history, .warn, .kick, .mute, .ban, .undo Warn; ban, mute and kick for a listed reason; lift punishments
shottycore.punish.custom Ban, mute and kick for a reason and length of your own
shottycore.ban.perm, .mute.perm, .ban.ip Permanent and IP punishments
shottycore.notify, .notify.banned-join, .alts.alerts, .chatfilter.alerts Staff alerts
shottycore.freeze, .staffmode, .staffmode.see, .invsee Staff tools; .staffmode.see sees staff who are in staff mode
shottycore.invsee.modify Move items while inspecting
shottycore.exempt Can’t be punished or frozen by staff (the console still can)
shottycore.report.exempt Can’t be reported
shottycore.socialspy See every private message
shottycore.msg.bypass, .ignore.exempt Reach players who have messages off or ignore you; can’t be ignored
shottycore.broadcast /broadcast
shottycore.list /list, /online, /who
shottycore.lookup.others /seen, /playtime and /ping on anyone, not only friends
shottycore.nick.others Set or clear another player’s nickname
shottycore.monitor (.alerts) The Flagged page and its in-game alerts
shottycore.monitor.manage Change the watched words
shottycore.anticheat.alerts Hear about anticheat flags on other servers
shottycore.anticheat.exempt Never kicked by the anticheat rules
shottycore.chatfilter.bypass, .maintenance.bypass, .vpn.bypass, .report.nocooldown, .helpop.nocooldown Skip the rule
shottycore.vpn.alerts VPN alerts
shottycore.panel Sign in to the web panel (and see the team and your own tasks)
shottycore.appeals, .audit, .reasons, .chatfilter, .maintenance Those pages and commands
shottycore.admin Reload, import, the Email and System pages
shottycore.permissions The Permissions page. It can grant anything to anyone: admins only
shottycore.stats, .map, .features The Statistics, Map and Servers pages
shottycore.news, .rules, .vote, .store The News, Rules, Voting and Store pages
shottycore.applications (.form) Read staff applications (and edit the form)
shottycore.staff.manage Hand out staff tasks and see everyone’s activity
shottycore.accounts Reset another staff member’s panel sign-in
shottycore.notify.email Choose notifications to get by email
shottycore.party.manage Break up a party from the panel

The companions’ permissions are under The companions.

plugins/shottycore/config.yml holds the settings and messages.yml every message, in MiniMessage. Any key you leave out uses the built-in default. /shottycore reload applies changes; the database settings need a full restart.

Section What it sets
network-name Your network’s name, shown in messages (<network> in messages.yml), on the staff panel, the appeal page and in emails.
database The MariaDB connection and pool size.
time-zone The zone dates are shown in.
retention-days Sessions, IP history and chat logs older than this are deleted daily (90; 0 = never). Punishments, reports, tickets and notes are kept.
modules Each module on or off.
staff-chat The channels (commands, permission, shortcut, format) and the staff join/leave/switch alerts.
player-data Alerts for alts of banned players; who counts as staff in /staff.
chat-log Whether commands are logged, and never-log-commands.
reports, helpop, tickets Who may use them, cooldowns, groups that can’t be reported, open tickets per player.
punishments Default reason, whether a reason is required, the appeal address on the ban screen (empty: the panel’s own appeal form), who is told about each kind, commands a muted player can’t use, and warn-actions (a console command at a number of warnings).
chat-filter Which private-message commands are filtered too.
staff-tools What a frozen player may still type, and a command to run if they log out while frozen.
tab Servers whose game plugins need their own scoreboard teams through Velocitab (hidden name tags, team colours).
maintenance Whether to kick everyone not allowed when it goes on.
vpn-check The proxycheck.io key, cache days, and alert or kick.
web-panel Bind address and port, the public address, session lengths, sign-in limits, trust-forwarded-for, appeals.
public-api The read-only addresses for your website: on or off, the rate limit, your site’s address, the servers it lists, and pictures for posts.
companion-link The companions’ own line to the proxy; url when the proxy can’t work out an address they can reach.
statistics Countries on the Statistics page (geoip) and where the free file comes from.
messaging Who may message, the command names, mail limits.
player-commands The lobby server and commands, the message of the day on join, broadcast names, /list permission, and whether lookups are friends-only.
nick Who may use /nick, the mark, and blocked words.
text-commands Commands that print text (/rules, /info, /motd, any you add). <website> and <website-rules> are links to public-api.site-url.
applications /apply, the roles and questions, link hours, cooldown, and whether to ask for an email.
store The Stripe API address (only for testing against a stand-in).
rewards Game wins from /gamewin: the announcement, and which server pays any money, with what command.
leaderboards The website’s leaderboards: on or off, size, and players to leave out.
site-rules Whether /rules prints the panel’s full rules, and how.
party, friends Permissions, command names, sizes, timings, and following the leader.
monitor What is checked, the categories, alerts, and whether private messages are kept for the conversation view.
staff-team Which permission makes someone staff on the Staff team page.
anticheat How alerts are merged and kept, and the automatic kick rules.
map The live maps on the panel’s Map page.
import LibertyBans’ database for /shottycore import libertybans.

The shipped file has placeholders for anything that belongs to your network. Set at least:

  • network-name and time-zone
  • database
  • web-panel.public-url (the address staff open the panel at)
  • public-api.site-url and public-api.servers, if you have a website that uses the public API
  • player-commands.lobby-server, and tab.game-team-servers and rewards.money-server if you use them, which name servers from velocity.toml
  • text-commands (/rules, /info, /motd), which use <network> and <website> and can be reworded freely

anticheat.auto-kick.rules kicks a player who keeps tripping one kind of GrimAC check. Each rule lists check names, a number of alerts in a time, and optionally a gap between alerts. With lag-guard, an alert counts for nothing when another player on the same server tripped the same kind of check within 10 seconds (that is the server lagging, not cheating). A rule can be limited with servers: [...] or except-servers: [...], or switched off with enabled: false. Nobody is ever banned automatically; the kick is an ordinary punishment by “Anticheat”, so it shows in /history.

The companion on each game server does what ShottyCore asks: drops a muted or filtered chat message (the proxy can’t drop signed chat itself), freezes, puts staff into staff mode, opens inventories, shows nicknames, passes GrimAC alerts and NuVotifier votes up, and runs store deliveries and prize money. None of that needs setting up.

It also has the everyday server commands, in groups that are off until you switch them on, per server: in the companion’s config, or on the web panel’s Servers page (which writes your choice into the file and applies it at once).

Group Commands Notes
economy /balance (/bal, /money), /pay, /baltop (/balancetop), /eco give|take|set|reset Kept in whole cents. On Paper it is offered to other plugins through Vault, so shops and crates work with it. A change from the panel applies at the next restart on Paper, at once on Fabric.
homes /sethome, /home, /homes, /delhome One home each unless shottycore.homes.limit.<n> says more.
teleport-requests /tpa, /tpaccept (/tpyes), /tpdeny (/tpno) Requests run out after expire-seconds.
spawn /spawn, /setspawn New players start there; players without a bed respawn there.
afk /afk Also automatic after auto-seconds without moving, chatting or clicking.
kits /kit [name] (/kits), /kit buy <name>, /kitadmin give|take|reset|shop <player> <kit>, /kitadmin reload Kits are in kits.yml (Paper) or kits.json (Fabric).
staff-commands /fly, /heal, /feed, /tpto (/tpo), /tphere, /gmc, /gms, /gma, /gmsp, /ci (/clearinventory) On by default, each behind its permission.
protection – Players can’t trample or break crops, or use doors and trapdoors (protection.crops, doors, trapdoors, fence-gates).

/clear: the game’s own /clear is left exactly as it is for operators, the console, functions and command blocks. Staff who hold shottycore.clear without being operators get a plain form under the same name: /clear empties their own inventory, /clear <player> someone else’s with shottycore.clear.others.

Files are in plugins/ShottyCore/: config.yml (the groups under features: and their settings), kits.yml, and the data in data.db (SQLite).

  • Coming from EssentialsX: on the first start with a group on, balances, homes and the spawn point are copied from plugins/Essentials if that folder is there (import-essentials). EssentialsX’s files are never changed.
  • Kits in a shop: paid kits can be listed in EconomyShopGUI’s /shop. Make a shop section named kits.shop-section (default kits) and name each item in it after a kit, priced like the kit. A purchase there buys the kit instead of handing the item over. For a shop plugin that can run commands, use /kitadmin shop <player> <kit> after it has taken the money.
  • Game wins: /gamewin <game> <player> [money] [label], from the console only, reports a win to the network. See Game wins and prize money.
  • Locator bar: worlds.locator-bar: false (the default) turns the locator bar off in every world. true leaves each world as it is.
  • Linking: proxy-link.self lets the companion link to the proxy before any player has joined. proxy-link.url is only needed when the proxy’s web panel is somewhere it can’t work out.
  • Any message can be reworded under messages: in MiniMessage.

Kits (kits.yml):

kits:
daily:
title: "Daily kit"
icon: BREAD
wait: 1d # 30m, 12h, 1d, 7d, 2w … or "once"
money: 50 # given with the kit
items:
- "BREAD 8"
- "IRON_PICKAXE 1 efficiency:2"
builder:
title: "Builder"
icon: BRICKS
wait: 7d
price: 5000 # bought once with the server's money, then taken on its wait
items:
- "STONE_BRICKS 64"

A kit is refused, without using it up, when the inventory has too little room.

Files are in config/shottycore/: config.json, data.json and kits.json. Permissions are asked of LuckPerms when it is installed, and mean the same as on Paper. (LuckPerms on Fabric normally lets a permission grant everything below it; the companion only takes a real grant or a real wildcard, so shottycore.invsee never turns into shottycore.invsee.modify.) Staff mode on Fabric is flight, no damage and vanish through a vanish mod; there is no tool hotbar.

Lobby rules. For a lobby, protection has more switches. They hold for everyone not in creative or spectator mode, while features.protection is on:

Key Effect
items Players can’t pick items up.
all-blocks Players can’t use any block: buttons, levers, chests, signs …
entities Players can’t right-click or hit anything but players and interaction entities.
pressure-plates Pressure plates and tripwires don’t notice players.
still-water Water and lava stay where they are and never spread.

Locked items. An item whose custom data has shotty_selector or shotty_locked can’t be moved: not into a chest, another slot or the off hand, and not dropped. Use it for a server selector the lobby hands out.

/sendserver <players> <server> (operators, the console and datapack functions) asks the proxy to move players to another server at once, the way a portal would. It goes over the BungeeCord channel, which Velocity answers.

Node Default Lets you
shottycore.balance, .pay, .baltop, .home, .tpa, .spawn, .afk, .kit everyone The everyday commands, where their group is on
shottycore.balance.others everyone Another player’s balance
shottycore.homes.limit.<n> – Up to n homes
shottycore.eco, .setspawn, .kit.admin operators /eco, /setspawn, /kitadmin
shottycore.fly, .heal, .feed, .tp, .tphere, .gamemode operators The staff commands
shottycore.clear (.others) operators /clear and /ci for yourself (and others)
shottycore.protect.bypass operators Not held back by protection
shottycore.gamewin console only /gamewin (refused for players whatever their permissions)

A game on any server reports a winner from the console with:

gamewin <game> <player> [money] [label ...]

The companion passes it to the proxy, which keeps it, tells the whole network, and, when there is money, queues a command on the server that holds the money. It waits there until the winner is on that server, travels signed, runs once, and the winner is told when it lands. ShottyEvents uses this for its prizes.

The settings are under rewards in config.yml:

rewards:
announce: true # tell the whole network
win-message: "<gold>🏆</gold> <white><player></white> <yellow>won <game>!</yellow><prize>"
money-server: "" # the server whose economy pays (its name in velocity.toml)
money-command: "eco give {player} {amount}" # run there, from the console
max-money: 500 # the most one win pays
currency-symbol: "$"

With money-server empty, wins are announced and no money is paid.

  • LuckPerms: permissions, rank prefixes in messages and on the panel, the Staff team page, temporary ranks from the store, and the panel’s Permissions page.
  • Velocitab: staff in staff mode disappear from the tab list, the server list count and name completion, except for holders of shottycore.staffmode.see. Use %shotty_online% in Velocitab’s header or footer for a count that leaves them out. tab.game-team-servers lets game plugins’ scoreboard teams through on the servers you list.
  • SignedVelocity: recommended with 1.19.1+ chat signing. ShottyCore also drops chat through the companion, so muted and filtered chat never shows even where a chat mod bypasses SignedVelocity.
  • GrimAC: each companion passes Grim’s alerts to the proxy: the player’s Anticheat tab, /anticheat <player>, cross-server alerts, and the automatic kick rules. Grim’s own thresholds decide what is an alert.
  • Vault (Paper): the companion’s money is offered to every plugin that uses Vault.
  • NuVotifier (Paper): votes are passed to the proxy and counted on the panel’s Voting page and the public API. The vote plugin on the server still hands out the rewards.
  • EconomyShopGUI (Paper): sells paid kits from /shop.
  • LibertyBans: /shottycore import libertybans brings bans, mutes, kicks and warnings over.
  • BlueMap, squaremap or any map with its own web server: shown on the panel’s Map page, behind the staff sign-in.

ShottyCore stores in its own database what staff work needs: sessions (with IP address, client brand and version), chat and command logs, punishments, reports, tickets, notes, private messages and mail when monitor keeps them, votes, store orders, and panel accounts. Sessions, IP history and chat logs are deleted after retention-days. Countries come from DB-IP’s free IP-to-country file (CC BY 4.0), downloaded once a month and read locally; no player address is sent anywhere for it. statistics.geoip: false turns that off. With vpn-check on, joining addresses are looked up at proxycheck.io.

Tell your players what you keep, in your privacy policy.

The proxy plugin and the Paper companion build with Maven, the Fabric companion with Gradle. See Building from source.

mvn -B package -pl velocity -am # velocity/target/ShottyCore-Velocity.jar
mvn -B package -pl paper -am # paper/target/ShottyCore-Paper.jar
cd fabric && ./gradlew build # fabric/build/libs/ShottyCore-Fabric.jar