GameQuery Fabric 模组(适用于 Minecraft 1.21.6)
GameQuery 是一款用于 Minecraft 1.21.6 的 Fabric 模组,它在端口 25566 上暴露了一个本地查询接口,允许外部脚本和应用程序获取实时游戏数据或控制某些游戏内操作。这非常适合 AI 智能体、机器人、自动化脚本或与自定义工具的集成。
? 安装
- 为 Minecraft 1.21.6 安装 Fabric Loader。
- 安装 Fabric API。
- 将 GameQuery 模组的 JAR 文件放入
.minecraft/mods文件夹中。 - 启动游戏。
- 查询服务器将自动在
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 端口暴露内部游戏数据。仅建议在受信任的单人游戏或仅限局域网的环境中使用此模组。切勿将端口暴露给互联网。
你是这个资源的作者?登录后可认领此资源。
相似资源
一个用于收集生物掉落物的多区块模组。
显示你正在注视的方块的信息。(适用于 Minecraft 1.16+ 的 Hwyla/Waila 分支)
查看物品与配方
在游戏画面角落显示附近世界地形、玩家、生物和实体的地图。可创建路径点,帮助你找到标记过的位置。
使用 JavaScript 编辑配方、添加自定义物品、编写世界事件!
适用于 MC 1.18+ 的 Effekseer 加载器
评论 0
登录后参与评分
还没有评论,来抢沙发吧