Skip to main content
Glama
bebabinlarsson-blip

godot-omni

by bebabinlarsson-blip
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Local

game_manage

Inspect a running Godot game's scene tree, nodes, and UI elements, and simulate keyboard, mouse, gamepad, or action input to test runtime behavior.

Instructions

Runtime game inspection and input simulation.

These ops target the running game process through Godot's EngineDebugger bridge. Start the project first with project_run and poll editor_state until game_capture_ready=true.

Ops:

  • get_scene_tree(depth=10, root_path="") Inspect the running scene tree. root_path accepts an absolute runtime path or a scene-relative path rooted at the current scene.

  • get_node_info(path, include_properties=True) Inspect one running node's metadata and optional property snapshot.

  • get_ui_elements(root_path="", include_hidden=False, include_disabled=True, max_depth=10) Inspect visible runtime Control nodes for UI testing. Includes path, type, text where present, disabled state, and rect metadata.

  • suspend() Suspend the running game through Godot's native debugger path.

  • resume() Resume a suspended game. Idempotent when it is already running.

  • next_frame() Advance exactly one process tick while suspended. The response reports verification and any Embedded Game View focus handoff. Runtime-control mutations also report path="embed_signal" or "direct_session"; the direct fallback works without embedding but cannot synchronize the Game View suspend button's visual pressed state.

  • debug_status() Probe suspend state and the game-helper process tick counter through the debugger capture, including while SceneTree processing is suspended.

  • input_key(key, pressed=True, echo=False) Send a key press/release to the running game.

  • input_mouse(event, position=None, button="left", pressed=True) Send a mouse motion or button event. event: "motion" | "button". position is a {x, y} object or [x, y] array; omit it to use the game's current cursor position. A present but malformed position is rejected rather than silently falling back to the cursor.

  • input_gamepad(device=0, control="button", index=0, pressed=True, value=0.0) Send a joypad button or axis event. control: "button" | "axis".

  • input_action(action, pressed=True, strength=1.0) Set a project action's pressed state directly in the running game.

  • input_sequence(steps, settle_frames=0) Apply a frame-timed action timeline in one call — the frame-accurate, multi-step form of input_action. Each step is {at_frame, action, pressed=True, strength=1.0}; the game applies each step's action on its scheduled frame, awaits settle_frames more, then replies once. Use this instead of separate input_action calls whenever timing matters (jump arcs, combos, walk-into-trigger): per-call network latency makes hitting a target frame impossible otherwise. Steps must be ordered by non-decreasing at_frame; frames (not ms) are the timing basis. Action-based input is focus-independent, so it works on a backgrounded game window. Cannot run inside batch_execute.

  • simulate_input(action="", key="", duration=0.5, press=True, strength=1.0) Simulate hardware or action input with duration and automatic clean release. For actions, executes a timed sequence and releases after duration seconds.

  • input_state(actions=None) Read current action pressed states. Empty actions = all project actions.

Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
opYes
paramsNo
session_idNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv5.0.14
    • changedInput schema / properties / op / enum
      Previous value: -[
-  "debug_status",
-  "get_node_info",
-  "get_scene_tree",
-  "get_ui_elements",
-  "input_action",
-  "input_gamepad",
-  "input_key",
-  "input_mouse",
-  "input_sequence",
-  "input_state",
-  "next_frame",
-  "resume",
-  "suspend"
-]New value: +[
+  "debug_status",
+  "get_node_info",
+  "get_scene_tree",
+  "get_ui_elements",
+  "input_action",
+  "input_gamepad",
+  "input_key",
+  "input_mouse",
+  "input_sequence",
+  "input_state",
+  "next_frame",
+  "playtest",
+  "resume",
+  "run_playtest_suite",
+  "simulate",
+  "simulate_input",
+  "suspend"
+]
  2. First observedv4.1.0

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and delivers richly: resume is declared idempotent, next_frame advances exactly one tick with verification and embed_signal/direct_session response semantics, input_mouse rejects malformed positions instead of silently falling back, input_sequence is frame-timed with non-decreasing at_frame ordering and focus-independent action input, and simulate_input has automatic clean release. This is exemplary behavioral disclosure of side effects, timing, failure modes, and environmental dependencies.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long (~600 words) but earns its length for 14 operations, with each op presented as a compact signature plus only semantically important notes. Purpose is front-loaded and the prerequisite placement is logical. Two minor structural flaws: the canonical call shape — needed for every invocation — is buried at the end, and the ops block is dense enough to tax a quick scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and an open params object, the description covers prerequisites, per-op semantics, timing rules, environment constraints (batch_execute, embedding fallback, backgrounded-window support), and failure behaviors for all documented ops — essentially a full API manual. The material gap is the three undocumented enum ops, which an agent would discover from the schema but could not invoke correctly, and the absence of any mention of how playtest/simulate relate to the documented ops or siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and params is an open object (additionalProperties: true), so the description is the only parameter documentation. It comprehensively details signatures and semantics for 14 ops: root_path path types, position as {x,y} or [x,y], control enum values, the input_sequence step schema with frame-based timing, and input_state's empty=all-actions rule. The gap: playtest, run_playtest_suite, and simulate appear in the op enum but have zero parameter documentation anywhere.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The title 'Runtime game inspection and input simulation' plus the opening line names a specific target resource (the running game process via Godot's EngineDebugger bridge) and a clear verb set (inspect, simulate). This distills cleanly against siblings: scene_manage/node_manage handle static scene/node editing, project_run launches the game, and input_map_manage configures mappings — none cover runtime inspection and input simulation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit prerequisites are given ('Start the project first with project_run and poll editor_state until game_capture_ready=true'), and input_sequence gets an explicit when-to-use vs. input_action plus a when-not ('Cannot run inside batch_execute'). However, three ops in the op enum (playtest, run_playtest_suite, simulate) are undocumented, so an agent gets no guidance on when to choose them over the documented simulate_input or the sibling test_run.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools