ReportBridge

Network-wide player reporting and moderation for BungeeCord and Velocity.

One /report command for players. One place for staff to handle every report, from every backend server. Optional web dashboard and Discord bot on top.

Download · Dashboard · Commands · Permissions · Configuration · Support

What it does

A player types /report Steve flying in survival-01. The report is stored proxy-side and every staff member online gets an alert, no matter which backend server they are on. Staff claim it, investigate, resolve or dismiss it, and add internal notes. Every action is written to an audit log.

Because ReportBridge runs on the proxy, there is one report list for the whole network. No per-server databases, no reports lost when a player hops servers, no duplicated staff tooling.

It works completely standalone. The web dashboard and Discord bot are optional extras that read the same reports through a REST API.

Features

/report <player> <reason> with validation and anti-spam (cooldown, reason length bounds, self-report and duplicate-report blocking).
One network-wide report list, paginated, with optional clickable [View] [Claim] [Dismiss] chat buttons. Typed commands always work too.
Full staff workflow: view, claim, unclaim, resolve, dismiss, note.
Live staff notifications on new reports, plus a pending-report count when a staff member joins so nothing is missed while they were offline.
Complete moderation audit log.
SQLite storage created automatically, indexed on the columns that get queried.
Every message configurable, with & colour codes and drop-in translations.
/report reload applies config and message changes without a restart.
Uses your proxy's native permission API, so LuckPerms or any other permission plugin works with no hard dependency.
All database work runs off the proxy main thread.
Optional Discord webhook notifications, Discord bot, and web dashboard.
Optional Paper companion plugin for staff sound alerts.

Installation

Download the jar for your proxy from SpigotMC or the releases page:
- BungeeCord: ReportBridge-BungeeCord-1.0.0.jar
- Velocity: ReportBridge-Velocity-1.0.0.jar
Drop it into your proxy's plugins/ folder.
Start the proxy. config.yml and messages_en.yml are generated on first run.
Grant reportbridge.report to everyone and the staff nodes to your staff group (see Permissions).
Edit the config and run /report reload.

Requirements

Platform	Runtime
BungeeCord	Java 17+ (modern builds run on Java 21+)
Velocity	Java 17+ (Velocity 3.4.x requires Java 21+)

The jars target Java 17 bytecode and run on any newer runtime. Any Minecraft version your proxy supports works, since reports are handled proxy-side.

Commands

Command	Description	Permission
`/report <player> <reason>`	Create a report	`reportbridge.report`
`/reports [page]`	Paginated report list (alias `/reportlist`)	`reportbridge.reports.view`
`/report list [page]`	Same as `/reports`	`reportbridge.reports.view`
`/report view <id>`	Report details	`reportbridge.reports.view`
`/report claim <id>`	Claim a report	`reportbridge.reports.claim`
`/report unclaim <id>`	Release a claimed report	`reportbridge.reports.claim`
`/report resolve <id> [reason]`	Resolve a report	`reportbridge.reports.resolve`
`/report dismiss <id> [reason]`	Dismiss a report	`reportbridge.reports.dismiss`
`/report note <id> <note>`	Add a staff note	`reportbridge.reports.note`
`/report reload`	Reload config and messages	`reportbridge.reload`
`/report restart`	Re-initialise storage and config	`reportbridge.admin`

Command labels and aliases are configurable under commands.aliases.

ReportBridge - Pending Reports
#1024 Steve - Cheating - survival-01 [PENDING]
#1023 Alex - Harassment - lobby [PENDING]
#1022 Notch - Exploiting - skyblock [PENDING]
Page 1/3 (18 total)

Permissions

Node	Purpose	Give to
`reportbridge.report`	Create reports	everyone
`reportbridge.reports.view`	View list and report details	staff
`reportbridge.reports.claim`	Claim and unclaim	staff
`reportbridge.reports.resolve`	Resolve reports	staff
`reportbridge.reports.dismiss`	Dismiss reports	staff
`reportbridge.reports.note`	Add notes	staff
`reportbridge.reports.notify`	Separate notify node (optional)	staff
`reportbridge.admin`	Umbrella admin node	admins
`reportbridge.reload`	Reload config	admins

