GamesAI

Installation

Run the following command in the MCDR console to install the plugin:

!!MCDR plugin install games_ai

Alternatively, get it from the MCDR Plugin Repository and place it in your plugin directory.

If you choose to install manually, install the Python packages openai and requests first:

pip install openai requests

Usage

Type !!gamesai anywhere to display all available features of this plugin.

You can also use !!ask directly to ask the AI questions, chat, or ask it to do things for you.

Type !!data for information about database commands.

Configuration

The default configuration file structure is as follows:

{
  "prefix": "[GamesAI]",
  "permission": 3,
  "max_history": 10,
  "all_ai": {
      "<Your AI ID>":{
          "prompt": "You are a mature, reliable Minecraft bot tool named \"GamesAI\".",
          "ai_name": "[GamesAI]",
          "base_url": "<Your API Base URL>",
          "ai_model": "<Your AI Model>",
          "api_key": "<Your API Key>",
          "thinking": false
      }
    },
  "default_ai": "<Your AI ID>"
  }

Below is a brief introduction to each parameter:

1.prefix

Type: str

Default: [GamesAI]

The plugin name used as a prefix in replies. May include Minecraft formatting codes.

2.permission

Type: int

Default: 3

The minimum permission level required to execute commands like !!data. See the MCDR Permission Documentation.

3.max_history

Type: int

Default: 10

The maximum number of conversation turns retained per player. Unrelated to the public database. Set to 0 to completely disable history.

4.all_ai

Type: dict

Default: see file

All AI configuration entries, consisting of multiple sub-dictionaries. Each sub-dictionary represents one AI model, and its key serves as the plugin's internal AI_ID.

prompt: Use this option to write a system prompt for each AI. Use > xxx.md to point the prompt to the config/games_ai/prompt/xxx.md file (any file type is supported).

ai_name: Similar to prefix, but set per model. May include Minecraft formatting codes.

base_url, ai_model, api_key: Same as previous related configuration, but now set per model.

thinking: Enable or disable the model's thinking/reasoning mode. Defaults to false when omitted. Do not enable this for models that do not support a thinking mode — it may cause errors.

5.default_ai

Type: str

Default: <Your AI ID>

