game
Drive a live Godot instance: query structure, modify state, invoke methods, send inputs, wait for conditions, freeze/step playtests, monitor signals, and act on UI.
Instructions
游戏桥接操作。安装/卸载: game_bridge_install, game_bridge_uninstall。P2-1 overrides 注入: install_override/uninstall_override (启动游戏前注入任意调试脚本到项目 autoload,如日志钩子/状态快照)。查询: game_query (ping, get_tree, find_nodes, get_node_properties, get_performance, get_viewport_info, take_screenshot)。写入: game_write (set_node_property, call_method)。输入: game_input (send_key, send_mouse_click, send_mouse_move, send_text, send_touch, send_drag, send_input_sequence 帧定时输入时间线)。等待: game_wait (wait_for_node, wait_for_property)。P2-4 确定性 playtest: game_playtest (playtest.seed 锁随机, playtest.fixed_delta 锁步长, playtest.step 单步推进, playtest.snapshot/restore 状态快照)。G1 control 层: playtest.freeze (冻结游戏循环,bridge 仍响应), playtest.unfreeze (解冻), playtest.step_until (条件满足/帧尽/wall 超时即停,结构化条件 {path,property,op,value}[] AND)。监控: monitor_start/stop/poll (属性时间线采样)。信号: watch_start/stop/poll (信号事件记录)。UI: find_ui_elements/click_button (UI元素发现+按钮点击)。
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | click_button: 按钮节点路径（和 text 二选一） | |
| port | No | game_bridge_install: 期望的起始监听端口(实际端口由游戏侧 env GODOT_MCP_BRIDGE_PORT 设起点,被占自动递增避让;此参数不影响行为,保留兼容)。实际端口见 ping 响应与实例 registry | |
| push | No | P3-6 watch_start/monitor_start: 启用 push 模式（事件/采样产生时主动推送 MCP notification，无需 poll）。client 需订阅 resources/subscribe 才能收到 | |
| text | No | click_button: 按钮文字（和 path 二选一） | |
| type | No | find_ui_elements: 按类型过滤（如 "Button"、"Label"） | |
| limit | No | find_ui_elements: 最大返回数（默认 200，上限 500） | |
| action | Yes | 操作类型 | |
| method | No | game_query/game_write/game_input/game_wait/game_playtest 的具体方法。game_query: ping, get_tree, find_nodes (支持 root 参数限定子树搜索范围,推荐绝对路径如 /root/Main;节点不存在时报错非静默全树), get_node_properties, get_node_layout, get_performance, get_viewport_info, take_screenshot, get_errors (查询游戏运行时错误,支持 since_seq 增量 + clear 读即焚), clear_errors (清空错误 buffer)。game_write: set_node_property, call_method (协程方法默认 fire-and-forget,返 {coroutine:true} 标记+说明;传 params.await_completion=true 走延迟响应等待返回值,长协程注意调大 timeout)。game_input: send_key, send_mouse_click (button 支持 int 1-9/left/right/middle), send_mouse_move, send_text, send_touch, send_drag, send_input_sequence (帧定时时间线,延迟响应)。game_wait: wait_for_node, wait_for_property。game_playtest: playtest.seed (锁全局 RNG,仅覆盖 randi/randf), playtest.fixed_delta (锁 physics 步长,delta=1/hz), playtest.step (单步推进 N 帧,走 coroutine 延迟响应), playtest.snapshot (快照场景树属性,不保信号/物理/已free节点), playtest.restore (从快照恢复属性)。G1 control 层: playtest.freeze (冻结 tree.paused), playtest.unfreeze (解冻), playtest.step_until (推进至 conditions 满足/帧尽/wall 超时,结构化条件 {path,property,op,value}[] AND,不引入 Expression) | |
| params | No | 方法参数。game_query: 因方法而异。get_errors {since_seq?:int(默认0,只返回 seq>since_seq 的), clear?:bool(默认false,查询后清空 buffer)}。game_write: set_node_property {path, property, value}, call_method {path, method, args}。call_method 默认只读白名单(get/has_*/get_meta 等),env GODOT_MCP_BRIDGE_EXTRA_METHODS=method1,method2 可扩展(含写方法如 take_damage);EXTRA_METHODS_BLOCKLIST(free/queue_free/set_script/call/emit_signal 等)是不可覆盖硬底线。args 按方法声明类型自动强转(传 [1,2,3] 给 Vector3 参数会正确转换)。方法不存在时返回 did-you-mean 建议。response 含 undoable=false(call 不可 undo)。game_input: send_key {key, pressed}, send_mouse_click {x, y, button, pressed}, send_mouse_move {x, y}, send_text {text}, send_touch {x, y, pressed, index}, send_drag {x, y, index, relative, speed}, send_input_sequence {timeline:[{at_frame:1-600(开窗后第N帧),type:action|key|mouse_click|mouse_move|touch|drag,...事件参数}], settle_frames?:int(0-600), wall_budget_ms?:int(1000-50000), 事件≤256}(action 字段 name/pressed/strength?,其余 type 字段同各 send_*;frozen 下自动开窗播放+完成 refreeze)。game_wait: wait_for_node {path}, wait_for_property {path, property, value}。game_playtest: playtest.seed {seed:int}, playtest.fixed_delta {hz:int}, playtest.step {frames:int(1-60)}, playtest.snapshot/restore 无参数。G1 control: playtest.freeze/unfreeze 无参数, playtest.step_until {conditions:[{path:String,property:String,op:String(==/!=/</>/<=/>=),value:标量/几何}], max_frames?:int(1-600,默认600), wall_budget_ms?:int(1000-50000,默认30000)} | |
| pattern | No | find_ui_elements: 名称/文字匹配模式（Godot match 语法） | |
| timeout | No | game_query/game_write/game_input/game_wait: 超时时间（毫秒，默认 10000）。game_wait 的 timeout 用作整个轮询窗口的总预算（在窗口内反复探测直到条件成立）。send_input_sequence 延迟响应,timeout 自动放宽至 wall_budget+10s(上限 65000) | |
| node_path | No | monitor_start: 要监控的节点路径（如 /root/Player） | |
| godot_path | No | 覆盖 Godot 二进制路径（可选，优先于项目配置和环境变量） | |
| max_events | No | watch_start: 最大记录事件数（默认 1000，最大 5000） | |
| properties | No | monitor_start: 要监控的属性名列表（如 ["position", "health"]） | |
| interval_ms | No | game_wait 专用：轮询探测间隔（毫秒，默认 200，范围 50-2000）。仅 wait_for_node/wait_for_property 生效 | |
| signal_name | No | watch_start: 要监听的信号名（如 "pressed"、"health_changed"） | |
| project_path | No | Godot 项目目录路径（可选，默认使用 GODOT_PROJECT_PATH 环境变量或当前目录） | |
| visible_only | No | find_ui_elements: 仅返回可见元素（默认 true） | |
| interval_frames | No | monitor_start: 采样间隔帧数（默认 10，最小 1，最大 300） | |
| source_script_path | No | install_override/uninstall_override: 源调试脚本绝对路径（必须在 ALLOWED_PROJECT_PATHS 白名单内,拷贝到项目根注册为 MCPOVERRIDE_<basename> autoload;插入 [autoload] 段末尾=在游戏 autoload 之后加载,脚本 _ready 可直接访问游戏单例,无需 await <Singleton>.ready） |