Table of Contents (click to expand)

• GamesAI for MCDReforged
  • Installation
  • Quick Start
    • 1. First start: let the plugin install what it needs
    • 2. Configure an AI
    • 3. Check the connection and ask the first question
    • 4. Where the conversation lives (and how to clear it)
    • 5. Give the AI abilities: tools and skills (optional)
    • 6. Let it drive a Mineflayer bot (optional)
    • 7. Link several instances into a cluster (optional)
    • 8. Everyday maintenance
    • Command reference
  • Technical Documentation
  • The Role of AI in This Project
  • Acknowledgements & Disclaimer
  • Sponsorship & Contributors
  • License

Installation

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

!!MCDR plugin install games_ai

Requirements: Python 3.12 or newer and MCDReforged 2.15.0 or newer (the manifest declares mcdreforged >= 2.15.0; MCDR runs the plugin on its own interpreter). Node.js 18+ with npm is needed only when you enable the Mineflayer bot.

---

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

If you choose to install manually, the plugin takes care of its Python packages itself: on the first start it looks for openai, requests and websockets, installs whatever is missing with pip (the machine's own pip configuration first, the Aliyun PyPI mirror as a second attempt) and reloads itself when that worked. You only have to step in when both attempts fail -- the log then prints the exact command to run, in the python -m pip form:

python -m pip install openai requests websockets

!!MCDR plugin install games_ai cannot pre-install anything either: the package list lives inside the plugin (games_ai/requirements.txt), and MCDR only reads a requirements.txt at the plugin root before loading it. Every install route therefore starts with the packages missing, and the plugin repairs them itself on the first start (see PIM); use the manual command above only when both pip attempts fail, and run !!MCDR plugin reload games_ai afterwards to bring the plugin back.

Coming from an older release needs no manual config edit: the old mineflayer_bot.websocket.url is migrated to the top-level websocket.uri on the first load. In a cluster, a node running an older build cannot obey the hub's update order, so install the new build by hand once on every instance (!!MCDR plugin install -U -y games_ai). Only the hub needs a reachable port, and a wss:// uri can only be a client.

GamesAI maintains itself: the plugin updates its own file (cluster-aware, verified download, rollback on failure) and repairs its own Python packages. Both are described in PIM: the plugin's own installer.

Quick Start

1. First start: let the plugin install what it needs

Put the plugin into plugins/ and start the server (if it is already installed, !!MCDR plugin reload games_ai is enough). On the first start it checks its three Python packages (openai, requests, websockets) and installs whatever is missing with pip -- the machine's own pip configuration first, the Aliyun PyPI mirror as a second attempt -- then reloads itself:

Installing the missing Python package(s) with pip: ...
[deps] ...
Dependencies installed; reloading the plugin...
Dependencies are ready; the plugin is fully loaded again (openai, requests, websockets)

While that runs, the plugin is loaded but idle: it registers no command and starts neither the bot nor the cross-server link. If both attempts fail, the log prints Could not install: ... together with the command to run by hand (python -m pip install openai requests websockets); run it, then !!MCDR plugin reload games_ai. See PIM: the Python package manager and Missing Python Packages.

2. Configure an AI

Open config/games_ai/config.json (created on the first start) and fill in one all_ai entry plus default_ai:

{
  "all_ai": {
    "<Your AI ID>": {
      "prompt": "You are a mature, reliable Minecraft assistant.",
      "ai_name": "[GamesAI]",
      "base_url": "<Your API Base URL>",
      "ai_model": "<Your AI Model>",
      "api_key": "<Your API Key>",
      "extra_body": {}
    }
  },
  "default_ai": "<Your AI ID>"
}

• all_ai holds one entry per model; the key you choose is the plugin's internal AI ID.
• base_url, ai_model and api_key are your provider's OpenAI-compatible endpoint, model name and key.
• ai_name is what the AI prefixes its answers with (Minecraft formatting codes work).
• extra_body is passed to the provider untouched -- for a thinking model, for example {"thinking": {"type": "enabled"}}.
• default_ai must be exactly one of the all_ai keys: it is the model a plain !!ask uses.
• Optional context_window overrides the window that automatic context management uses for that model.

Keep long prompts out of the file by writing "prompt": "> my_prompt.md": the text is then read from config/games_ai/prompt/my_prompt.md.

Apply the change with !!gamesai reload. !!gamesai config get <key> and !!gamesai config set <key> <value> handle simple top-level keys, but config set refuses the complex all_ai and mineflayer_bot blocks and does not resolve dotted keys, so edit those in the file. Every key is documented in Configuration.

3. Check the connection and ask the first question

!!gamesai speedtest asks every configured model at <base_url>/models and prints the latency (!!gamesai speedtest <model> tests a single one). Then simply talk to it:

!!ask Hello! Are you there?

!!ask is open to every player. Around it: !!ask -n <content> answers without the conversation history, !!ask -f <content> (alias --forced) merges the question into the round that is already running, !!ask switch <model> hands the conversation to another model (the old one summarizes it first), !!ask stop stops everything you have in flight and keeps what the round already wrote, and !!ask context [player] / !!ask context --all show how much context is in use. See AI Request Pipeline and Stopping a running round.

4. Where the conversation lives (and how to clear it)

Every conversation is written into a chat_history table of config/games_ai/database/public_database.db -- the same file as !!data, a separate table -- after every finished round, and restored on every plugin load. A reload, an update, a restart or removing the plugin therefore no longer loses it.

!!gamesai clear deletes your own conversation; !!gamesai clear <name> deletes another player's (it needs the configured permission level and stops that player's running round first); !!gamesai clearall deletes all of them (also permission-gated). See Conversation persistence.

