ReportSystem - Comprehensive Documentation

ReportSystem Documentation

Professional report and moderation system for your Minecraft server

ReportSystem is a comprehensive player reporting and moderation plugin developed for Minecraft servers. Inspired by CS:GO's Overwatch system, it offers community-based review system, automatic replay recordings, and advanced punishment management features.

Tip

This documentation is constantly updated. Follow our Discord server for the latest information.

Features

All features offered by ReportSystem

🎯

Advanced Report System

GUI-based easy reporting, category system, priority levels, and cooldown management

👁️

Overwatch Review

CS:GO style community-based report review, XP/level system, and automatic punishment

🎬

Replay Recording

Automatic 45-second recordings, nearby player tracking, block/inventory recording

🌐

Network Support

BungeeCord/Velocity fully compatible, cross-server reporting and replay viewing

⚡

Punishment Integration

Full integration with LiteBans, AdvancedBan, BanManager

🗃️

Multiple Database

MySQL and SQLite support, automatic table creation

Requirements

Requirement	Minimum	Recommended	Note
Server Software	Spigot 1.18	Paper 1.21	Paper recommended for performance
Java Version	Java 17	Java 21	Java 21 required for MC 1.20.5+
PacketEvents	2.0+	Latest version	Required
Punishment Plugin	-	LiteBans	Optional

Important

The plugin will not work without PacketEvents. The replay system depends on PacketEvents.

Version Compatibility

MC Version	Status	Note
1.21.x	✅ Full Support	Recommended version
1.20.x	✅ Full Support	-
1.19.x	✅ Full Support	-
1.18.x	✅ Full Support	Minimum supported
1.17 and below	❌ Not Supported	Java 17 requirement

Quick Installation (Standalone)

PacketEvents Installation

Download PacketEvents and put it in the plugins folder.

Download from SpigotMC →

ReportSystem Installation

Put ReportSystem-Spigot.jar file in the plugins folder.

First Start

Start the server. Configuration files will be created automatically.

License Activation

Enter your license key in config.yml and restart the server.

config.yml

license:
  license-key: "KB-XXXX-XXXX-XXXX"

Successful Installation

You should see [ReportSystem] Plugin enabled successfully! message in console.

BungeeCord/Velocity Setup

Install ReportSystem-BungeeCord.jar on proxy server

Install ReportSystem-Spigot.jar on all backend servers

Use the same MySQL database on all servers

Set bungeecord.enabled: true on each server

config.yml (Each Server)

bungeecord:
  enabled: true
  display-name: "Survival"  # Server name
database:
  type: mysql
  mysql:
    host: "localhost"
    port: 3306
    database: "reportsystem"
    username: "root"
    password: "password"

Important

In network mode SQLite cannot be used. All servers must connect to the same MySQL database.

Database Settings

SQLite vs MySQL

Feature	SQLite	MySQL
Setup	Automatic	Manual database creation
Network Support	❌ No	✅ Yes
Performance	Good for small servers	Recommended for high traffic
Backup	File copy	mysqldump

MySQL Connection Pool (config.yml)

database:
  type: mysql
  mysql:
    host: "localhost"
    port: 3306
    database: "reportsystem"
    username: "root"
    password: "strong_password"
    pool:
      maximum-pool-size: 10
      minimum-idle: 2
      connection-timeout: 30000
      idle-timeout: 600000
      max-lifetime: 1800000

General Settings

general.debug Default: false

Enables debug mode. Detailed logs are written to console. Use for troubleshooting.

general.language Default: "en"

Language file to use. Available: tr (Turkish), en (English)

general.date-format Default: "dd/MM/yyyy HH:mm:ss"

Date format. Uses Java SimpleDateFormat format.

Report Settings

reports.cooldown Default: 60 (seconds)

Time a player must wait between two reports. 0 = disabled.

Can be bypassed with reportsystem.cooldown.bypass permission.

reports.global-rate-limit Default: 5

Maximum reports per minute. For spam protection. -1 = unlimited.

reports.max-reports-per-player Default: 3

How many times a player can report the same person. -1 = unlimited.

reports.auto-close-days Default: 30

How many days until open reports are automatically closed. -1 = disabled.

reports.categories List

Report categories. Shown as options in GUI.

categories:
  - "Cheating"
  - "Harassment"
  - "Spam"
  - "Griefing"
  - "Bug Abuse"
  - "Other"

Replay Settings

replay.recording-duration Default: 45 (seconds)

Duration of each replay recording. Longer durations mean more data.

replay.auto-delete-days Default: 7

How many days until replay recordings are deleted.

7 = Recordings older than 7 days are deleted
30 = Keep for 30 days
-1 = Never delete (warning: disk may fill up!)

replay.quality.tps Default: 20

Recording quality. 20 = Full quality, 10 = Half quality (less data)

