AquariusProxy Plugin Template

AquariusProxy is a headless Minecraft proxy and bot — a fork of ZenithProxy.

This repository is a template for building AquariusProxy plugins: drop-in jars that add your own modules and commands to the proxy without rebuilding it.

It is the AquariusProxy counterpart to rfresh2's ZenithProxyExamplePlugin. The example modules/commands are the same demos, ported to the com.aquarius API.

📖 The companion guide lives on the wiki: Plugin Development →

---

What's in the example

Class	Demonstrates
ExamplePlugin	The plugin entrypoint — @Plugin metadata + registering modules/commands/config
ExampleConfig	A JSON-backed config POJO
ExampleModule + ExampleCommand	A tick-loop module toggled by a command
ExampleESPModule + ExampleESPCommand	A packet handler that edits outbound entity metadata (glowing ESP)
ExampleWanderModule + ExampleWanderCommand	Driving Baritone pathfinding from a module

---

Installing plugins

Plugins are only supported on the java release channel (not linux/native — the native image can't load jars at runtime).

1. Put plugin jars in the plugins folder next to the AquariusProxy launcher (it's created on first launch).
2. Restart AquariusProxy. Plugins load at startup — hot-reloading is not supported.
3. Plugin configs are written to plugins/config/<plugin_id>.json.

Verify loaded plugins in the proxy console with the plugins command.

---

Creating a plugin

Use this repository as a template (green Use this template button on GitHub, or clone it).

Prerequisites

• JDK 25 (the same JDK AquariusProxy is built with — required so compilation can run AquariusProxy's bundled annotation processor). The Gradle toolchain will auto-provision it if missing.
• The AquariusProxy "fat" jar to compile against — the exact AquariusProxy.jar the launcher runs. This is how you get the API; AquariusProxy is not published to a public Maven repository.

Get the API jar one of two ways:

# Option A — copy it from your AquariusProxy install
cp /path/to/your/install/AquariusProxy.jar libs/AquariusProxy.jar

# Option B — download the latest release
gh release download --repo aquariusnetwork9/AquariusProxy --pattern 'AquariusProxy.jar' --dir libs

The build looks for libs/AquariusProxy.jar by default. To point somewhere else (e.g. straight at your install dir):

./gradlew build -Paquarius_jar=/path/to/AquariusProxy.jar

New plugin checklist

1. Edit gradle.properties:
   • plugin_name — display name, also the jar file name (e.g. MyPlugin)
   • plugin_id — unique id (e.g. my-plugin). Must start with a lowercase letter and contain only lowercase letters, numbers, or dashes (-)
   • mc — MC version of AquariusProxy you compile for (e.g. 1.21.4)
   • maven_group — your Java package (e.g. com.github.yourname)
2. Move the sources from org.example to your maven_group package:
   • src/main/java/org/example → src/main/java/<your package>
   • Also move the template package under src/main/templates
   • Doing this in IntelliJ (drag/refactor) updates all imports for you
3. Edit ExamplePlugin.java — update the @Plugin annotation, or replace it with your own main class.

Plugin structure

Every plugin has a main class that implements AquariusProxyPlugin and is annotated with @Plugin:

@Plugin(
    id = BuildConstants.PLUGIN_ID,
    version = BuildConstants.VERSION,
    description = "My AquariusProxy plugin",
    authors = {"you"},
    mcVersions = {BuildConstants.MC_VERSION} // or mcVersions = "*" for any version
)
public class MyPlugin implements AquariusProxyPlugin {
    @Override
    public void onLoad(PluginAPI pluginAPI) {
        var config = pluginAPI.registerConfig("my-plugin", MyConfig.class);
        pluginAPI.registerModule(new MyModule());
        pluginAPI.registerCommand(new MyCommand());
    }
}

The @Plugin annotation is processed at build time to generate the zenithproxy.plugin.json metadata file the proxy reads — you don't write it by hand.

Plugin API

onLoad hands you a PluginAPI to register your:

• Configs — registerConfig(fileName, ConfigClass.class) returns the loaded instance (auto-saved/loaded as JSON).
• Modules — registerModule(...). Modules listen to events, can be toggled, and register packet handlers.
• Commands — registerCommand(...). Commands run from the terminal, in-game chat, and Discord.

Module and Command are written exactly as in the AquariusProxy source. The best references are the proxy's own modules and commands:

• Modules
• Commands

Building

./gradlew build

The plugin jar is written to build/libs/<plugin_name>.jar. Copy it into your proxy's plugins folder.

Testing

./gradlew run

This launches AquariusProxy from the ./run directory with your freshly built plugin installed into run/plugins. The first run walks you through the normal proxy setup (account, target server, etc.). You can also just copy the built jar into an existing install's plugins folder and restart.

---

Porting a ZenithProxy plugin

A plugin jar built for ZenithProxy will not load on AquariusProxy as-is. AquariusProxy renamed the whole API package com.zenith.* → com.aquarius.* (including ZenithProxyPlugin → AquariusProxyPlugin), so a compiled ZenithProxy plugin references classes that don't exist here, and the loader requires AquariusProxyPlugin.

Porting is mechanical, though — the API shape is identical:

1. Replace imports com.zenith. → com.aquarius. (and ZenithProxyPlugin → AquariusProxyPlugin).
2. Compile against AquariusProxy.jar instead of ZenithProxy (this template already does).

External imports (com.github.rfresh2.*, com.mojang.brigadier.*, org.geysermc.mcprotocollib.*, net.kyori.*) stay the same.

---

How this template builds

Unlike the upstream example, this template does not depend on rfresh's zenithproxy.plugin.dev Gradle convention plugin (there is no AquariusProxy equivalent). It is self-contained:

• It compiles compileOnly + annotationProcessor against the AquariusProxy fat jar. The fat jar bundles every API/transitive class and the @Plugin annotation processor (auto-registered via SPI), so no Maven publishing or transitive resolution is needed.
• BuildConstants is generated from src/main/templates via a Gradle Copy/expand task.
• The Shadow plugin packages the final jar (and can bundle/relocate any dependencies you implementation-declare).

---

License

Dedicated to the public domain under CC0 1.0, same as the upstream ZenithProxy example. Do whatever you want with it.