Skip to content
Allay

WikiAllay plugin

Architecture

#How a question flows

  1. A player asks. The plugin opens a stream to the backend, POST /api/v2/chat, and shows the live status.
  2. When the model needs something from the game, the backend sends a tool call.
  3. The plugin runs the tool on the server thread and posts the result back.
  4. The answer streams into the chat, with buttons.

The protocol is docs/protocol-v2.md in Allay Server. Change both sides together. When a backend has no v2, the plugin falls back to v1.

#Two modules

  • core holds everything that doesn't touch a game platform: the backend client, billing, languages, settings, the tool registry, items as the model reads them, the game's formulas, notes, goals, chest and inventory planners, and quotas. It never imports org.bukkit or net.minecraft.
  • spigot is the adapter for Spigot, Paper, and their forks: commands, events, windows, and the tools that read the world through Bukkit. Its entry point is Zygote.

A Fabric or NeoForge port would be another adapter next to spigot, not a second copy of the plugin.

#Rules the code keeps

  • Spigot API only, so one jar runs on Spigot and Paper.
  • Threads. Bukkit calls happen on the server thread; network calls never do.
  • Privacy. Tools see only the asker and the world around them. Other players reach the model only as the asker's locator bar shows them.
  • Operator tools are checked three times: the registry offers them only to operators, the backend client refuses them for anyone else, and the tool checks isOp() once more. Automation agents never get them.
  • Chest changes are planned in memory, checked, and written in one tick, or nothing moves.
  • Windows only show pictures: every click, drag, and hopper move on them is cancelled.
  • Secrets. The BYOK key and the license never reach the log or the chat.

The full map of files and every rule live in CLAUDE.md in the repository.

Next: Releasing