replay.quality.nearby-radius Default: 50

Distance at which nearby players will be recorded (blocks).

Disk Usage

An average 45-second recording takes 50-200 KB. 100 reports per day ≈ 10-20 MB/day.

Overwatch Settings

overwatch.min-reviewers Default: 3

Minimum number of reviews required before a decision is made on a report.

overwatch.consensus-threshold Default: 70.0

Percentage of "Guilty" votes required for automatic punishment. 70% = If 2 out of 3 vote guilty, punishment is applied.

overwatch.auto-ban-duration-days Default: 30

Automatic ban duration when consensus is reached (days).

overwatch.npc.hologram-update-interval Default: 30

NPC hologram statistics update frequency (seconds).

Reward Settings

XP Settings

Setting	Default	Description
`overwatch.xp.guilty-innocent-xp`	15	XP for Guilty/Innocent vote
`overwatch.xp.skip-xp`	5	XP for Skip vote
`overwatch.xp.bronze-xp`	0	XP required for Bronze rank
`overwatch.xp.silver-xp`	500	XP required for Silver rank
`overwatch.xp.gold-xp`	1000	XP required for Gold rank
`overwatch.xp.diamond-xp`	2500	XP required for Diamond rank
`overwatch.xp.xp-per-level`	100	XP required per level

Reward Commands

config.yml

overwatch:
  rewards:
    enabled: true

    # Her inceleme sonrası
    on-review-complete:
      - "give %player% diamond 1"
      - "eco give %player% 100"

    # Sadece Suçlu/Masum oyları için
    on-guilty-innocent:
      - "give %player% emerald 1"

    # Seviye atlama ödülü
    on-level-up:
      - "broadcast &e%player% &7Overwatch seviye &e%level% &7oldu!"
      - "give %player% diamond 5"

    # Rütbe atlama ödülleri
    on-rank-up:
      bronze:
        - "broadcast &c%player% &lBRONZE &7rütbesine ulaştı!"
      silver:
        - "give %player% iron_ingot 32"
      gold:
        - "give %player% gold_ingot 32"
      diamond:
        - "give %player% diamond 64"

Placeholders

%player% Player | %verdict% Verdict | %xp% XP | %level% Level | %rank% Rank

Player Commands

Command	Description	Permission
`/report <player>`	Report a player (opens GUI)	`reportsystem.report`
`/report <player> <reason>`	Report with direct reason	`reportsystem.report`
`/reports`	View your own reports	`reportsystem.view`

Aliases: /rapor, /raporla, /reportplayer

Staff Commands

Command	Description	Permission
`/reports all`	List all reports	`reportsystem.view.all`
`/reports <id>`	View specific report	`reportsystem.view.all`
`/reports accept <id>`	Accept report	`reportsystem.manage`
`/reports reject <id>`	Reject report	`reportsystem.manage`
`/reports delete <id>`	Delete report	`reportsystem.delete`

Overwatch Commands

Command	Description	Permission
`/overwatch`	Open Overwatch main menu	`reportsystem.overwatch`
`/overwatch stats`	View your statistics	`reportsystem.overwatch`
`/overwatch leaderboard`	View leaderboard	`reportsystem.overwatch`
`/overwatch npc create <name>`	Create Overwatch NPC	`reportsystem.overwatch.admin`
`/overwatch npc remove`	Remove nearby NPC	`reportsystem.overwatch.admin`
`/overwatch npc list`	List all NPCs	`reportsystem.overwatch.admin`
`/overwatch queue add <id>`	Add report to queue	`reportsystem.overwatch.admin`

Aliases: /ow, /overwatchsystem

Admin Commands

Command	Description	Permission
`/reportsystem reload`	Reload configuration	`reportsystem.admin`
`/reportsystem stats`	View system statistics	`reportsystem.admin`
`/reportsystem info`	View plugin information	`reportsystem.admin`
`/reportsystem debug`	Toggle debug mode	`reportsystem.admin`

Aliases: /rs, /rsystem

Basic Permissions

Permission	Description	Default
`reportsystem.report`	Permission to create reports	Everyone
`reportsystem.view`	View own reports	Everyone
`reportsystem.cooldown.bypass`	Bypass cooldown	OP
`reportsystem.exempt`	Cannot be reported	OP

Moderator Permissions

Permission	Description
`reportsystem.view.all`	View all reports
`reportsystem.notify`	Receive new report notifications
`reportsystem.manage`	Accept/reject reports
`reportsystem.punish`	Give punishments (ban, mute, kick)
`reportsystem.overwatch`	Use Overwatch system

LuckPerms Example

Console Commands

/lp creategroup moderator
/lp group moderator permission set reportsystem.view.all true
/lp group moderator permission set reportsystem.notify true
/lp group moderator permission set reportsystem.manage true
/lp group moderator permission set reportsystem.overwatch true

