Skip to content

Home

Jump to bottom
Sasha Baranov edited this page Jun 12, 2026 · 1 revision

Aicraft Wiki (local source)

This file is gitignored. Copy sections into your GitHub Wiki as separate pages. Suggested page names are marked with <!-- PAGE: Name -->.

Home

Aicraft is a Paper plugin that adds private AI chat to Minecraft — in-game and in the browser. Players talk to any OpenAI-compatible API (Ollama, Unsloth, vLLM, OpenAI, etc.). Conversations are saved per player with optional web access to history.

Author: SushiMC
Current version: 1.1.0
Supported platforms: Paper 1.21+ and 26.x

Quick links

Features

  • Private in-game chat — only the player sees messages
  • OpenAI-compatible API (/v1/chat/completions)
  • Local models (Ollama, Unsloth, LM Studio, vLLM) and cloud APIs
  • Per-player chat IDs (Chat #1 is always your chat #1)
  • Saved chat history (SQLite or Postgres)
  • Web UI with account linking
  • LuckPerms-friendly daily chat limits

Requirements

Component Requirement
Server software Paper 1.21+ or 26.x (not Spigot)
Java 21 (Paper 1.21.x) or 25 (Paper 26.x)
AI backend Any OpenAI-compatible chat API
Web UI (optional) Open port 8765 (or your configured port)

Installation

  1. Download the latest aicraft-x.x.x.jar from Releases or Modrinth.
  2. Place the JAR in your server's plugins/ folder.
  3. Start or restart the server.
  4. On first run, Aicraft creates:
File Purpose
plugins/Aicraft/config.yml AI endpoint and model settings
plugins/Aicraft/web.yml Web UI, database, rate limits
plugins/Aicraft/aicraft.db SQLite database (auto-created)
  1. Edit config.yml (and web.yml if using the web UI).
  2. Restart the server. Reloading may not restart the web server or database pool.

See Configuration for all options.

Configuration

Aicraft uses two config files in plugins/Aicraft/:

File What it controls
config.yml AI provider, model, system prompt, timeouts
web.yml Web UI, database, rate limits, account linking

Restart the server after editing either file.

config.yml

endpoint: "http://localhost:11434/v1/chat/completions"
api-key: "ollama"
model: "llama3.2"
system-prompt: "You are a helpful assistant inside a Minecraft server. Keep replies concise and game-friendly."
timeout-seconds: 120
max-history-messages: 20
Option Description
endpoint Full URL to /v1/chat/completions
api-key Sent as Authorization: Bearer …. Use any placeholder (e.g. ollama) if auth is not required
model Model name your provider expects
system-prompt Prepended to every new chat
timeout-seconds HTTP timeout for AI requests
max-history-messages Max user + assistant messages kept in the AI context window

web.yml

enabled: true
port: 8765
bind-address: "0.0.0.0"

database:
  type: sqlite
  sqlite-file: "aicraft.db"
  postgres:
    host: "localhost"
    port: 5432
    database: "aicraft"
    username: "aicraft"
    password: ""

rate-limits:
  default-chats-per-day: 50

linking:
  link-code-expiry-minutes: 2
  web-session-days: 30
Option Description
enabled Enable or disable the web UI
port Web server port (default 8765)
bind-address 0.0.0.0 = all interfaces; 127.0.0.1 = localhost only
database.type sqlite or postgres
database.sqlite-file SQLite filename inside plugins/Aicraft/
database.postgres.* Postgres connection settings
rate-limits.default-chats-per-day Default max new chats per player per 24h
linking.link-code-expiry-minutes How long /ailink codes stay valid
linking.web-session-days How long a linked web session lasts

See Database and AI Providers for setup details.

Commands

Command Permission Description
/newchat aicraft.use Start a new private chat. Shows your Chat #N ID.
/ai <message> aicraft.use Send a message in your active chat
/endchat aicraft.use End your active chat (history is saved)
/reopenchat <id> aicraft.use Reopen one of your saved chats by number
/ailink aicraft.web Get a link code for the web UI

Chat IDs

Each player has their own numbered chats. /reopenchat 1 opens your chat #1, not another player's.

Chat numbers increment per player: first chat is #1, second is #2, and so on. The same numbers appear in the web UI.

Example in-game session

/newchat
→ Chat #3 started. Only you see this conversation.

/ai what should I build in survival?
/ai give me a compact starter base layout

/endchat

/reopenchat 3
/ai add a storage room to that plan

/endchat

Notes

  • /ai only works while a chat is active (/newchat or /reopenchat).
  • Messages are private — other players cannot see your chat or the AI's replies.
  • Starting a new chat with /newchat counts toward your daily limit (see Permissions and Rate Limits).

Web UI

The web UI lets players browse chat history, start new chats, and continue conversations from a browser.

Enabling

In web.yml:

enabled: true
port: 8765
bind-address: "0.0.0.0"

Open http://<server-ip>:8765 (replace with your server IP and port).

Linking your Minecraft account

  1. Open the web UI and enter your Minecraft username.
  2. Join the server and run /ailink.
  3. A code is shown only to you in-game. Enter it on the web page.

Codes expire after link-code-expiry-minutes (default: 2 minutes). If it expires, start over from step 1.

What players can do

  • View all saved chats
  • Start new chats from the browser
  • Continue previous conversations
  • See the same chat numbers as in-game

Admin tips

Goal Suggestion
Remote access Open/forward the web port in your firewall
HTTPS Set bind-address: "127.0.0.1" and put nginx/Caddy in front
Disable web only Set enabled: false — in-game chat and DB still work
Security Do not expose the web UI publicly without HTTPS and access controls

Permissions and Rate Limits

Permission nodes

Permission Default Description
aicraft.use true In-game commands: /newchat, /ai, /endchat, /reopenchat
aicraft.web true /ailink for web UI account linking
aicraft.chats.unlimited op No daily cap on new chats
aicraft.chats.<n> — e.g. aicraft.chats.50 = 50 new chats per 24h

How rate limits work

  • Limits apply to new chats created in a rolling 24-hour window — not individual messages.
  • /newchat and creating a chat on the web both count.
  • Reopening an existing chat with /reopenchat does not count as a new chat.

Priority

  1. aicraft.chats.unlimited → no cap
  2. Highest matching aicraft.chats.<n> permission
  3. Fallback: rate-limits.default-chats-per-day in web.yml

LuckPerms examples

/lp group default permission set aicraft.chats.10 true
/lp group vip permission set aicraft.chats.100 true
/lp group staff permission set aicraft.chats.unlimited true

Players creating chats from the web while offline use LuckPerms cached permissions when LuckPerms is installed.

Database

Aicraft stores chat history, web sessions, and link requests in a database. The database is always initialized — even when the web UI is disabled.

SQLite (default)

Zero setup. On first startup:

  1. Creates plugins/Aicraft/aicraft.db
  2. Runs migrations automatically
  3. Creates all required tables
database:
  type: sqlite
  sqlite-file: "aicraft.db"

You never need to run SQL manually.

Postgres

Create the database on your Postgres server first, then configure:

database:
  type: postgres
  postgres:
    host: "localhost"
    port: 5432
    database: "aicraft"
    username: "aicraft"
    password: "your-password"

Migrations run automatically on startup.

Schema overview

Table Purpose
chats Chat sessions per player (with per-player chat number)
chat_messages Messages (user, assistant, system)
web_sessions Linked web UI sessions
link_requests Pending /ailink verification codes
schema_version Migration tracking

Backups

For SQLite, stop the server (or ensure no writes) and copy plugins/Aicraft/aicraft.db. For Postgres, use your normal backup tooling.

AI Providers

Aicraft uses the OpenAI chat completions format: POST /v1/chat/completions with a JSON body containing model and messages.

Ollama (recommended for local)

On the same machine as Minecraft:

ollama pull llama3.2
ollama serve
endpoint: "http://localhost:11434/v1/chat/completions"
api-key: "ollama"
model: "llama3.2"

If Ollama runs on another machine, replace localhost with that host's IP.

OpenAI

endpoint: "https://api.openai.com/v1/chat/completions"
api-key: "sk-your-key-here"
model: "gpt-4o-mini"

Other compatible providers

Any service exposing /v1/chat/completions works, including:

  • Unsloth
  • vLLM
  • LM Studio
  • Groq
  • OpenRouter

Set endpoint to the full completions URL, api-key to your key (or a placeholder if unused), and model to the provider's model name.

Docker note

If the AI server runs in Docker and Minecraft runs on the host, localhost from the Minecraft server's perspective may not reach the container. Use the container's published IP/port or host.docker.internal where applicable.

Troubleshooting

In-game

"No active chat. Start one with /newchat."

Run /newchat or /reopenchat <id> before /ai.

"Daily chat limit reached"

The player hit their 24h new-chat cap. Grant aicraft.chats.<n>, aicraft.chats.unlimited, or raise default-chats-per-day in web.yml.

"Failed to reach AI endpoint"

  • Confirm the AI server is running (ollama serve, etc.)
  • Check endpoint includes the full path: /v1/chat/completions
  • If the model is on another machine, use that IP instead of localhost
  • Check firewall / Docker networking between Minecraft and the AI host

HTTP 404 / model not found

  • Pull the model: ollama pull <model>
  • Match model in config.yml exactly to the provider's name

Slow or timed-out replies

  • Increase timeout-seconds in config.yml
  • Use a smaller/faster model

Web UI

Page won't load

  • Confirm enabled: true in web.yml
  • Check firewall / port forwarding for your configured port
  • Look for Aicraft web UI running on http://... in server logs

"/ailink" — no pending web link

Enter your username on the web UI first, then run /ailink within the expiry window.

Link code expired

Start over: enter username on the web → /ailink in-game → enter code quickly.

Database

Postgres connection errors

  • Verify the database exists and credentials in web.yml are correct
  • Ensure the Minecraft server can reach the Postgres host and port

SQLite locked errors

Rare with normal use. Restart the server. Avoid copying the .db file while the server is running.

FAQ

Does Spigot work?

No. Aicraft requires Paper 1.21+ or 26.x.

Do other players see my AI chat?

No. All in-game messages are sent only to you.

Is the .db file created automatically?

Yes. SQLite creates plugins/Aicraft/aicraft.db on first startup with all tables.

Can I disable the web UI but keep chat history?

Yes. Set enabled: false in web.yml. The database still saves in-game chats.

Do /reopenchat and web history share the same data?

Yes. In-game and web chats use the same database and per-player chat numbers.

Does reopening a chat count toward the daily limit?

No. Only new chats (/newchat or "New chat" on the web) count.

Can I use this without LuckPerms?

Yes. Rate limits fall back to default-chats-per-day in web.yml. LuckPerms is optional for per-group limits.

What Minecraft versions are supported?

Paper 1.21 through 26.x. Same JAR for all supported versions.

Changelog

1.1.0

  • Web UI on configurable port
  • SQLite database (default) and Postgres support
  • Auto-run database migrations
  • Per-player chat IDs with /reopenchat
  • Account linking via web UI + /ailink
  • LuckPerms-compatible daily chat limits (aicraft.chats.<n>)
  • Chat history synced between in-game and web

1.0.0

  • Initial release
  • Private in-game AI chat (/newchat, /ai, /endchat)
  • OpenAI-compatible API support (Ollama, local models, cloud)
  • config.yml for endpoint, API key, and model

Wiki maintained by SushiMC. For bugs and feature requests, open an issue on the repository.

Clone this wiki locally