GameQuery

模组

· 作者 YeeticusFinch

适用于 Minecraft 1.21.6 的 Fabric 模组,在端口 25566 上暴露本地查询接口,允许外部脚本和应用程序获取实时游戏数据或控制某些游戏内操作

0 本站下载 0 关注 更新于 1 年前

需要前置:Fabric API

最新 1.0.2 · 1.21.6 · Fabric

一键开服(送7天)

GameQuery Fabric 模组(适用于 Minecraft 1.21.6)

GameQuery 是一款用于 Minecraft 1.21.6 的 Fabric 模组,它在端口 25566 上暴露了一个本地查询接口,允许外部脚本和应用程序获取实时游戏数据或控制某些游戏内操作。这非常适合 AI 智能体、机器人、自动化脚本或与自定义工具的集成。


? 安装

  1. 为 Minecraft 1.21.6 安装 Fabric Loader。
  2. 安装 Fabric API。
  3. 将 GameQuery 模组的 JAR 文件放入 .minecraft/mods 文件夹中。
  4. 启动游戏。
  5. 查询服务器将自动在 localhost:25566 上启动。

运行方式

每当您进入游戏(加入单人或多人世界)时,查询服务器将自动在 localhost:25566 上启动。


? 查询协议

查询以 JSON Lines 格式(每行一个 JSON 对象)发送到 localhost:25566。响应也以相同格式返回。

请求示例:

{ "type": "inventory" }

响应示例:

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

? 可用查询

inventory

获取玩家的物品栏内容。

{ "type": "inventory" }

返回:

{
  "inventory": {
    "items": [
      {
        "slot": 0,
        "type": "minecraft:diamond_sword",
        "name": "Super Fancy Sword",
        "count": 1,
        "damage": 17,
        "maxDamage": 990,
        "durability": 973,
        "enchanted": true
      },
      {
        "slot": 1,
        "type": "minecraft:diamond_shovel",
        "name": "My Favorite Spoon",
        "count": 1,
        "damage": 3,
        "maxDamage": 990,
        "durability": 987,
        "enchanted": true
      },
      ...
    ],
    "selected": 0 
  }
}

position

获取玩家当前位置和旋转角度。

{ "type": "position" }

返回:

{
  "position": {
    "x": 123.0,
    "y": 64.0,
    "z": 456.0,
    "yaw": 90.0,
    "pitch": 0.0
  }
}

blocks

获取玩家周围区块的三维数组。

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

可选参数:

range: 整数半径(默认值:5)

返回:

{
  "blocks": {
    "blocks": [
      {
        "x": -182,
        "y": 102,
        "z": 12,
        "type": "Block{minecraft:spruce_slab}"
      },
      {
        "x": -182,
        "y": 102,
        "z": 14,
        "type": "Block{minecraft:crafting_table}"
      },
      {
        "x": -182,
        "y": 103,
        "z": 12,
        "type": "Block{minecraft:air}"
      }
    ]
  }
}

entities

获取附近的实体及其数据。

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

可选参数:

range: 整数半径(默认值:10)

返回:

{
  "entities": {
    "entities": [
      {
        "type": "entity.minecraft.villager",
        "name": "Fletcher",
        "x": -182.30000001192093,
        "y": 103.0,
        "z": 15.667358260097222,
        "health": 20.0,
        "maxHealth": 20.0,
        "uuid": "2e290bd5-81f5-4166-bc25-806818f1d958",
        "hostile": false,
        "passive": true,
        "neutral": false,
        "isPlayer": false
      }
    ]
  }
}

world_info

获取关于世界的通用信息(维度、时间等)。

{ "type": "world_info" }

返回:

{
  "world_info": {
    "dimension": "minecraft:overworld",
    "time": 4154384,
    "isDay": true,
    "isRaining": false,
    "isThundering": false,
    "difficulty": "NORMAL"
  }
}

send_chat

向游戏内聊天发送消息。

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

返回:

