Comparator

> ### The AI agent built for Minecraft.

Github

Modrinth

Documentation

Build

Comparator brings a fully conversational AI agent to your Paper server; with multi-turn memory, built-in tools, and an API to extend it on your own.

---

Features

🤖 Conversational AI Agent

Embed a fully conversational AI agent directly into your Minecraft server. Comparator maintains context across messages for natural, coherent dialogue; not just one-shot responses.

🔧 Built-In Tools

The agent can to more than just chat. Comparator ships with several built-in tools the AI can invoke to give accurate, grounded answers:

| Tool | Description | |------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| | Player Info | Searches the web for up-to-date information, so the agent isn't limited to its training data | | Player Info | Retrieves the current date, helping the agent reason about how recent its knowledge is | | Player Info | Fetches the server's running Minecraft version so answers are version-accurate | | Player Info | Retrieves the player's surroundings, inventory, nearby entities, biome, game mode, and what they're looking at. This enables contextual in-game assistance |

🌐 Embedded Web Panel

Comparator includes a built-in web panel served directly from the plugin via an embedded server. It gives server admins a live view into conversations, tool runs, and registered tools with real-time updates. No separate deployment needed; just configure the host and port in `comparator.conf` and run `/comparator panel start` to launch it.

🧩 Extensible Tool API

Third-party plugins can register their own tools using the Comparator API. Defining a tool is as simple as annotating a function:

```kotlin @ToolFunction("give_item", "Gives an item to the requesting player") suspend fun giveItem( @ToolParameter("The item to give") item: String, context: ToolContext ): GiveResult { val player = context.bukkitPlayer ?: throw ToolException("No player context", null) // ... }

// Register during ToolRegistrationEvent event.registry.register(tool(::giveItem)) ```

The API handles parameter validation, type checking, serialization, and error reporting automatically. See the API docs for full details.

🔒 Designed for Responsible AI Use

Comparator was built with safety and transparency in mind. This sets it apart from plugins that simply wrap an AI API with no guardrails:

- Structured error handling — All commands and public chat interactions respect Bukkit permissions, giving server admins fine-grained control over who can use the agent and who can manage it. - Structured error handling — The agent's behavior, persona, and constraints are fully configurable. The default prompt explicitly instructs the agent to stay on-topic, avoid fabricating information, and flag when its knowledge may be outdated. - Structured error handling — Conversations are isolated per-player, per-console, and for public chat. A player cannot read or pollute another player's conversation history. - Structured error handling — Conversation history expires after a configurable period of inactivity, limiting unintended data retention. - Structured error handling — Tool inputs are validated against declared parameter types and constraints before execution. The agent cannot invoke a tool with malformed arguments. - Structured error handling — Each conversation runs through a bounded channel. If a player floods the agent with messages, excess requests are rejected gracefully rather than queued unboundedly. - Structured error handling — Tool failures are surfaced to the model as descriptive errors, not raw stack traces or internal state.

⚡ High-Performance, Non-Blocking Architecture

Built on Kotlin coroutines for fully non-blocking execution. AI requests, tool calls, and context operations never block the server thread, so the agent has no impact on server tick performance.

✨ Flexible AI Provider Support

Integrates with Ollama, supporting both cloud-hosted and self-hosted models. Configure your model, base URL, and optional API key in `comparator.conf`.

---

Installation

1. Download the plugin `.jar` from Modrinth or GitHub Releases 2. Place the `.jar` in your server's `plugins/` folder 3. Restart your server 4. Follow the quickstart guide to complete setup

---

Usage

Ask in private (DM-style): ``` /ask <prompt> ```

Mention in public chat: ``` @bot <prompt> ```

For full usage information, see the documentation.

---

Support

- Plugin Documentation - API Documentation - Discord - GitHub Issues

---

Contributing

Contributions are welcome!

1. Fork the repository 2. Create a feature branch: `git checkout -b feature/my-feature` 3. Commit your changes: `git commit -m "Add my feature"` 4. Push and open a Pull Request

Please follow the existing code style and include tests where applicable. For more details, see CONTRIBUTING.md.

---

Credits

- Main icon: *circuit* by Skena Grafis from The Noun Project (CC BY 3.0)