AquaGuard is a professional-grade block logging, inspection, and rollback mod for Minecraft servers. Track every block placement, container interaction, entity kill, and player action — then roll back grief or mistakes in seconds. Built on Architectury as a multiloader mod: one codebase, three loaders.
AquaGuard is a server-side Minecraft Forge mod designed for administrators who need a full audit trail of everything that happens on their server. It logs 18+ action types to an SQLite or MySQL database, lets you inspect any block's history in-game, and restores entire areas to an earlier state — all without lagging the server.
Primary use cases:
- Investigate and roll back grief on survival or modded Minecraft servers
- Collect evidence for ban appeals with timestamped logs
- Debug contraption misbehavior on technical Forge servers
- Audit container and item transactions on economy servers
| Feature | Details |
|---|---|
| 18+ Action Types | Block place/break, container open/modify, entity kill, player death, item pickup/drop, explosions, fluid placement, furnace smelting, chat, commands, login/logout |
| Async Database | HikariCP connection pool with a dedicated worker thread — zero tick impact on the main thread |
| SQLite & MySQL | Embedded SQLite out of the box; switch to MySQL/MariaDB for multi-server setups |
| String Pool | Deduplicates player names, block states, and dimension IDs — keeps the database compact |
| Inspector Tool | Right-click any block with the inspector stick to see its last 10 actions inline |
| Advanced Lookup | Filter by player, radius, position, or action type with time ranges from 10 seconds to 7 days |
| Async Rollback | Chunk-based scheduler restores up to 500 blocks per tick; preview mode shows scope before applying |
| Full NBT Restore | Container contents, sign text, machine states, and energy values are stored as exact binary NBT and restored precisely |
| Entity Rollback | Destroyed item frames (with maps), paintings, and armor stands are re-spawned from their saved NBT on rollback |
| Container Rollback | Item deposits and withdrawals are reversed exactly — rollback puts stolen items back and removes planted ones, with full component/enchant fidelity |
| Mod Integration | Detects FakePlayer machines (Create, Modular Machinery, etc.); exposes a public API for third-party mods |
| Mixin Logging | Captures furnace smelting events at the bytecode level for complete coverage |
| Rename-Proof History | Player lookups, rollbacks, stats, and exports resolve to a UUID, so a name change never splits or hides a player's history |
| Multi-Dimension | Logs are dimension-aware; rollbacks stay scoped to the correct world |
| Safe Rollback | Reverted changes are flagged (rolled_back) so re-running a rollback is a no-op and restore knows exactly what to re-apply — no double-reverts |
| Grief Alerts | Optional real-time Discord webhook when a player breaks blocks faster than a configurable threshold |
| Auto-Prune | Optional scheduled deletion of old logs so the database never grows unbounded |
| CSV Export | /ag export dumps a player's full history to a CSV file for ban appeals and audits |
| Anonymous Telemetry | Optional aggregate usage reporting to a self-hosted Worker + GitHub Pages dashboard; no player names, UUIDs, IPs, chat, commands, coordinates, NBT, or raw logs |
AquaGuard is a multiloader (Architectury) mod targeting Minecraft 1.21.1, Java 21. A single build produces one jar per loader:
| Loader | Minimum version | Jar |
|---|---|---|
| Forge | 52.0.16+ | aquaguard-forge-<version>.jar |
| NeoForge | 21.1.93+ | aquaguard-neoforge-<version>.jar |
| Fabric | loader 0.16+, Fabric API | aquaguard-fabric-<version>.jar |
Pre-1.21.1 Forge-only builds remain available on the
masterbranch's earlier releases. The multiloader line targets 1.21.1 only. GUI and client networking are deferred to a later release; the current scope is the server-side core (logging, lookup, rollback, alerts, prune, export). | 1.18.2 | 40.2.0+ | 17 |
The default build targets Minecraft 1.20.1. Change mc_version in gradle.properties to build for any supported version.
- Download the latest release JAR from the Releases page.
- Drop it into your server's
mods/folder. - Start the server once to generate the config at
config/aquaguard/aquaguard-common.toml. - Edit the config to enable MySQL if needed (SQLite works out of the box).
- Restart the server.
No client-side mod required. AquaGuard runs entirely on the server.
All commands use the /ag prefix. Shorthand aliases are shown in parentheses.
/ag inspect (alias: /ag i)
Toggles inspector mode. While active, right-click a block to view its 10 most recent actions with timestamps, block states, and item data. Left-click to view extra NBT details.
/ag lookup user <player> [time] (alias: /ag l u)
/ag lookup radius <1-100> [time] (alias: /ag l r)
/ag lookup position <x> <y> <z> [time] (alias: /ag l p)
/ag lookup action <action_type>
/ag lookup page <number>
Results are paginated (10 per page). Color-coded action types, clickable coordinates, and hover tooltips with before/after block states.
Time formats: 10s 30s 1m 10m 1h 12h 24h 7d
/ag rollback user <player> [time] [action] [preview]
/ag rollback radius <1-100> [time] [action] [preview]
/ag restore user <player> [time] [action] [preview]
/ag restore radius <1-100> [time] [action] [preview]
preview:true— shows how many blocks would be affected without changing anything.action— optional filter (e.g.block_break) to only roll back one action type.- Rollback undoes player changes; restore re-applies them.
/ag prune <time> (alias: /ag purge) — delete logs older than <time>
/ag status — show log count, DB size, write-queue health, and active config
/ag export <player> [time] — export a player's full history to a CSV file for evidence
Automatic pruning and real-time Discord grief alerts can be enabled in the config — see CONFIGURATION.md.
| Permission Level | Commands |
|---|---|
| Level 2 (Moderator / Op) | /ag inspect, /ag lookup, /ag status |
| Level 3 (Admin / Op) | /ag rollback, /ag restore, /ag prune |
File location: config/aquaguard/aquaguard-common.toml
# Database
database_type = "SQLITE" # SQLITE or MYSQL
mysql_host = "localhost"
mysql_port = 3306
mysql_database = "aquaguard"
mysql_username = "root"
mysql_password = ""
# Logging toggles (all default to true)
log_block_place = true
log_block_break = true
log_container_access = true
log_container_modify = true
log_entity_kill = true
log_player_death = true
log_item_pickup = true
log_item_drop = true
log_explosion = true
log_fluid_place = true
log_player_login = true
log_player_logout = true
log_player_chat = true
log_player_command = true
# Anonymous telemetry (aggregate only; opt-out)
telemetry_enabled = true
telemetry_endpoint = "https://<worker-domain>/api/telemetry"
telemetry_interval_minutes = 30
telemetry_public_notice = trueDisable any category you don't need to reduce database write volume.
Set telemetry_enabled = false to disable all outbound telemetry.
The telemetry backend lives in telemetry-worker/. The static dashboard lives in
docs/telemetry/ and is deployed by the GitHub Pages workflow.
Third-party mods can log custom events through the public AquaGuard API:
// Log a custom action from your mod
AquaGuardAPI.logCustomAction(
player, // ServerPlayer
level, // ServerLevel
blockPos, // BlockPos
"MY_ACTION", // action type string
beforeState, // BlockState (nullable)
afterState, // BlockState (nullable)
extraData // CompoundTag NBT (nullable)
);Add AquaGuard as an optional dependency in your mods.toml:
[[dependencies.yourmodid]]
modId = "aquaguard"
mandatory = false
versionRange = "[1.0.0,)"
ordering = "AFTER"
side = "SERVER"See CONTRIBUTING.md for build instructions.
git clone https://github.com/denfry/AquaGuard.git
cd AquaGuard
# Build all three loaders at once (Minecraft 1.21.1)
./gradlew buildThis produces three jars:
forge/build/libs/aquaguard-forge-<version>.jarneoforge/build/libs/aquaguard-neoforge-<version>.jarfabric/build/libs/aquaguard-fabric-<version>.jar
To build a single loader, use its subproject task, e.g. ./gradlew :fabric:build. Run a dev server
with ./gradlew :forge:runServer (or :fabric: / :neoforge:). The DB drivers (SQLite, HikariCP,
MySQL, night-config) are shaded into each jar — no extra installation required.
Bug reports, feature requests, and pull requests are welcome. See CONTRIBUTING.md for guidelines.
All Rights Reserved © denfry. See LICENSE for details.