PaperChat - AI-Powered Minecraft Plugin

PaperChat is a Minecraft server plugin that integrates AI language models directly into Minecraft. It allows players to send messages to AI assistants and get answers quickly, creating natural conversation experiences powered by Google Gemini and OpenAI models, with the ability to add your own!

Built for PaperMC servers, PaperChat maintains conversation history per player and provides a seamless bridge between Minecraft players and modern AI capabilities.

Project Philosophy

PaperChat follows the "run it yourself" philosophy. By requiring your own AI API credentials and local deployment, you get:

• No Rate Limits - Your API keys, your usage quotas
• Complete Privacy - Player conversations never leave your infrastructure
• Full Control - Customize AI behavior, system prompts, and response filtering
• No Dependencies - No external services beyond the AI providers themselves

Features

• Multi-Provider AI Support: Automatic registration of Google Gemini and OpenAI providers with easy extensibility
• Persistent Conversation History: Per-player chat sessions with configurable history limits
• Smart Error Handling: User-friendly error messages with automatic response recovery
• Configurable System Prompts: Define AI behavior and response formatting rules
• Input Validation: Character limits
• Asynchronous Processing: Non-blocking AI requests to maintain server performance
• Docker Ready: Complete containerized deployment with Minecraft server bundled in

Configuration

PaperChat is configured through either environment variables:

Variable	Description	Value
PAPERCHAT_API_KEY	Your AI provider API key	your-api-key (required only by your provider. If an AI provider does not require an API key, you can leave this blank)
PAPERCHAT_MAX_HISTORY	Max number of past requests to be saved per player	Conversation history limit
PAPERCHAT_PROVIDER	One of the available AI providers	AI provider (see more at Available Providers)
PAPERCHAT_MODEL	Any LLM that a provider provides	Model to use (required only by your provider. If an AI provider does not require a model to be set, you can leave this blank)
PAPERCHAT_TEMPERATURE	Response creativity (0.0-1.0)	0.7
PAPERCHAT_TIMEOUT	Request timeout in seconds	30
PAPERCHAT_MAX_INPUT_CHARACTERS	Maximum input message length	100
PAPERCHAT_MAX_OUTPUT_TOKENS	Maximum response length	4096
PAPERCHAT_SYSTEM_PROMPT	Custom system prompt for AI behavior	Your custom prompt (leaving empty uses default system prompt)

Or config.yml file located in the data/plugins/PaperChat/ directory:

ai:
  api-key: ""  # You can leave it empty if your provider does NOT require an API key
  provider: "google"
  model: "gemini-2.5-flash"  # You can leave it empty if your provider does NOT require a model parameter. However, at the moment this is only true for HackClub provider
  temperature: 0.7
  timeout: 30
  max-output-tokens: 4096
  system-prompt: ""  # Include your custom system prompt here

# NOTE: setting a system prompt here will overwrite the current prompt
# If left empty, the default system prompt will be used

# Chat Configuration
chat:
  max-history: 5
  max-input-characters: 100

Configuration in config.yml matches the environment variables. If both are set, the environment takes precedence.