The model used when a player simply uses !!ask. Should be one of the keys in the all_ai dictionary (i.e. the plugin's internal AI_ID). An incorrect value will prevent !!ask from working properly.

Tools, Skills & Custom Tools

Tools

The GamesAI plugin provides many built-in tools, listed in the table below. If you want more tools, you can submit a suggestion or use Custom Tools.

Skills

The Skills system lets you write instruction files to guide how the AI handles specific tasks — such as whitelist management, fake player control, and more.

Skills files are stored in config/games_ai/skills/ as Markdown (.md) files. To register a skill, edit config/games_ai/skills/skills.json. The following is an example configuration (whitelist.md and player.md are example filenames only — they are not built-in files):

[
    {
        "file": "whitelist.md",
        "description": "Read this skill before managing the whitelist"
    },
    {
        "file": "player.md",
        "description": "Read this skill before controlling fake players"
    }
]

• file — the skill filename (relative to the skills folder).
• description — a short hint shown to the AI, explaining when to read this skill.

When a skill is registered, it appears in the AI's system prompt. The AI can then use the read_skills tool to read the full contents of any skill file before performing related tasks.

Custom Tools

Customize tools by editing the config/games_ai/tools/tools.py file.

Let's start by looking at the default content:

from mcdreforged.command.command_source import CommandSource
from games_ai.games_ai_tool import register_tool

@register_tool(description="My Custom Tool")
def my_custom_tool(source: CommandSource, ai_prefix: str):
    return "Tool execution completed"

As you can see, the structure is very simple.

Now I'll show you how to build a real tool. Let's use searching baidu.com as an example.

@register_tool(description="Search Minecraft Wiki for relevant information. Do not use this method to search for non-Minecraft content. If the search results page is returned, you can browse that page first and then perform a more precise query.", tr_key="searching_minecraft_wiki", parameters={
    "type": "object",
    "properties": {
        "query": {
            "type": "string",
            "description": "The search term, e.g. the name of an item, mob, or game mechanic."
        }
    },
    "required": ["query"]
})
def search_minecraft_wiki(source: CommandSource, ai_prefix: str, query: str):
    source.reply(f'{ai_prefix}{source.get_server().rtr("games_ai.tools.searching_minecraft_wiki", query=query)}')
    lang = source.get_server().get_mcdr_language()
    if lang == "en_us":
        search_url = f"https://minecraft.wiki/?search={query}"
    else:
        search_url = f"https://zh.minecraft.wiki/?search={query}"
    response = requests.get(search_url)
    if response.status_code == 200:
        return f"Search results for {query}:\n{response.content.decode('utf-8')}"
    else:
        return "Unable to access Minecraft Wiki for searching."

@register_tool(description="Search Baidu")

@register_tool(description="Search Baidu", parameters={
    "type": "object",
    "properties": {
        "query": {
            "type": "string",
            "description": "The search term"
        }
    },
    "required": ["query"]
})

def search_baidu(source: CommandSource, ai_prefix: str, query: str):

def search_baidu(source: CommandSource, ai_prefix: str, query: str):
    ...
    return ...

import requests
from games_ai.games_ai_tool import register_tool

@register_tool(
    description="Use Baidu to search for information on the internet. Use this tool when you need real-time info, news, encyclopedia knowledge, etc.",
    parameters={
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "The keyword or question to search for on Baidu"
            }
        },
        "required": ["query"]
    }
)
def search_baidu(source, ai_prefix: str, query: str):
    source.reply(f'{ai_prefix}Searching Baidu: {query}...')

    try:
        url = "https://www.baidu.com/s"
        headers = {
            "User-Agent": (
                "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
                "AppleWebKit/537.36 (KHTML, like Gecko) "
                "Chrome/120.0.0.0 Safari/537.36"
            )
        }
        response = requests.get(url, params={"wd": query}, headers=headers, timeout=10)

        if response.status_code != 200:
            return f"Baidu search failed, HTTP status code: {response.status_code}"

        # Extract plain text from page (strip HTML tags)
        import re
        text = response.text
        # Remove script and style tag contents
        text = re.sub(r'<script[^>]*>.*?</script>', '', text, flags=re.DOTALL | re.IGNORECASE)
        text = re.sub(r'<style[^>]*>.*?</style>', '', text, flags=re.DOTALL | re.IGNORECASE)
        # Remove HTML tags
        text = re.sub(r'<[^>]+>', '', text)
        # Collapse extra whitespace
        text = re.sub(r'\s+', ' ', text).strip()

        # Truncate long content (keep first 3000 characters, suitable for AI context)
        max_len = 3000
        if len(text) > max_len:
            text = text[:max_len] + "\n...(content truncated)"

        return f"Baidu search results for 「{query}」:\n{text}"

    except requests.Timeout:
        return "Baidu search request timed out. Please try again later."
    except Exception as e:
        return f"Baidu search error: {str(e)}"

What's New

Version 0.5.6

1. !!ask No-History Mode

Added --no-history / -n flag. When used, old conversation history is not read into the prompt, but the current conversation is still saved for future use. Can be combined with -m. This feature was suggested by william-song-shy (William Song).

• !!ask -n <content> — Ask without history
• !!ask --no-history <content> — Same as above
• !!ask -n -m <model> <content> — Specify model without history

2. max_history Can Disable History

max_history can now be set to 0, which completely disables the history feature — no conversation history is read or saved.

3. Graceful Tool Error Handling

Removed raise e from the tool execution error handler. Tool call failures no longer terminate the entire conversation thread. The AI now receives the error message and can attempt alternative approaches.

4. get_all_pos / remove_pos File Check Fix

Fixed a crash in get_all_pos and remove_pos tools when the where2go plugin is installed but its data file hasn't been created yet. Both tools now check for file existence before attempting to read.

Acknowledgements & Disclaimer

Special thanks to the Wanghai Commune server for providing the foundation for testing this plugin.

Special thanks to william-song-shy (William Song) for suggesting the !!ask no-history mode.

All content generated by AI (LLM) models is unrelated to this plugin.

All consequences arising from custom tools are unrelated to this plugin.

Sponsorship & Contributors

Sponsorship address: Afdian

Those who sponsor GamesAI will appear in the following sponsor list (currently no sponsors):

License

MIT License, Copyright (c) 2026 yello