Admin Permissions

Permission	Description
`reportsystem.*`	All permissions (wildcard)
`reportsystem.admin`	Admin commands (reload, stats)
`reportsystem.delete`	Permission to delete reports
`reportsystem.overwatch.admin`	Overwatch admin (NPC, queue)

Replay System

How It Works?

When a player is reported, the system records the last 45 seconds

Recording is compressed and saved to database

When staff reviews the report, replay is played as NPC

Viewer can see all movements

Recorded Data

Player position and direction (every tick)
Inventory changes
Block breaking/placing
Attack animations
Riding (horse, boat, etc.)
Nearby players (within 50 blocks)
Chat messages

Replay Controls

Item	Function
⏸️ Pause	Pause/resume replay
⏪ Rewind	Go back 10 seconds
⏩ Fast Forward	Go forward 10 seconds
🔴 Stop	End replay
🏃 Speed	Change playback speed (0.5x - 2x)

Important

While watching replay, other players cannot see you and you cannot interact with the world.

Overwatch System

What is it?

Overwatch is a community-based report review system inspired by CS:GO. Trusted players review reports and vote. If enough "Guilty" votes are received, automatic punishment is applied.

Review Process

Player right-clicks Overwatch NPC

System assigns a random report from queue

Reviewer watches the replay

Makes decision: Guilty, Innocent or Skip

Earns XP and rank progresses

Rank System

Rank	Required XP	Color
🥉 Bronze	0 XP	Bronze
🥈 Silver	500 XP	Silver
🥇 Gold	1000 XP	Gold
💎 Diamond	2500 XP	Diamond

NPC System

Creating NPC

/overwatch npc create Overwatch-1

Creates an Overwatch NPC where you are looking.

NPC Features

Appears with pirate captain head
Shows hologram statistics
Opens Overwatch menu when right-clicked
Automatically restored on server restart
Cannot be broken and items cannot be taken

NPC Management

/overwatch npc list      # List all NPCs
/overwatch npc remove    # Remove nearby NPC

Punishment Plugins

ReportSystem works fully compatible with the following punishment plugins:

✅

LiteBans

Recommended punishment plugin. Full integration.

✅

AdvancedBan

Full integration support.

✅

BanManager

Full integration support.

Auto Detection

No configuration required. Plugin automatically detects installed punishment plugin.

PlaceholderAPI

If PlaceholderAPI is installed, the following placeholders can be used:

Placeholder	Description
`%reportsystem_reports_total%`	Total report count
`%reportsystem_reports_pending%`	Pending report count
`%reportsystem_player_reports%`	Reports received by player
`%reportsystem_overwatch_xp%`	Overwatch XP
`%reportsystem_overwatch_rank%`	Overwatch rank
`%reportsystem_overwatch_reviews%`	Number of reviews made

Frequently Asked Questions

Does it work without PacketEvents?

No. Replay system depends on PacketEvents. Plugin will not start.

How much space do replay recordings take?

Average 45-second recording is 50-200 KB. 100 reports per day ≈ 10-20 MB.

When are replay recordings deleted?

According to replay.auto-delete-days setting. Default is 7 days.

Can two people watch the same replay?

Yes. Each viewer sees their own NPCs, they don't affect each other.

Does Overwatch NPC disappear on server restart?

No. NPCs are saved to database and automatically recreated.

Do arrows/potions in replay affect real players?

No. Replay projectiles are harmless and ineffective.

Troubleshooting

Plugin not starting

Check if PacketEvents is installed
Check Java version (minimum Java 17)
Check console logs

Replay not playing

Check replay.auto-record: true
Replay may have expired (auto-delete-days)
Enable debug mode with /rs debug

Database connection error

Check MySQL credentials
Make sure database exists
Check firewall settings

Support

💬

Discord Server

24/7 community support and instant help

Join Discord

🐛

Bug Report

Found a bug? Report it in #bug-report channel on Discord.

Thank You

Thank you for choosing ReportSystem!

Comprehensive Guide

ReportSystem Documentation

Features

Requirements

Version Compatibility

Quick Installation (Standalone)

PacketEvents Installation

ReportSystem Installation

First Start

License Activation

BungeeCord/Velocity Setup

Database Settings

SQLite vs MySQL

General Settings

Report Settings

Replay Settings

Overwatch Settings

Reward Settings

XP Settings

Reward Commands

Player Commands

Staff Commands

Overwatch Commands

Admin Commands

Basic Permissions

Moderator Permissions

LuckPerms Example

Admin Permissions

Replay System

How It Works?

Recorded Data

Replay Controls

Overwatch System

What is it?

Review Process

Rank System

NPC System

Creating NPC

NPC Features

NPC Management

Punishment Plugins

PlaceholderAPI

Frequently Asked Questions

Troubleshooting

Support