{
  "result": {
    "success": true,
    "message": "Sent: Hello World!"
  }
}

drop_item (待实现)

从物品栏丢弃一个物品。

按槽位:

{ "type": "drop_item", "slot": 3 }

按物品名称:

{ "type": "drop_item", "name": "minecraft:stone" }

rotate

旋转玩家的视角。

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

返回:

{
  "result": {
    "success": true,
    "message": "Rotated player to yaw: 90.0\u00b0, pitch: 0.0\u00b0",
    "yaw": 90.0,
    "pitch": 0.0
  }
}

point_to_entity

旋转玩家视角以指向具有特定 UUID 的实体(提示:entities 查询会返回 UUID)。此功能会在 100 格范围内搜索该 UUID 的实体,并将准星指向该实体的中心(实体高度的一半)。

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

返回:

{
  "result": {
    "success": true,
    "message": "Pointed to entity: Fletcher",
    "entityName": "Fletcher",
    "entityType": "entity.minecraft.villager",
    "distance": 2.93,
    "yaw": 28.57,
    "pitch": 12.7,
    "entityX": -182.30000001192093,
    "entityY": 103.0,
    "entityZ": 15.667358260097222
  }
}

point_to_xyz

旋转玩家视角,使准星指向目标坐标。

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

如上例所示,坐标可以接受整数和浮点数。

响应示例:

{
  "result": {
    "success": true,
    "message": "Pointed to location: 42.0 69.0 -42.2",
    "distance": 232.45,
    "yaw": 256.06,
    "pitch": 8.81
  }
}

get_screen_pos (开发中)

获取特定物品栏槽位的屏幕位置。屏幕位置以像素为单位返回。此功能仍在开发中,请谨慎使用。

{ "type": "get_screen_pos", "slot": 5 }

响应示例:

{
  "result": {
    "x": 223,
    "y": 179
  }
}

get_block

获取玩家所在世界中特定坐标处的方块及其一些其他信息。

{ "type": "get_block", "x": 42, "y": 69, "z": 42 }

响应示例:

{
  "type": "Block{minecraft:chest}",
  "contents": []
}

left_click

执行普通左键点击

{"type": "left_click"}

示例响应(如果准星指向方块):

{
  "result": {
    "success": true,
    "message": "Attacked block at class_2339{x=-190, y=115, z=110}"
  }
}

示例响应(如果准星指向实体):

{
  "result": {
    "success": true,
    "message": "Attacked entity: Armor Stand"
  }
}

right_click

执行普通右键点击

{"type": "right_click"}

示例响应:

{
  "result": {
    "success": true,
    "message": "Right-clicked entity: Armor Stand (result: class_9859[])"
  }
}

select_slot

通过槽位编号选择快捷栏中的槽位(从 0 开始,因此包含 0-8 之间的数字)。

{"type": "select_slot", "slot":1}

示例响应:

{
  "result": {
    "success": true,
    "message": "Selected hotbar slot 1"
  }
}

hotbaar

返回玩家快捷栏中的物品。

{"type": "hotbar"}

示例响应:

{
  "hotbar": {
    "items": [
      {
        "slot": 0,
        "type": "minecraft:iron_sword",
        "name": "Iron Sword",
        "count": 1
      },
      {
        "slot": 1,
        "type": "minecraft:water_bucket",
        "name": "Water Bucket",
        "count": 1
      },
      {
        "slot": 2,
        "type": "minecraft:bow",
        "name": "Bow",
        "count": 1
      },
      {
        "slot": 3,
        "type": "minecraft:stone_pickaxe",
        "name": "Stone Pickaxe",
        "count": 1
      },
      {
        "slot": 4,
        "type": "minecraft:stone_axe",
        "name": "Stone Axe",
        "count": 1
      },
      {
        "slot": 5,
        "type": "minecraft:spruce_boat",
        "name": "Spruce Boat",
        "count": 1
      },
      {
        "slot": 6,
        "type": "minecraft:cobblestone_slab",
        "name": "Cobblestone Slab",
        "count": 2
      },
      {
        "slot": 7,
        "type": "minecraft:carrot",
        "name": "Carrot",
        "count": 36
      },
      {
        "slot": 8,
        "type": "minecraft:cobblestone",
        "name": "Cobblestone",
        "count": 52
      }
    ]
  }
}