5. Give the AI abilities: tools and skills (optional)

The plugin ships 27 built-in tools (world queries, public data, skills, the bot). Which ones a request is offered depends on the player's MCDR permission level and the configured permission, so a low-level player never sees the administrative ones at all.

• Your own tools: config/games_ai/tools/tools.py is created on the first start with a @register_tool skeleton. Add your functions there and run !!gamesai reload. See Tools.
• Skills: config/games_ai/skills/skills.json indexes the skill files the AI reads with read_skills; the AI can also write and maintain them itself. See Skills.

6. Let it drive a Mineflayer bot (optional)

Node.js 18+ and npm have to be installed on the server machine. Then set the credentials and start it:

!!aibot set username <Minecraft account name>
!!aibot set password <password>
!!aibot set auth microsoft
!!aibot join

!!aibot leave stops it again. In config.json the same settings live under mineflayer_bot: enabled, cycle_interval (how often the autonomous controller decides, 15 seconds by default) and bot.username / bot.password / bot.auth (microsoft, mojang or offline). The bot joins the cluster as a client instead of listening on a port of its own, and the server address is read from server.properties. Credentials are only read when the Node process (re)starts, so change them with !!aibot set and restart (!!aibot leave, then !!aibot join); !!gamesai config set refuses the whole mineflayer_bot block. See Mineflayer Bot.

7. Link several instances into a cluster (optional)

One instance becomes the hub (it owns the AI, the conversation history and the public database) and the others join it as clients that forward their players' commands; tools stay with each instance. Point every instance at the hub in the websocket block of config.json:

{
  "websocket": {
    "uri": "ws://<hub address>:8080",
    "force_server": false,
    "name": ""
  }
}

An instance that finds a GamesAI hub at that address becomes a client; one that finds nothing (and can bind the address) becomes the hub, while force_server insists on the hub role. Enrolment is per node: on the hub, !!gamesai node pending lists the waiting names and !!gamesai node token <name> issues a token; that instance joins with !!gamesai node claim <token>. websocket.name is derived from the instance directory when it is left empty. Cluster updates are ordered by the hub -- nodes first, hub last. The remaining keys (allow_app_id, token_ttl_hours, auto_enroll, identity_file) are documented in Configuration §6; the full picture is in Cross-server Linking and Cluster updates.

8. Everyday maintenance

• !!gamesai reload re-reads the configuration, the skills and the tools and restarts the bot when needed; the cross-server link keeps running. Changes to websocket.* need !!MCDR plugin reload games_ai (or !!gamesai node claim / node forget, which rebuild the link), because the link is built on load. See Hot Reload.
• !!gamesai check looks for a new release and refreshes the context-window table; in a cluster the hub coordinates it. The plugin updates its own file (verified download, rollback on failure) and repairs its own Python packages -- see PIM.
• !!gamesai debug toggles the full request log; !!gamesai debug thread lists the threads the plugin owns.
• !!data manages the public key/value database the AI can read.
• Something broken? Troubleshooting lists the log lines and what to do about them.

---

Command reference

Type !!gamesai for the in-game feature list (!!gamesai node … for cluster enrolment, !!aibot … for the bot); the tables below cover the most used commands.

