Docs/Setup/Plugin

Plugin

Install the StaffHQ plugin, configure it, and set up staff group sync with LuckPerms.

Supported platforms

StaffHQ ships separate jars for each platform family.

staffhq-plugin-bukkit.jar

PaperSpigotPurpurFolia

staffhq-plugin-bungeecord.jar

BungeeCordWaterfall

staffhq-plugin-velocity.jar

Velocity 3.x

ℹ

Note

For proxy networks (BungeeCord or Velocity), install the proxy jar on the proxy and the Bukkit jar on every backend server. The proxy plugin handles cross-server player tracking.

Download and install

Plugin downloads are available after you purchase a license. Log in to dash.staffhq.net and open the Settings page to download the jar for your platform.

ℹ

Note

Download URLs are tied to your license and are not shared publicly. Do not redistribute the jar file.

1Place the jar in your server's plugins/ directory.
2Start (or restart) the server once to generate the default config.
3Stop the server.
4Edit plugins/StaffHQ/config.yml with your API key and settings.
5Start the server again.

Full config.yml reference

yaml

api:
  endpoint: "https://dash.staffhq.net"
  key: "CHANGE_ME"
  timeout_seconds: 10
  retry_attempts: 5

server:
  name: "My Server"
  type: "bukkit"

tracking:
  chat: true
  commands: true
  punishments: true
  joins_quits: true
  rank_changes: true
  reports: true
  report_commands:
    - "report"
    - "ar"
    - "rts"
    - "staffreport"
    - "sreport"
  command_blacklist:
    - "/login"
    - "/register"
    - "/l"
    - "/reg"
    - "/changepassword"
    - "/cp"
  strip_args_for_commands:
    - login
    - l
    - register
    - reg
    - changepassword
    - changepw
    - auth
    - passwd
    - password
    - premium
    - email

offline_mode: false
debug: false

staff-groups:
  - owner
  - manager
  - admin
  - moderator
  - helper
  - mod
  - srmod

features:
  punishment_execution: false

Config options explained

string

Base URL of your StaffHQ dashboard. No trailing slash.

default: https://dash.staffhq.net

string

Plugin API key from Settings -> Servers in the dashboard. Required.

default: CHANGE_ME

int

HTTP timeout for requests to the dashboard. Increase on slow connections.

default: 10

int

Number of times the plugin retries a failed sync before dropping the batch.

default: 5

string

Display name shown in the dashboard. Can contain spaces.

default: "My Server"

string

Platform tag reported to the dashboard. Set automatically by each jar; usually no need to edit.

default: "bukkit"

bool

Log player chat messages.

default: true

bool

Log player commands. Use command_blacklist to exclude sensitive commands.

default: true

bool

Capture bans, mutes, kicks, and warnings from supported punishment plugins.

default: true

bool

Record when players join or leave the server.

default: true

bool

Record LuckPerms group changes for tracked players.

default: true

bool

Capture player reports issued via the commands listed in report_commands.

default: true

list

Command aliases that trigger a player report. Add your report plugin's aliases here.

list

Commands that are never logged, even when tracking.commands is true. Include the leading slash. Always list authentication commands.

list

Commands whose arguments are redacted before being forwarded. The command name is still logged; arguments become [redacted]. Leading slash is optional.

bool

Set to true if your server allows cracked or offline-mode players.

default: false

bool

Verbose logging to the console. Useful for diagnosing connection issues.

default: false

list

LuckPerms groups treated as staff. Drives auto-detection in the dashboard and the %staffhq_staff_online% placeholder.

bool

When true, the plugin polls the dashboard for pending punishments and runs them as server commands. Off by default.

default: false

ℹ

Note

After editing config.yml, run /staffhq reload in-game or in the console to apply changes. A full server restart is only required when you swap the plugin jar.

Staff group setup

StaffHQ reads group memberships from LuckPerms to determine which players are staff. List the groups you want tracked under staff-groups in config.yml.

Example LuckPerms setup:

bash

# Create a moderator group
/lp creategroup moderator

# Add a player to it
/lp user Steve parent add moderator

# StaffHQ config entry
staff-groups:
  - moderator

✦

Tip

Inherited groups are detected automatically. If moderator inherits from helper, a moderator will still appear as staff even if only helper is listed, as long as the player's highest group is in the list.

Permissions

The plugin does not use Bukkit permissions for tracking. No permissions need to be assigned to players for tracking to work. The staff-groups list in config.yml controls visibility in the dashboard.

Updating the plugin

To update, replace the jar file in plugins/ with the new version and restart the server. Do not delete plugins/StaffHQ/config.yml when updating. New config keys will be added with defaults automatically.

← PreviousGetting Started Next →Dashboard