GameQuery - Minecraft Query Mod

GameQuery is a Fabric mod for Minecraft 1.21.6 that provides a local query interface on port 25566, enabling external scripts and applications to retrieve real-time game data or control specific in-game actions. This is perfect for AI agents, bots, automation scripts, or integration with custom tools.

🛠️ Installation

1. Install Fabric Loader for Minecraft 1.21.6
2. Install Fabric API
3. Place the GameQuery JAR file in the .minecraft/mods folder
4. Launch the game
5. The query server will automatically start on localhost:25566

📡 Query Protocol

Queries are sent to localhost:25566 in JSON line format (one JSON object per line). Responses are returned in the same format.

Example request:

{ "type": "inventory" }

Example response:

{ "inventory": { "slots": [...], "selected": 0 } }

📋 Available Queries

Inventory

Get the player's inventory contents.

{ "type": "inventory" }

Position

Get the player's current position and rotation.

{ "type": "position" }

Blocks

Get a 3D array of blocks around the player.

{ "type": "blocks", "range": 5 }

Entities

Get data about nearby entities.

{ "type": "entities", "range": 10 }

World Information

Get general world information (dimension, time, etc.).

{ "type": "world_info" }

Send Chat Message

Send a message to the in-game chat.

{ "type": "send_chat", "message": "Hello World!" }

Rotation

Rotate the player's view.

{
  "type": "rotate",
  "yaw": 90.0,
  "pitch": 0.0
}

Point to Entity

Rotate the player to point at an entity with a specific UUID.

{ "type": "point_to_entity", "uuid": "2e290bd5-81f5-4166-bc25-806818f1d958" }

Point to Coordinates

Rotate the player to point at specific coordinates.

{ "type": "point_to_xyz", "x": 42, "y": 69, "z": -42.2 }

Item Actions

• drop_item - Drop item from inventory
• select_slot - Select hotbar slot
• hotbar - Get items on hotbar

Environment Interaction

• left_click - Left click
• right_click - Right click
• open_container - Open container
• attack - Attack
• shoot_bow - Shoot bow
• use_door - Use door
• use_bed - Use bed
• leave_bed - Leave bed

🐍 Python Client Example

import socket
import json
from typing import Any, Dict, Optional

class GameQueryClient:
    def init(self, host="localhost", port=25566):
        self.host = host
        self.port = port

    def send_query(self, query: Dict[str, Any]) -> Optional[Dict[str, Any]]:
        """Send a query to the Minecraft client and return the response."""
        try:
            with socket.create_connection((self.host, self.port), timeout=5) as sock:
                query_json = json.dumps(query) + "\n"
                sock.sendall(query_json.encode('utf-8'))

                with sock.makefile('r', encoding='utf-8') as f:
                    response_line = f.readline()
                    return json.loads(response_line.strip())

        except socket.timeout:
            print(f"❌ Timeout connecting to {self.host}:{self.port}")
            return None
        except ConnectionRefusedError:
            print(f"❌ Connection refused to {self.host}:{self.port}")
            print("   Make sure Minecraft is running with the GameQuery mod loaded")
            return None
        except Exception as e:
            print(f"❌ Error: {e}")
            return None

# Example usage:
if name == "main":
    client = GameQueryClient()
    response = client.send_query({"type": "position"})
    print(response)

⚠️ Security Warning

This mod exposes internal game data through an open TCP port. Only run this mod in a trusted single-player environment or local network. Do not expose the port to the internet.