!!! READ THE DESCRIPTION PLEASE | THERE WILL BE A LITTLE BIT OF CONFIGURATION. !!!

FloodGuard

Server-side protection for Paper servers against automated fluid, TNT, redstone, flying-machine, explosion, and block-based griefing.

FloodGuard monitors suspicious automation and provides configurable detection, containment, alerts, and optional rollback functionality without requiring a client-side mod.

Platform: Paper 1.21+
Java: 21+
Environment: Server-side
License: GPL-3.0

Features

FloodGuard combines event monitoring, machine detection, behavior analysis, configurable limits, staff alerts, and optional rollback features.

Supported protection areas include:

• Flying machines
• TNT machines and automated TNT systems
• TNT duplication mechanisms
• TNT minecarts
• Water-based machines and flooding
• Lava-based machines and lava casting
• Powder snow
• Pistons and moving block structures
• Dispensers and automated triggers
• Redstone clocks and repetitive activation
• Large or abnormal block movement
• Repeated explosions
• Other configurable grief patterns

Detection does not need to treat ordinary player activity as malicious. Administrators can configure thresholds, detection categories, worlds, and responses.

Flying Machines

FloodGuard can monitor piston-based moving structures and identify patterns commonly associated with automated machines.

Detection can use factors such as:

• Piston activity
• Slime and honey block connections
• Observer-controlled movement
• Repeated movement patterns
• Moving block structures
• Machine size
• Machine movement frequency
• Nearby explosive payloads
• Nearby fluid sources

When configured thresholds are exceeded, FloodGuard can contain the machine, cancel relevant activation, notify staff, and record the detection.

TNT Protection

FloodGuard can monitor automated TNT systems and suspicious explosive structures.

Examples include:

• TNT attached to moving machines
• Automated TNT launchers
• Repeating TNT systems
• TNT-based grief machines
• Suspicious TNT dispensers
• Automated explosive mechanisms
• TNT minecart systems

Possible responses include:

• Cancelling dangerous activation
• Preventing continued machine operation
• Removing configured dangerous blocks or entities
• Preventing configured explosions
• Notifying staff
• Logging the detection

TNT Duplication

FloodGuard can detect configurable patterns associated with automated TNT duplication and automated TNT production.

Detection may consider combinations of:

• Pistons
• Slime blocks
• Honey blocks
• TNT
• Observers
• Redstone clocks
• Repeated activation patterns
• Machine movement

Detection is behavior-based rather than relying on a single block or layout. This allows administrators to tune protection thresholds for their server.

TNT Minecarts

FloodGuard can monitor suspicious TNT minecart activity.

Protection can cover:

• TNT minecart cannons
• Automated explosive rail systems
• Repeating TNT minecart attacks
• Redstone-controlled TNT minecart systems

Depending on configuration, FloodGuard can cancel dangerous activation, remove explosive entities, stop associated machines, and alert staff.

Water Protection

FloodGuard can limit automated water-based griefing.

Protection can detect or respond to:

• Automated water machines
• Flying water machines
• Dispenser-based flooding
• Large automated waterfalls
• Repeated source placement
• Fluid activity around moving machines

Administrators can configure detection radius and propagation limits.

Example:

water:
  enabled: true
  detection-radius: 5
  spread-limit: 2

FloodGuard can optionally stop the associated machine, limit further spreading, remove configured source blocks, and notify staff.

Lava Protection

Lava can be monitored separately because large automated lava systems can damage builds and generate significant block-update activity.

Possible detections include:

Lava machines
Automated lava casting
Lava flood systems
Dispenser-based lava systems
Lava attached to moving machines
Abnormal lava propagation

Configured responses can include limiting propagation, stopping associated machine activity, removing selected source blocks, and alerting staff.

Powder Snow

Powder snow can be handled as a separate protection category.

The detection system is intended to be extensible so additional block-based fluid or propagation mechanics can be integrated without rewriting the entire protection system.

