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.

As this project is in its early beta stage, the official demo/beta builds are published here, on GitHub (check Releases and Packages sections) and on Modrinth to be easily accessible by the community.

Using links below you can find the latest builds on both platforms:

• Latest GitHub release
• Latest Modrinth release

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

• 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

1. Clone the repository:

git clone https://github.com/yourusername/paperchat.git

cd paperchat

2. Configure environment variables:

# Create environment file
cp .env.example .envv

NOTE: Edit the .env file to set your desired settings.

3. Start with Docker Compose:

# Run the cloud container
docker-compose up --build



# Or build yours and then run
docker-compose up --buildd

• Java 21 or higher
• Gradle 9.0 or higher
• PaperMC server 1.21+

1. Configure and build the plugin:

gradle wrapper --gradle-version 9.0
./gradlew clean buildd

2. Copy to server:

cp build/libs/paperchat-*.jar /path/to/your/minecraft/server/plugins/

3. Configure environment variables:

export PAPERCHAT_API_KEY="your-api-key-here"

export PAPERCHAT_PROVIDER="google"

export PAPERCHAT_MODEL="gemini-2.5-flash"

4. Start your Minecraft server

• Google's Models
• OpenAI Models
• Hack Club (no API key required, handles multiple models internally)

PaperChat is configured through either environment variables:

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.

Send a message to AI:

/paperchat 
n>

Available options:

 - /paperchat  : Ask a question to the AI
 - /paperchat history : View your conversation history
 - /paperchat clear : Clear your conversation history
story
y

• paperchat.use - Allows players to use the /paperchat command

1. Player sends command with target message
2. AI processes the message with conversation history context
3. Response is formatted and sent to the sender
4. Both the original message and AI response are stored in conversation history

PaperChat follows clean architecture principles:

src/main/java/lt/domax/paperchat/
├── domain/
│   ├── ai/            # AI provider abstractions and registry
│   ├── chat/          # Chat services and session management
│   ├── config/        # Configuration management
│   └── player/        # Player data management
├── infrastructure/
│   └── commands/      # Minecraft command implementations
├── resources/
│   ├── plugin.yml     # Plugin metadata
│   └── META-INF       # Java metadata
│       └── services/  # Service provider configurations
└── PaperChat.java     # Main plugin class
lugin class

• Abstract Provider Class: Base for all AI implementations
• Service Provider Interface: Automatic registration using Java SPI
• Registry Pattern: Centralized provider management
• Graceful Fallback: Automatic error recovery and user-friendly messages

1. Create provider class:

@AIProvider("yourprovider")

public class YourProvider extends Provider {
     // Implementation
}}

2. Add to service registry: Add your provider class name to::

src/main/resources/META-INF/services/lt.domax.paperchat.domain.ai.Provider

1. Visit Google AI Studio
2. Create a new API key
3. Set PAPERCHAT_API_KEY to your key
4. Set PAPERCHAT_PROVIDER to google
5. Set PAPERCHAT_MODEL to your desired Gemini model (e.g., gemini-2.5-flash)

1. Visit OpenAI API
2. Create a new API key
3. Set PAPERCHAT_API_KEY to your key
4. Set PAPERCHAT_PROVIDER to openai
5. Set PAPERCHAT_MODEL to your desired OpenAI model (e.g., gpt-5)

1. Visit Hack Club's AI
2. Set PAPERCHAT_API_KEY to be empty (any other value will simply be ignored)
3. Set PAPERCHAT_PROVIDER to hackclub

Plugin fails to load or compile:

• Check Java version (requires 21+)
• Verify API key and/or model is set correctly
• Check server logs for detailed error messages

AI responses not working:

• Verify API key has sufficient credits/quota
• Check network connectivity from server
• Review timeout settings

Performance issues:

• Reduce PAPERCHAT_MAX_HISTORY value
• Increase PAPERCHAT_TIMEOUT for slow networks
• Monitor API usage and rate limits

1. Fork the repository
2. Create a feature branch
3. Make your changes following the existing architecture
4. Submit a pull request

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

• API keys are never logged or exposed
• All AI requests use HTTPS
• Player data is stored locally only
• No external data transmission beyond AI providers

For issues, feature requests, or questions:

• Open an issue on GitHub
• Review configuration options

Built with modern Java practices for reliable Minecraft server integration. Happy chatting!