open_container

打开准星所指的容器

{"type": "open_container"}

示例响应(如果准星处有容器):

{
  "result": {
    "success": true,
    "message": "Interacted with block at class_2339{x=-190, y=115, z=110} (result: class_9860[swingSource=CLIENT, itemContext=class_9858[wasItemInteraction=true, heldItemTransformedTo=null]])"
  }
}

示例响应(如果没有容器):

{
  "result": {
    "success": true,
    "message": "Interacted with block at class_2339{x=-193, y=114, z=109} (result: class_9859[])"
  }
}

(ps. 很抱歉这种情况仍然显示 success=true,我将在后续版本中修复此问题)

attack

使用主手当前选中的物品攻击准星所指的目标。

{"type": "attack"}

示例响应:

{
  "result": {
    "success": true,
    "message": "Attacked entity: Sheep",
    "uuid": "44a7eb0a-ddde-43c3-873c-594a94aa1cd1"
  }
}

shoot_bow

从快捷栏中选择一把弓,并向目标坐标或实体射击,对静止目标的射程精度可达 114 格。 可选的 overshoot 参数,用于增加额外的射程(即比目标多射出多少格距离)

{"type": "shoot_bow", "x": 42, "y": 69, "z": 42}
{"type": "shoot_bow", "x": 42, "y": 69, "z": 42, "overshoot": 5}
{"type": "shoot_bow", "entity": "44a7eb0a-ddde-43c3-873c-594a94aa1cd1"}
{"type": "shoot_bow", "entity": "44a7eb0a-ddde-43c3-873c-594a94aa1cd1", "overshoot": 3}

示例响应:

{
  "result": {
    "bow_slot": 2
  }
}

? Python 客户端示例

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]]:
        """向 Minecraft 客户端发送查询并返回响应。"""
        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

# 用法示例:
if __name__ == "__main__":
    client = GameQueryClient()
    response = client.send_query({"type": "position"})
    print(response)

use_door

在准星指向的位置或指定坐标处打开或关闭门。如果定义了 state,则会将门设置为该状态(open = true,closed = false)。否则,门的状态将在当前状态的基础上切换为相反状态。

查询:

{"type":"use_door"}

响应:

{
  "result": {
    "result": "closed the door at class_2338{x=-178, y=104, z=14}"
  }
}

查询:

{"type":"use_door", "state":"closed"}

响应:

{
  "result": {
    "result": "door already closed"
  }
}

查询:

{"type":"use_door", "state":true}

响应:

{
  "result": {
    "result": "opened the door at class_2338{x=-178, y=103, z=14}"
  }
}

查询:

{"type":"use_door", "x":-178, "y":103, "z":14, "state":true}

响应:

{
  "result": {
    "result": "opened the door at class_2338{x=-178, y=103, z=14}"
  }
}

use_bed

尝试在指定位置的床上睡觉,或者在准星指向的床上睡觉(如果未定义位置)。

{"type": "use_bed"}
{"type": "use_bed",  "x":-172, "y":102, "z":19}

响应:

{
  "result": {
    "success": true,
    "result": "Player is now sleeping at class_2338{x=-172, y=102, z=19}"
  }
}

leave_bed

离开玩家当前正在睡觉的床(有时 use_bed 会导致玩家进入一种异常状态,使其无法正常离开床铺)

{"type": "leave_bed"}

?️ 安全警告

此模组通过开放的 TCP 端口暴露内部游戏数据。仅建议在受信任的单人游戏或仅限局域网的环境中使用此模组。切勿将端口暴露给互联网。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源