Alternate Account Finder

Description

Alternate Account Finder is a Minecraft plugin that attempts to identify accounts that have used the same IP address, helping server administrators detect and manage alternate (alt) accounts.

Supported Minecraft Versions

This plugin is supported on the Minecraft versions listed in minecraft-versions.json: currently 1.19.4, 1.21.11, 26.2 and 26.3 (Spigot and its forks). Every stable release is booted on a real server of each of these versions before it is published, and every build checks that the plugin only uses Bukkit API that exists on all of them. Other versions from 1.19.4 onwards are expected to work but are not tested. To support another version, add it to the file: both checks pick it up.

Installation

First Time Installation

1. Download the plugin from SpigotMC.
2. Place the jar in the plugins folder of your server.
3. Restart your server.

Usage

Documentation

• User Guide – Getting started and common scenarios
• Commands Reference – Complete list of all commands
• Configuration Guide – Detailed configuration options

Wiki & Additional Resources

• FAQ

Support

You can find the support Discord server here.

Experiencing a bug?

Please fill out a bug report here.

Already-reported bugs are listed here.

Contributing

• CONTRIBUTING.md
• CLAUDE.md – Repository guide for AI coding agents
• Notes for Developers

Testing

Verification Build

Linux:

./gradlew clean build

Windows:

.\gradlew.bat clean build

If you see BUILD SUCCESSFUL, the build has passed.

Unit Tests

The project has a JUnit 5 test suite under src/test/java/. The verification build above runs it, and it can also be run on its own:

Linux:

./gradlew test

Windows:

.\gradlew.bat test

Development

Test Server

A Dockerfile and a compose.yml are available to build and run a Spigot test server with the plugin installed.

The server is Spigot 1.20.4 on Java 17, built with BuildTools when the image is built. That version is not one of the supported versions, so this server does not reproduce the setup releases are tested on. Building the image also builds the plugin from the working tree with ./gradlew build, which runs the unit tests, so a failing test stops the image build.

Setup with Docker Compose

1. Build and start the test server: docker compose up --build

The compose file builds the image from the Dockerfile in this repository and publishes port 25565. Without --build, docker compose up builds the image only when it does not exist yet; after that it keeps starting the existing image, which contains the plugin as it was when that image was built.

Setup with Docker

1. Build the test server image: docker build -t aaf-test-server .
2. Run the test server: docker run -p 25565:25565 aaf-test-server

Run the build step again after changing the plugin; the run step only starts the image that already exists.

Stopping the Test Server

Press Ctrl+C. If the server was started in the background, run docker compose down when Docker Compose was used, or docker stop <container-id> otherwise.

Neither file mounts a volume, so the plugin's data folder (the H2 database and ip-encryption.key) exists only inside the container. docker compose down removes the container and that data with it, and so does docker compose up --build when the rebuilt image differs from the one the container was created from, because Compose then replaces the container. Each docker run starts a new container with an empty data folder, so the plugin generates a new key and starts an empty database.

Authors and Acknowledgements

Developers

Name	Main Contributions
Daniel Stephenson	Creator
Ren Binden	v2

License

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

You are free to use, modify, and distribute this software, provided that:

• Source code is made available under the same license when distributed.
• Changes are documented and attributed.
• No additional restrictions are applied.

See the LICENSE file for the full text of the GPL-3.0 license.

Project Status

This project is in active development.

bStats

You can view the bStats page for the plugin here.

Usage reporting

Usage reporting is on by default: when the plugin is enabled, and each time a player uses one of its commands, it sends its name, its version and the command's name to the author's trace server at https://trace.danielstephenson.dev, so it is known which plugins are actually in use. Commands run from the console or a command block are not reported, and neither is one another plugin runs other than as a player. Nothing about players, worlds or IP addresses is sent, and nothing typed after a command. Repeated uses of a command within a minute are sent as one event carrying how many there were, rather than one event each. The plugin prints one line on every startup saying whether reporting is on and, if not, why.

Each event also carries a random server ID (the server-id line in plugins/trace/config.yml) so servers can be counted rather than events. It identifies no person, account or IP address; delete the line to get a new one.

To turn it off:

• for this plugin only: usage-reporting.enabled: false in plugins/AlternateAccountFinder/config.yml
• for every plugin on the server that reports to trace: enabled: false in plugins/trace/config.yml (created on first start; plugins never turn it back on)
• for the whole server process: the environment variable TRACE_USAGE_REPORTING=off or DO_NOT_TRACK=1

Details: https://danielstephenson.dev/usage-reporting

Roadmap

• Planned Features
• Planned Improvements

Changelog

See CHANGELOG.md for a history of changes.