There is no `/op` on a proxy

BungeeCord and Velocity have no operator system, so nobody gets these nodes automatically. Grant them explicitly through your proxy config or permission plugin.

If nobody holds the staff nodes yet, reports are still created and stored safely. They simply wait until someone with reportbridge.reports.view runs /reports.

BungeeCord config.yml:

permissions:
  default:
    - reportbridge.report
  admin:
    - reportbridge.reports.view
    - reportbridge.reports.claim
    - reportbridge.reports.resolve
    - reportbridge.reports.dismiss
    - reportbridge.reports.note
    - reportbridge.admin
    - reportbridge.reload

LuckPerms, run on the proxy:

/lp group default permission set reportbridge.report true
/lp group staff permission set reportbridge.reports.view true
/lp group staff permission set reportbridge.reports.claim true
/lp group staff permission set reportbridge.reports.resolve true
/lp group staff permission set reportbridge.reports.dismiss true
/lp group staff permission set reportbridge.reports.note true

Notifications

New reports alert everyone holding staff.notify-permission, which defaults to reportbridge.reports.view. Any staff member who can see reports is therefore alerted without configuring a second node. Point it at reportbridge.reports.notify if you want to separate "can view" from "gets pinged".

staff.notify-pending-on-join tells staff how many reports are still pending when they connect. Regular players see nothing.

Configuration

config.yml, generated on first run:

plugin:
  name: ReportBridge
  language: en

database:
  type: sqlite
  file: reportbridge.db

report:
  cooldown-seconds: 30
  max-reason-length: 200
  min-reason-length: 3
  prevent-self-report: true
  allow-duplicate-reports: false

staff:
  notify-new-reports: true
  notify-pending-on-join: true
  notify-permission: reportbridge.reports.view
  sound-alert: false

reports:
  page-size: 8
  clickable-components: true

commands:
  aliases:
    report:
      - report
    reports:
      - reports
      - reportlist

messages:
  prefix: "&b[ReportBridge] &r"

All user-facing text lives in messages_en.yml and supports & colour codes and {placeholder} substitution. To add a language, copy the file to messages_<code>.yml, translate it, and set plugin.language.

Storage

Reports live in SQLite inside the plugin data folder. The schema is created on startup with indexes on status, reported_uuid, reporter_uuid and created_at, plus report_id on the audit log.

Access goes through the ReportRepository and AuditRepository interfaces. Timestamps are UTC epoch millis and players are keyed by UUID, so name changes are handled correctly.

Local and cloud mode

connection.mode decides where reports go:

connection:
  mode: local        # standalone, the plugin's own SQLite (default)
  # mode: cloud      # also mirror reports to the ReportBridge API
  api-url: "https://api.reportbridge-mc.scify-tech.com"
  network-id: ""     # from Dashboard -> Network
  api-key: ""        # from Dashboard -> API
  api-secret: ""     # shown once when generated

local needs nothing else. cloud still writes locally first, then mirrors to the API so the dashboard and Discord stay in sync. If the API is unreachable, submissions queue in memory and retry with exponential backoff, using the local report id as an idempotency key. The proxy is never blocked and a bad key logs one warning rather than a stream of them.

API credentials are secrets and never appear in the console.

Discord

Two independent pieces, both optional:

Webhook notifications from the plugin. Enable under discord: in config.yml and reports post as an embed. Disabled by default.
Discord bot with slash commands (/reports, /report view|claim|resolve|dismiss|note) and Claim / Investigate / Resolve / Dismiss buttons. Management is limited to configured roles and users, and every action lands in the audit log as a DISCORD_* entry. Configured from the dashboard.

If Discord is down, in-game reporting is unaffected.

Web dashboard

