AquaGuard

Server-side audit logging, investigation, and rollback for modded Minecraft servers.

Русская версия · Documentation · Issues · Releases · Modrinth

Important

AquaGuard is under active development. Every release ships Fabric, NeoForge, and Forge builds for Minecraft 1.21.1 from the same source and with the same version number.

Know what happened. Fix it safely.

AquaGuard records server activity in SQLite or MySQL without running database writes on the server thread. Moderators can inspect a block, trace a player's actions, preview a rollback, and restore damaged areas from in-game commands.

The project focuses on modded servers: block entities, container changes, NBT, automated actors, and third-party integrations belong in the same audit trail as vanilla events.

What AquaGuard covers

	Capability	What it gives administrators
🛡️	Audit trail	Block changes, containers, signs, entities, sessions, explosions, and natural events (fire spread, leaf decay, falling blocks). Chat, command, and item pickup/drop logging is planned.
🔎	In-world inspection	Point at a block to see recent actions, timestamps, coordinates, states, and stored details.
↩️	Rollback and restore	Preview and reverse changes by player or area, then re-apply a rollback when required.
📦	NBT-aware history	Preserve container contents, signs, furnaces, item components, and supported block-entity state.
🗄️	SQLite or MySQL	Start with an embedded database or connect multiple servers to managed MySQL/MariaDB.
⚙️	Asynchronous pipeline	Queue writes off-thread, batch inserts, and run lookups through separate read workers.
🚨	Operations tools	Discord grief alerts, automatic pruning, CSV evidence exports, and database health status.
🧩	Integration API	Let other mods submit attributed custom actions through AquaGuardAPI.

Platform status

Platform	Minecraft	Status	Notes
Fabric	1.21.1	Supported	Fabric Loader 0.16.9+ and Fabric API
NeoForge	1.21.1	Supported	NeoForge 21.1.93+
Forge	1.21.1	Supported	Forge 52.0.16+

AquaGuard is server-side. Players do not need to install it on their clients. It also works in singleplayer and on LAN worlds.

Quick start

1. Download the jar for your loader from Modrinth or Releases: aquaguard-fabric-<version>.jar, aquaguard-neoforge-<version>.jar, or aquaguard-forge-<version>.jar.
2. On Fabric, also install Fabric API. NeoForge and Forge need no other mods.
3. Place the jar in the server's mods/ directory.
4. Start the server once.
5. Review config/aquaguard/aquaguard-common.toml and restart after changing it.

SQLite works without external setup. For a server network, configure MySQL or MariaDB before the first production start.

Commands at a glance

All administrative commands use /ag. Permissions follow the vanilla operator levels configured by the command.

Command	Purpose
/ag inspect	Toggle block inspection mode
/ag area ...	Get the selection wand and set area corners for lookups and rollbacks
/ag lookup ...	Search by player, radius, position, action, or result page
/ag rollback ...	Preview or reverse recorded changes
/ag restore ...	Re-apply changes from a previous rollback
/ag status	Check log count, database state, and active settings
/ag export ...	Export player history for review or moderation evidence
/ag prune <time>	Permanently remove expired history

See the command reference for syntax, filters, time formats, and examples.

How it stays responsive

flowchart LR
    A[Server events and mod integrations] --> B[Normalized log entry]
    B --> C[Bounded write queue]
    C --> D[Dedicated database worker]
    D --> E[(SQLite or MySQL)]
    E --> F[Async lookup workers]
    F --> G[Inspect, lookup, rollback, export]

Loading

• Event listeners enqueue records instead of waiting for the database.
• The database worker drains entries in transaction batches.
• Repeated values use a string pool to reduce storage overhead.
• Lookups run through a separate executor and return CompletableFuture results.
• Rollback work is scheduled in bounded batches to avoid one large server-tick spike.

Configuration

The generated TOML separates database, logging, maintenance, alerts, and telemetry settings. Every logging category can be disabled independently.

[database]
type = "SQLITE"

[maintenance]
auto_prune_enabled = false
max_age_days = 60

[telemetry]
enabled = false

Read the configuration guide before enabling MySQL, Discord alerts, or telemetry.

Telemetry

Telemetry is off by default and sends nothing until a server owner sets telemetry.enabled = true and a telemetry.endpoint. When enabled, AquaGuard reports every interval_minutes a random install ID, the mod, Minecraft, loader, Java and OS versions, the database type, player counts, enabled features, and per-action counts. It never sends player names, UUIDs, chat, or coordinates.

Developer API

Other mods can write attributed actions through the public API:

AquaGuardAPI.logCustomAction(
    player,
    level,
    position,
    "yourmod_machine_operation",
    "input=4; output=1; energy=1200"
);

Custom action names should be stable and prefixed with the source mod ID. These entries support auditing and lookup; the convenience API does not register custom rollback logic. See the API guide for the contract.

Build from source

Requirements: Git and JDK 21.

git clone https://github.com/denfry/AquaGuard.git
cd AquaGuard

./gradlew :common:test releaseBundle

The three loader JARs are written to build/releaseArtifacts/. The release process is described in CONTRIBUTING.md.

Documentation

• Commands
• Configuration
• Developer API
• Contributing
• Documentation index

Contributing

Use the issue templates for reproducible bugs and scoped feature requests. Before opening a pull request, read CONTRIBUTING.md and run the checks for each loader you changed.

License

Released under the MIT License. Copyright © denfry.