Features

• /ask command — Ask AI questions directly from the Minecraft chat
• Multi-model support — Switch between AI models via -m / --model flags
• Multi-profile configuration — Define multiple AI backends (OpenAI, custom endpoints, etc.) with independent API keys, prompts, and base URLs
• Async execution — AI requests run off the main thread, never freezing the server
• Compatible with any OpenAI-compatible API — Works with OpenAI, local LLMs (Ollama / LM Studio), or self-hosted endpoints
• Auto-generated config — First run creates a default config/games_ai/config.json, no manual setup needed
• Multi-language support — Server-wide language switching (en_us / zh_cn), live reload without restart
• Conversation history — Per-player, per-model history with configurable length and auto-trimming
• Context-sensitive help — /gamesai help adapts to your current command context
• Debug mode — Toggle request logging for troubleshooting API issues

Usage

Commands

/ask <your question>
/ask -m <model_name> <your question>
/ask --model <model_name> <your question>

Example

/ask Explain how to build a redstone clock
/ask -m deepseek-v3 Write a haiku about creepers

Management Commands

💡 Type /gamesai help in-game for clickable command suggestions.

Configuration

On first run, a default config is created at:

<minecraft_dir>/config/games_ai/config.json

Default Structure

{
  "prefix": "[GamesAI]",
  "max_history": 10,
  "lang": "en_us",
  "all_ai": {
    "example_ai": {
      "prompt": "You are a helpful assistant in Minecraft.",
      "ai_name": "[GamesAI]",
      "base_url": "<Your Base URL>",
      "ai_model": "<Your AI Model>",
      "api_key": "<Your API Key>"
    }
  },
  "default_ai": "example_ai"
}

Adding Multiple AI Profiles

{
  "prefix": "[GamesAI]",
  "max_history": 10,
  "lang": "en_us",
  "all_ai": {
    "gpt4o": {
      "prompt": "You are a Minecraft expert.",
      "ai_name": "[GPT-4o]",
      "base_url": "https://api.openai.com/v1",
      "ai_model": "gpt-4o",
      "api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
    "local_llama": {
      "prompt": "You are a friendly Minecraft assistant.",
      "ai_name": "[Llama3]",
      "base_url": "http://localhost:11434/v1",
      "ai_model": "llama3",
      "api_key": "ollama"
    }
  },
  "default_ai": "gpt4o"
}

Tip: For Ollama / local models, set api_key to "ollama" as a placeholder.

Conversation History

The mod maintains per-player, per-model conversation history in memory.

Project Structure

src/
├── main/java/io/github/pengzixuan30/gamesai/
│   ├── GamesAI.java                  # Mod entry point — init & config loading
│   ├── command/
│   │   └── GamesAICommands.java      # Command registration & execution
│   ├── config/
│   │   ├── GamesAIConfig.java        # Config data model (AI profiles)
│   │   └── GamesAIConfigManager.java # Config file read/write (JSON)
│   ├── help/
│   │   └── GamesAIHelp.java          # Context-sensitive help system
│   ├── openai/
│   │   └── GamesAIRequestAI.java     # OpenAI API client & response handling
│   └── translations/
│       └── GamesAITranslations.java  # I18n translation engine (JSON + GSON)
├── main/resources/
│   ├── fabric.mod.json               # Fabric mod metadata
│   ├── assets/games_ai/icon.png      # Mod icon (optional)
│   └── assets/games_ai/lang/         # Translation files (en_us, zh_cn, ...)
├── client/java/io/github/pengzixuan30/gamesai/client/
│   └── GamesAIClient.java            # Client-side entry (placeholder)
├── build.gradle                      # Gradle build configuration
├── gradle.properties                 # Minecraft & dependency versions
└── settings.gradle                   # Gradle plugin repositories

Architecture Overview

flowchart LR
    Config[json] -->|load| Manager[GamesAIConfigManager]
    Manager --> Model[GamesAIConfig]
    Model --> Main[GamesAI]
    Main --> Cmd[GamesAICommands]
    Cmd -->|/ask| API[GamesAIRequestAI]
    API -->|HTTP| OpenAI[OpenAI API]
    Main --> History[(allHistory)]
    History --> API
    API --> History
    API -->|response| Cmd
    Cmd -->|sendMessage| Player[Minecraft Player]

Building

Prerequisites

• JDK 21 (or newer)
• Gradle Wrapper (included — use gradlew / gradlew.bat)

Build

# Clone the repository
git clone https://github.com/pengzixuan30/GamesAI.git
cd GamesAI

# Build the mod
./gradlew build

The compiled .jar will be at: build/libs/games_ai-0.1.1-Fabric-xxx.jar

Run in Dev Environment

./gradlew runClient    # Launch Minecraft client with the mod
./gradlew runServer    # Launch a local test server

Quick Version Migration

For minor patch upgrades within 1.21.x, edit gradle.properties:

minecraft_version=<new_version>
yarn_mappings=<new_version>+build.X
fabric_version=<api_version>+<new_version>

Then rebuild and test. Check fabricmc.net/develop for recommended version combinations.

Server Notes

• History is in-memory only — server restart clears all conversations
• API costs — each /ask makes one HTTP request to the configured endpoint

Version Compatibility

More versions coming soon.

License

This project is licensed under the MIT License.

Acknowledgements

• FabricMC — Modding framework
• openai/openai-java — The official Java library for the OpenAI API
• Minecraft is a trademark of Mojang / Microsoft. This mod is not affiliated with Mojang.