Custom Fluids

FloodGuard can expose configuration for compatible custom fluids provided by other plugins or server APIs.

Example:

fluids:
  custom:
    ExamplePlugin:
      - ExampleFluid

Custom-fluid support depends on the APIs and events exposed by the installed server and plugins. FloodGuard should not assume that every third-party fluid behaves identically to vanilla water or lava.

Block Protection

FloodGuard can monitor block-based mechanisms commonly used as components of automated grief machines.

Supported monitoring can include:

Pistons
Observers
Dispensers
Droppers
Repeaters
Comparators
Redstone activation
Moving structures
Automated block placement
Automated block interaction

The goal is to identify destructive behavior without unnecessarily interfering with normal farms, doors, transportation systems, or other legitimate redstone builds.

Redstone Detection

FloodGuard can monitor high-frequency redstone activity without requiring every redstone circuit to be treated as malicious.

Potential signals include:

Rapid piston activation
Observer loops
Repeater clocks
Comparator clocks
Repeated dispenser activation
Repeated machine cycles
Abnormal activation frequency
Large automated mechanisms

Normal farms and redstone builds should remain functional unless configured detection thresholds are exceeded.

Machine Analysis

FloodGuard should evaluate multiple signals before taking a destructive protection action.

Possible inputs include:

Structure
Movement
Redstone
Fluids
Explosives
Frequency
Size
Repetition
Potential damage

A machine can then be assigned a configurable risk score.

Example:

[FloodGuard]

Threat detected
Player: ExamplePlayer
Type: Automated TNT Machine
Risk: 95
Action: Machine contained
World: survival
Location: 1250, 72, -430

Risk scoring is intended to reduce false positives by combining multiple indicators instead of relying on a single rule.

Protection Actions

Protection responses are configurable.

Depending on the detected threat, FloodGuard can:

Cancel an activation
Stop machine activity
Limit fluid propagation
Prevent configured explosions
Remove configured explosive blocks
Remove configured explosive entities
Notify staff
Log the event
Queue supported rollback operations

Each protection module should expose its own configuration where practical.

Alerts

FloodGuard provides configurable staff notifications.

Alerts can be sent to:

Console
Operators
Users with floodguard.notify
Supported external integrations

Example:

[FloodGuard]
Threat detected

Player: ExamplePlayer
Type: Flying TNT Machine
Risk: 95
Action: Machine Disabled
Location: survival 1250 72 -430
Statistics

FloodGuard can maintain bounded statistics for detected activity.

Possible statistics include:

Total detections
TNT detections
Flying-machine detections
Fluid detections
Explosion detections
Machines contained
Alerts sent
Rollback operations

View statistics with:

/floodguard stats
Rollback

FloodGuard can optionally track supported block changes caused by detected threats.

Rollback storage can be limited using configurable:

Time windows
Chunk limits
Storage limits
Retention settings

Rollback should be optimized for large servers and should not store unlimited historical data.

Regular server backups should still be maintained.

Administration

FloodGuard provides administrative controls through commands and an optional operator-only GUI.

Commands
Command	Description
/floodguard status	Display protection status
/floodguard stats	Display detection statistics
/floodguard reload	Reload configuration
/floodguard toggle	Toggle configured protection
/fg	Command alias
Permissions
Permission	Description
floodguard.admin	Full administrative access
floodguard.notify	Receive protection alerts
floodguard.bypass	Bypass configured protection

Only trusted administrators should receive floodguard.bypass.

Admin GUI

The optional GUI is restricted to users with the required administrative permission.

The GUI can expose controls for:

Protection modules
Detection categories
Detection thresholds
Machine radius
TNT radius
Fluid radius
Risk settings
World exclusions
Alert settings
Rollback settings
Performance limits
Statistics
Debug mode

Changes made through the GUI should use the same validated configuration system as manual configuration edits.