web/ is a Next.js + Tailwind dashboard: report management with audit history, servers, staff roles, Discord configuration and API key management. It talks only to the API over HTTPS and keeps only the session token in the browser, never network or Discord secrets. See web/README.md.

API

backend/ is the REST API and the single integration point for the plugin in cloud mode, the Discord bot and the dashboard. It handles website-user auth (JWT) and network API-key auth, enforces strict per-network isolation, and exposes report, network and server endpoints plus a realtime SSE stream. See backend/README.md.

Staff sound alerts

Proxies have no world or entity context, so they cannot play sounds. To alert staff audibly, install the optional ReportBridgeCompanion plugin on your backend Paper/Spigot servers and set staff.sound-alert: true on the proxy.

The proxy then sends a plugin message on the reportbridge:sound channel and the companion plays a configurable sound to players holding reportbridge.reports.view. Without the companion, nothing breaks; the setting is simply a no-op.

Project layout

Module	Stack	Purpose
`common/`	Java	Report core, models, SQLite, Discord webhook, cloud client
`bungeecord/`	Java	BungeeCord adapter
`velocity/`	Java	Velocity adapter
`paper-companion/`	Java	Optional backend sound companion
`backend/`	Node, TypeScript, Fastify	REST API, auth, network isolation
`web/`	Next.js, TypeScript, Tailwind	Web dashboard

The dashboard and Discord bot never touch the plugin's database. Everything goes through the API. All report logic lives in common; the platform modules only translate native sender and command types into shared abstractions.

Platform differences are confined to the adapters:

Concern	BungeeCord	Velocity
Descriptor	`bungee.yml`	generated from `@Plugin`
Bootstrap	`Plugin#onEnable`	`ProxyInitializeEvent` + DI
Async work	proxy scheduler	dedicated single-thread executor
Chat	`TextComponent`	Adventure `Component`

Building

./gradlew clean build

Compiles every module, runs the tests and produces the shaded jars:

Module	Output
BungeeCord	`bungeecord/build/libs/ReportBridge-BungeeCord-1.0.0.jar`
Velocity	`velocity/build/libs/ReportBridge-Velocity-1.0.0.jar`
Companion	`paper-companion/build/libs/paper-companion-1.0.0.jar`

Tests only:

./gradlew test

Report creation, validation, cooldown, duplicate prevention, the full claim/resolve/dismiss/note lifecycle, storage failure handling, SQLite repositories and config/message loading are covered without needing a running proxy.

The Node services build with npm install && npm run build in backend/ and web/. See their own READMEs for environment variables.

Contributing

Pull requests are welcome. Keep common free of platform-specific code, add tests for new business logic, and follow the existing package structure and style. Open an issue first for larger changes.

License

MIT. See LICENSE.

Support

Issues and feature requests: GitHub issues
SpigotMC resource: https://www.spigotmc.org/resources/reportbridge.138086/
Dashboard: https://reportbridge-mc.scify-tech.com
Support development: Ko-fi

Navigation Menu

Repository files navigation

ReportBridge

What it does

Features

Installation

Requirements

Commands

Permissions

There is no `/op` on a proxy

Notifications

Configuration

Storage

Local and cloud mode

Discord

Web dashboard

API

Staff sound alerts

Project layout

Building

Contributing

License

Support

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
backend		backend
bungeecord		bungeecord
common		common
gradle/wrapper		gradle/wrapper
paper-companion		paper-companion
velocity		velocity
web		web
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
build.gradle.kts		build.gradle.kts
ecosystem.config.cjs		ecosystem.config.cjs
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle.kts		settings.gradle.kts

Latest commit

History

Folders and files

Repository files navigation

ReportBridge

What it does

Features

Installation

Requirements

Commands

Permissions

There is no /op on a proxy

Notifications

Configuration

Storage

Local and cloud mode

Discord

Web dashboard

API

Staff sound alerts

Project layout

Building

Contributing

License

Support

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

There is no `/op` on a proxy