Command	Description
!!gamesai clear	Clear your own chat history. It is stored in its own table of the public database file, and this deletes your row. !!gamesai clear <name> clears one other player's history instead and requires the configured permission level; a round that player still has in flight is stopped first.
!!gamesai clearall	Clear all players' chat history (the stored rows included).
!!gamesai reload	Reload the configuration, the skills and the tools and restart the bot; the cross-server link keeps running. See Hot Reload for details.
!!gamesai check	Check for plugin updates and force-refresh the context-window table. In a cluster this is executed on the hub, which starts an update round: the nodes install first, the hub last (see Cross-server Linking).
!!gamesai speedtest [model]	Test API server connection latency. If no model is specified, all models are tested.
!!gamesai config get <key>	Read a configuration value.
!!gamesai config set <key> <value>	Update a configuration value (auto type-adapts; automatically triggers Hot Reload).
`!!gamesai node <pending	token
`!!aibot join	leave`

---

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

Command	Description
!!ask <content>	Ask the AI a question, chat, or ask it to do something. <content> is what you want the AI to do or the question you want to ask.
!!ask -n <content>	Ask the AI without using conversation history (current conversation is still saved).
!!ask -f <content>	Force-ask without waiting: the request is merged into the round that is currently running (alias: --forced). See AI Request Pipeline & Chat Mechanism.
!!ask switch <model>	Switch the AI model for your current conversation (<model> is the AI_ID or nickname). The history is cleared and the old model summarizes it right before your next request, handing the summary to the new model. See Summary Hand-off on Model Switch.
!!ask stop	Immediately stop everything you have in flight: your running round (tool calls included), a running !!ask -n request and a task you delegated to the bot. What the round already wrote stays in the history -- only a tool call whose result never arrived is dropped; queued !!ask -f messages are kept and merged by your next round. See Stopping a running round.
!!ask context [player]	Show the context usage: model and window source, how much of the window is used, how many tokens are left before compression, the per-round sizes and the cache-hit rate. Without a player name it shows your own. See Context Inspection.
!!ask context --all	Sum the context usage of every player on the server, grouped by model (models with zero usage are not listed); hover for that model's totals since those conversations were created (they survive a reload and a restart). See Context Inspection.
!!ask compact	Compress the older history right now, ignoring the compression triggers. It is performed by the preflight of your next question, so the command itself never blocks. See Context Inspection.

---

Type !!data for information about database commands.

Command	Description
!!data write <key> <value>	Add a data entry to the public database. <key> must not contain spaces; <value> can be any string.
!!data add <key> <value>	Append <value> to an existing key in the public database. Creates a new key if it does not exist.
!!data del <key>	Delete a data entry from the public database, regardless of whether the key exists.
!!data read <key>	Read the value associated with a key from the public database.
!!data list	Read all entries in the public database.
!!data list keys	Read all keys in the public database.

---

Technical Documentation

The technical details live in docs/en_us/ — how a request is built and kept inside the window, what every configuration key does, how tools and skills work, how the bot is driven, and what to do when something fails.

Document	Contents
AI Request Pipeline	Request chain, the stateless !!ask -n, the !!ask switch hand-off, !!ask stop, automatic context management, per-user state
Configuration	Every key of config.json: prefix, permission, all_ai (incl. context_window), default_ai, mineflayer_bot, websocket (uri, force_server, allow_app_id, name, token_ttl_hours, auto_enroll, identity_file) and the self-update behaviour
Tools	The 27 built-in tools, writing your own in tools.py, registering tools from your own plugin, permissions and visibility
Skills	What skills are for, the built-in ones, skills.json, letting the AI write them, registering them from your own plugin
Example	A real server configuration end to end: config, six skills, 44 custom tools, a walkthrough round and the pitfalls
Mineflayer Bot	Prerequisites, commands, how it works, supported actions, bot control tools
Hot Reload	Triggering a reload, what happens during one, following it from your plugin
Cross-server Linking	Cluster roles, per-node enrolment, command routing, cluster updates, tool scope
PIM	The plugin's own installer: self-update and Python package repair
Troubleshooting	!!ask errors, bot errors, logging & debugging
Testing	Installing pytest, running the whole suite, one module or one test by name, what each part of tests/ holds, and what a run needs
Architecture	The package tree by role, how the parts may depend on each other, the dependency gate, and where a new module goes
Changelog	Release notes of recent releases

The same documents in other languages: 简体中文 · 繁體中文.

---

The Role of AI in This Project

GamesAI is an AI-powered plugin, and AI also plays an important role in how this project itself is maintained:

1. This README was originally typeset by the author (yello) and has since been fully revised by AI;
2. All translation files (lang/*.yml) are maintained by AI;
3. Logic checks before each release are performed by AI;
4. Issues reported for snapshot/development builds are investigated by AI;
5. GitHub issues and PRs are first triaged by AI before reaching the maintainer.

Acknowledgements & Disclaimer

Special thanks to WangHai Server for providing the foundation for testing this plugin.

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

Special thanks to ZhangZuoqian (张作乾) for suggesting the !!gamesai speedtest command.

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):

#	Sponsor	Amount	Date
-	-	-	-

License

MIT License, Copyright (c) 2026 yello