Violations System

Understanding how GAPE tracks, logs, and responds to violations.

What is a Violation?

A violation occurs when a player's packet triggers one of GAPE's security checks. Each violation increases the player's violation level (VL) for that specific check.

Violation Levels

GAPE tracks violations per-player, per-check:

  • Independent tracking - Each check has its own violation counter
  • Incremental increase - Each violation adds 1 to the counter (configurable)
  • Time-based decay - Violations decrease over time if no new violations occur
  • Reset on kick - All violations reset when a player is kicked

Example

If a player triggers the Sign Exploit check 3 times in 10 seconds:

  • Violation 1: VL increases to 1, packet cancelled, no alert
  • Violation 2: VL increases to 2, packet cancelled, no alert
  • Violation 3: VL increases to 3, packet cancelled, staff alerted

If the threshold is set to 3, actions trigger on the third violation.

Violation Actions

When a violation occurs, GAPE can take multiple actions:

Cancel Packet

Block the malicious packet from reaching the server. The packet is dropped and never processed by Minecraft.

Alert Staff

Notify online staff members with the gape.alerts permission. Alerts include:

  • Player name
  • Check type
  • Current violation level
  • Timestamp

Log to File

Write the violation to the violations log file for later analysis. Includes full details about the violation.

Kick Player

Automatically kick the player when they reach the violation threshold. Kick messages are configurable.

Execute Commands

Run custom commands when violation threshold is reached. Useful for integrating with ban plugins or Discord webhooks.

Violation Decay

To prevent permanent flagging from accidental violations, GAPE includes violation decay:

Decay Rate

Violations decrease over time if the player doesn't trigger more violations:

  • Default: -1 VL every 30 seconds
  • Configurable: Set custom decay rates per check
  • Minimum: VL never goes below 0

Decay Strategies

  • Fast decay (15s): Forgiving, good for checks with potential false positives
  • Normal decay (30s): Balanced approach (default)
  • Slow decay (60s): Strict, use for critical security checks
  • No decay: Violations never decrease until kick/reset

Logging Configuration

Log Levels

Control what gets logged:

  • All violations - Log every single violation (verbose, for debugging)
  • Threshold only - Log only when threshold is reached (recommended)
  • Kicks only - Log only when players are kicked
  • None - Disable violation logging entirely

Log Format

Violation logs include:

  • Timestamp (ISO 8601 format)
  • Player name and UUID
  • Check type that was violated
  • Current violation level
  • Action taken (cancelled, kicked, alerted)
  • Additional context (packet type, size, etc.)

Log Rotation

GAPE automatically rotates log files to prevent them from growing too large:

  • Daily rotation - New log file created each day
  • Size-based rotation - New file created when current exceeds size limit
  • Automatic cleanup - Old logs deleted after retention period
  • Compression - Old logs compressed to save disk space

Alert Configuration

Alert Thresholds

Configure when alerts are sent to staff:

  • Every violation - Alert on each violation (can be spammy)
  • Threshold only - Alert when VL reaches threshold (recommended)
  • Above threshold - Alert for every violation after threshold
  • Never - No alerts, only log to file

Alert Formatting

Customize how alerts appear in chat:

  • Color coding - Different colors for different severity levels
  • Sound notifications - Play sound effect when alert is sent
  • Hover details - Show additional info on hover
  • Clickable actions - Click to teleport, view inventory, or kick

Alert Filtering

Reduce alert noise:

  • Cooldown - Don't alert more than once per X seconds per player
  • Duplicate suppression - Group repeated violations from same player
  • Check filtering - Only alert for specific check types
  • Severity filtering - Only alert for high-priority violations

Custom Actions

Command Execution

Run commands when violation threshold is reached:

  • Ban commands - Automatically ban repeat offenders
  • Webhook notifications - Send Discord/Slack alerts
  • Database logging - Store violations in external database
  • Custom punishments - Integrate with punishment plugins

Placeholders

Commands support placeholders for dynamic data:

  • %player% - Player name
  • %uuid% - Player UUID
  • %check% - Check type
  • %vl% - Current violation level
  • %timestamp% - Current time

Violation Persistence

Database Storage

GAPE can store violations in a database for long-term tracking:

  • SQLite - Built-in, no setup required
  • MySQL - For network-wide tracking
  • PostgreSQL - For advanced deployments

Cross-Server Sync

Share violation data across multiple servers:

  • Players carry VL between servers
  • Network-wide bans for severe violations
  • Centralized violation tracking
  • Shared alert system

Best Practices

Logging

  • Use "threshold only" logging for production
  • Enable "all violations" logging only when debugging
  • Set log retention to 7-30 days
  • Enable compression to save disk space
  • Regularly review logs to identify attack patterns

Alerts

  • Set alert threshold to 50% of kick threshold
  • Enable cooldowns to prevent alert spam
  • Use sound notifications for critical violations
  • Grant gape.alerts permission only to active moderators

Actions

  • Always cancel malicious packets
  • Enable auto-kick for crash-related violations
  • Use command execution for integration with other plugins
  • Set appropriate decay rates to avoid false positives

Performance

  • Async logging to avoid blocking the main thread
  • Batch database writes for better performance
  • Limit alert broadcast to necessary staff only
  • Use efficient log format (avoid verbose JSON)
Warning: Setting violation thresholds too low can result in legitimate players being kicked. Always test in a controlled environment first.