Sensitive actions should require confirmation before execution.

Water Cleanup

FloodGuard can provide an operator-only command for removing water source blocks above a specified Y-level.

Example:

/floodguard remove-water <height>

The implementation should:

Require administrator permission
Require a valid height
Operate only in allowed worlds
Target water source blocks according to configured rules
Avoid unnecessary unrestricted world scanning
Provide progress or completion feedback
Respect server performance limits

The exact command behavior may vary with the final implementation.

World Controls

Protection can be disabled for selected worlds.

Example:

worlds:
  disabled:
    - creative
    - testing

This allows servers to keep protection enabled in production worlds while leaving dedicated testing worlds unrestricted.

Configuration

Example configuration:

enabled: true
debug: false

protection:
  flying-machines: true
  tnt: true
  tnt-duplication: true
  tnt-minecarts: true
  water: true
  lava: true
  powder-snow: true
  explosions: true
  redstone-machines: true

detection:
  machine-radius: 5
  tnt-radius: 5
  fluid-radius: 5

actions:
  stop-machine: true
  cancel-explosion: true
  notify-staff: true
  rollback: true

worlds:
  disabled: []

fluids:
  custom: {}
  
The actual configuration can contain additional options depending on the installed version.```

Performance

FloodGuard is intended for multiplayer servers, including servers with significant player counts and automation.

The implementation should prefer:

Event-driven detection
Cached machine data
Bounded collections
Limited chunk access
Asynchronous processing where API-safe
Scheduled cleanup
Configurable scan limits
Bounded rollback storage

FloodGuard should avoid continuously scanning entire worlds or loading chunks solely for background detection.

Protection logic should also avoid unnecessary:

Synchronous heavy computation
Repeated block searches
Unbounded memory growth
Thread creation
Persistent storage growth
Compatibility

FloodGuard targets:

Minecraft Java Edition
Paper 1.21+
Java 21+

FloodGuard is a Paper plugin and does not provide native Bedrock server support.

Compatibility with third-party plugins depends on the APIs and events exposed by those plugins.

Installation
Install Paper 1.21+.
Install Java 21 or newer.
Place FloodGuard.jar in the server's plugins directory.
Start the server once.
Stop the server.
Edit plugins/FloodGuard/config.yml.
Start the server again.

It is recommended to test the configuration on a copy of the server before deploying aggressive protection or rollback settings to a production world.

Limitations

FloodGuard uses configurable detection and behavioral analysis. It does not guarantee perfect detection of every possible redstone machine, exploit, griefing design, or future Minecraft mechanic.

Detection accuracy depends on:

Minecraft version
Paper API behavior
Machine design
Plugin interactions
Configured thresholds
Available events and server data

New Minecraft mechanics may require updates to the detection modules.

FloodGuard should therefore be tested with existing farms, redstone systems, transport systems, and other automation before restrictive settings are enabled on a live server.

Privacy

FloodGuard should only retain information necessary for configured protection, logging, statistics, and rollback functionality.

Retention limits should be configurable.

The plugin should not transmit server data to external services unless the server administrator explicitly enables and configures such functionality.

Development

FloodGuard is intended to use a modular architecture so individual protection modules can be expanded without replacing the entire detection engine.

The implementation should prioritize:

Maintainability
Testability
Clear module boundaries
Defensive error handling
Bounded resource usage
Version-aware Minecraft integration
Clear configuration validation
Project Status

FloodGuard is intended to be:

Production-ready
Modular
Expandable
Fully configurable
Well documented
Error resistant
Optimized for multiplayer environments

Features may be expanded in future releases as Minecraft and Paper mechanics evolve.

License

FloodGuard is licensed under the GNU General Public License v3.0 (GPL-3.0).

You may use, modify, and redistribute FloodGuard in accordance with the GPL-3.0.

Full license text:

https://www.gnu.org/licenses/gpl-3.0.html****