DOCSEARCHbyAlgolia
Submit Docs

Mindcraft Framework

repository·develop·Indexed 26 days ago

https://github.com/mindcraft-bots/mindcraft

A framework for creating Minecraft bots powered by Large Language Models (LLMs) using Mineflayer. Mindcraft enables agents to perform complex tasks, write code, and interact with the Minecraft world through natural language and automated goal-seeking. It supports multiple LLM providers including OpenAI, Google Gemini, Anthropic, xAI, DeepSeek, and Ollama, and provides integration options via Docker and ViaProxy for connecting to various server versions.

Tokens
8K
Snippets
20
Records
63
Agent score
90%

What's inside Mindcraft

  1. Configure ViaProxy for offline servers

    develop

    To connect to an offline Minecraft server, follow these steps:

    1. Start the ViaProxy service.
    2. Locate the generated configuration file at services/viaproxy/viaproxy.yml.
    3. Edit the file and set the target-address to your Minecraft server's address.
    4. Update your settings.js file to point the host and port to the ViaProxy endpoint:
    "host": "host.docker.internal",
"port": 25568,

  2. Create new tasks

    develop

    To define a new task, specify the initial_inventory and the target item.

    • Construction Tasks: You must also set a new blueprint. Reference existing blueprints in tasks/construction_tasks/.
    • Custom Evaluation: If your task does not rely on inventory or blueprint checks, you must implement a custom evaluation function. You can use CookingTaskValidator in src/agent/tasks/cooking_tasks.js as a template for designing your own validator.

  3. Run a basic Minecraft task manually

    develop

    To run a simple task manually, ensure Minecraft is installed and a supported version is launched. Open the world to LAN on port 55916. You can then execute a task using node main.js by specifying a task path and a task ID.

    Task JSON Format Example:

    {
    "gather_oak_logs": {
      "goal": "Collect at least four logs",
      "initial_inventory": {
        "0": {
          "wooden_axe": 1
        }
      },
      "agent_count": 1,
      "target": "oak_log",
      "number_of_target": 4,
      "type": "techtree",
      "max_depth": 1,
      "depth": 0,
      "timeout": 300,
      "blocked_actions": {
        "0": [],
        "1": []
      },
      "missing_items": [],
      "requires_ctable": false
    }
}

    Key Fields:

    • initial_inventory: Items the bot starts with.
    • target: The item to be collected.
    • number_of_target: The quantity required for success.
    • timeout: Seconds before the agent leaves the game (default is 300).
    node main.js --task_path tasks/basic/single_agent.json --task_id gather_oak_logs

  8. Configure API Keys in keys.json

    develop
    Mindcraft requires API keys to communicate with LLM providers. You must rename keys.example.json to keys.json and provide at least one valid key. Supported providers include OpenAI, Google (Gemini), Anthropic, xAI, DeepSeek, Ollama (local), and others. The specific model used is determined by the agent profile (e.g., andy.json).

  9. Run Mindcraft in Docker

    develop

    To mitigate risks when using allow_insecure_coding: true, run Mindcraft in a Docker container.

    Note: If joining a local Minecraft server from inside Docker, set the host in settings.js to host.docker.internal.

    To build and run via CLI:

    docker build -t mindcraft . && docker run --rm --add-host=host.docker.internal:host-gateway -p 8080:8080 -p 3000-3003:3000-3003 -e SETTINGS_JSON='{"auto_open_ui":false,"profiles":["./profiles/gemini.json"],"host":"host.docker.internal"}' --volume ./keys.json:/app/keys.json --name mindcraft mindcraft

    Alternatively, use Docker Compose:

    docker-compose up --build

  10. Install and Run Mindcraft

    develop

    Follow these steps to set up and run the Mindcraft bot in a local Minecraft environment:

    1. Verify Requirements:
      • Minecraft Java Edition (v1.21.6 recommended, up to v1.21.11).
      • Node.js (v18 or v20 LTS recommended; avoid v24+).
      • An API key from a supported provider (e.g., OpenAI).
    2. Setup Files:
      • Download the latest release or clone the repository.
      • Rename keys.example.json to keys.json and populate it with your API keys.
    3. Install Dependencies:
      • Run npm install in the project directory.
    4. Launch Minecraft:
      • Start a Minecraft world and open it to LAN on port 55916.
    5. Run the Bot:
      • Execute node main.js from the project directory.
    npm install
node main.js

  11. Add new worlds to the Minecraft environment

    develop

    To use custom Minecraft worlds beyond the default Forest and Superflat worlds, follow these steps:

    1. Create the desired world in your version of Minecraft.
    2. Copy the world files into the server_data folder.
    3. Update the server.properties file, setting the level-name to match the name of your created world.

  12. Manage Microsoft accounts in ViaProxy

    develop

    To connect to 'online' Minecraft servers, you must manage accounts within the running ViaProxy container.

    1. Start the ViaProxy container.
    2. Attach to the container using: docker attach mindcraft-viaproxy-1.
    3. Use the account command to manage identities:
    • account list: List all available accounts.
    • account add microsoft: Add a Microsoft account (follow the interactive instructions).
    • account select <id>: Select an account by its ID (use account list to find IDs).
    • account remove <id>: Remove an account.
    • account deselect: Deselect the current account to return to offline mode.

    Security Warning: If you use a Microsoft account, your access token is stored in saves.json. Never share this file, as it allows others to join servers using your identity.

    To detach from the container without stopping it, press CTRL-P followed by CTRL-Q.