Skip to content

Getting started

This guide sets up ShottyCore on a Velocity network: the proxy plugin, its database, a companion on each game server, and the staff web panel. The game plugins (ShottyEvents and the rest) are covered in Running an events server and in their own READMEs.

  • A Velocity 4.3 proxy with player info forwarding set up for your backends (modern forwarding).
  • Paper 26.3 game servers, and optionally a Fabric server for Minecraft 26.3 (Fabric Loader 0.20 or newer and Fabric API).
  • Java 25 on the proxy and every game server.
  • A MariaDB server the proxy can reach. ShottyCore keeps all its tables in a database of its own.
  • LuckPerms on the proxy and the game servers, sharing one storage, is strongly recommended. ShottyCore asks LuckPerms who is staff, shows rank prefixes, and its web panel can edit LuckPerms groups and players.
  • Optional: Velocitab (ShottyCore hides staff in staff mode from its tab list and fills an online count), SignedVelocity, GrimAC on the game servers (its alerts reach the proxy), Vault on Paper servers that use the companion’s money.

Create an empty database and a user that owns it, for example:

CREATE DATABASE shottycore CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'shottycore'@'%' IDENTIFIED BY 'a-long-random-password';
GRANT ALL PRIVILEGES ON shottycore.* TO 'shottycore'@'%';

ShottyCore creates and upgrades its own tables. Its numbered migrations run once each when the proxy starts.

  1. Put ShottyCore-Velocity.jar in the proxy’s plugins/ folder and start the proxy once. It writes plugins/shottycore/config.yml and messages.yml.

  2. Stop the proxy and fill in at least:

    network-name: "My Network" # shown in messages, on the staff panel and in emails
    database:
    host: "127.0.0.1"
    port: 3306
    name: "shottycore"
    user: "shottycore"
    password: "a-long-random-password"
    time-zone: "UTC" # dates in commands and on the web panel
    web-panel:
    port: 8085
    public-url: "https://staff.example.com" # where staff open the panel
    player-commands:
    lobby-server: "lobby" # the server /lobby and /hub go to (its name in velocity.toml)
  3. Read through modules: and switch off what you don’t want. A module that needs the database is skipped if the database is down.

  4. Start the proxy and run /shottycore status (or sco status) in its console.

Any setting left out of config.yml uses the built-in default, so you can keep the file short and updates never need it replaced. Settings that change while the proxy runs are applied with /shottycore reload; the database settings only change on a full restart.

Coming from LibertyBans or the Maintenance plugin

Section titled “Coming from LibertyBans or the Maintenance plugin”

ShottyCore’s punishments module owns /ban, /mute and the rest, and maintenance owns /maintenance. Keep both modules off while LibertyBans or the Maintenance plugin is installed. To move over:

  1. /shottycore import libertybans --dry-run shows what would be imported, /shottycore import libertybans imports it. It reads LibertyBans’ database through plugins/libertybans/sql.yml (or the import.libertybans settings) and is safe to repeat.
  2. Switch punishments and maintenance on, remove LibertyBans and the Maintenance plugin, and restart.

Put a companion on every game server:

  • Paper: ShottyCore-Paper.jar in plugins/.
  • Fabric: ShottyCore-Fabric.jar in mods/, with Fabric API.

Nothing has to be set up on them. Each companion talks to the proxy in two ways:

  • Over the player’s connection (plugin channel shottycore:main), for what belongs to one player: chat, freezing, staff mode, inventory checks, nicknames, anticheat alerts.
  • Over HTTP to the proxy’s web panel port, every few seconds, for what belongs to the server: which features are on, store deliveries, prize money. The first time a player joins a server, the proxy gives that server’s companion its name, a key of its own and the addresses to try, which it keeps in proxy-link.properties in its folder. A Paper companion can also link before anyone has joined: it shows a code in its server list ping, and the proxy hands the key to the server that shows it.

So the game servers must be able to reach the proxy’s web panel port. If the address the proxy works out is wrong (the game server’s log says so), set companion-link.url on the proxy, for example http://10.0.0.5:8085.

The companions’ everyday commands (money, homes, teleport requests, spawn, AFK, kits) are off until you switch them on, per server, in the companion’s config or on the web panel’s Servers page. See the companions.

The panel is served by the proxy plugin itself on web-panel.port (8085). Don’t expose that port directly:

  1. Put a reverse proxy with HTTPS in front of it (Nginx, Caddy, Nginx Proxy Manager …), forwarding https://staff.example.com to http://<proxy-host>:8085.
  2. Leave web-panel.trust-forwarded-for: true only if that reverse proxy sets X-Forwarded-For.
  3. Make sure web-panel.public-url is the address staff will type.
  4. In game, run /panel login and click the link. The first time it sets up your password and authenticator app.

See the staff web panel for what is on it.

Give your staff groups the nodes they need; the full list is in ShottyCore’s permissions. A sensible start:

lp group staff permission set shottycore.staffchat true
lp group staff permission set shottycore.panel true
lp group staff permission set shottycore.profile true
lp group staff permission set shottycore.history true
lp group staff permission set shottycore.warn true
lp group staff permission set shottycore.kick true
lp group staff permission set shottycore.mute true
lp group staff permission set shottycore.ban true
lp group staff permission set shottycore.report.manage true
lp group staff permission set shottycore.ticket.manage true
lp group staff permission set shottycore.freeze true
lp group staff permission set shottycore.staffmode true
lp group staff permission set shottycore.staffmode.see true
lp group staff permission set shottycore.invsee true
lp group admin permission set shottycore.* true

Players need nothing for /report, /helpop, /ticket, /msg, /party or /friend.

shottycore.permissions opens the panel’s Permissions page, which can grant anything to anyone. Keep it to admins.

  • /shottycore status on the proxy lists the modules, the database and each linked server.
  • On a game server, /sc hello reaches staff chat on every server.
  • The web panel’s System page shows each game server and how it reaches the proxy.