Skip to main content
Glama

simulate_input

Destructive

Inject keyboard, mouse, click, action, text, and wait input into a running Godot game to drive gameplay and UI. Send batches of actions, optionally hold keys, and sample node properties to verify results.

Instructions

Send input actions. key, mouse_button, action: omit pressed to tap; set it to hold or release. click_element takes a node path or name (see get_ui_elements), not text, and scrolls its target into view. Returns: projectPath, success, results[]: ok, hit, scrolled, signals, changes, watch, mouse_motion position (as delivered), errors (spawned only); warnings leads if errors is partial. An invalid batch injects nothing; a failure skips the rest. A covered or clipped click is refused.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "actions": "<actions>"
    },
    "name": "simulate_input"
  }
}

Input Schema

NameRequiredDescriptionDefault
watchNoGodot NodePath:property strings sampled after every action and reported per result, e.g. "/root/Main/Player:position". Property subnames are allowed ("/root/Main/Player:position:x"). Read-only; an unresolvable path samples as null instead of failing the batch.
actionsYesArray of input actions to execute sequentially. Each object must have a "type" field. A batch whose time budget (waits, holds, and every frame counted at 10fps) exceeds 600s is rejected before anything is injected: split it across calls. The budget admits at most 5900 actions per call, fewer when they tap, hold or wait. When results outgrow one reply (about 4 MiB), later entries keep only index, type, ok, frame, elapsed_ms and error, with details_dropped: true; the action still ran.

Output Schema

NameRequiredDescriptionDefault
resultsYesOne entry per requested action, in order.
successYesFalse when an action failed and the remaining actions were skipped.
warningsNoPresent when the per-action errors could not be attributed completely: some may sit on the wrong entry or be missing.
still_heldNoInputs this batch pressed that the engine still reports pressed when the batch ends, e.g. "key:W", "action:jump", "mouse_button:left"; a key is spelled as the engine names its keycode, whatever case the request used. Absent when none.
projectPathYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed18 schema fields changedv4.0.1
    • changedInput schema / properties / actions / description
      Previous value: -"Array of input actions to execute sequentially. Each object must have a \"type\" field."New value: +"Array of input actions to execute sequentially. Each object must have a \"type\" field. A batch whose time budget (waits, holds, and every frame counted at 10fps) exceeds 600s is rejected before anything is injected: split it across calls. The budget admits at most 5900 actions per call, fewer when they tap, hold or wait. When results outgrow one reply (about 4 MiB), later entries keep only index, type, ok, frame, elapsed_ms and error, with details_dropped: true; the action still ran."
    • changedInput schema / properties / actions / items / properties / action / description
      Previous value: -"[action] Godot input action name (as defined in Project Settings > Input Map)"New value: +"[action] Godot input action name (as defined in Project Settings > Input Map). Sent as an InputEventAction: input handlers see it like its bound key, and ui_* actions act on the focused Control (ui_text_* editing actions do not; use key or text)."
    • addedInput schema / properties / actions / items / properties / frames / maximum
      Added value: +600
    • addedInput schema / properties / actions / items / properties / frames / minimum
      Added value: +0
    • addedInput schema / properties / actions / items / properties / hold_ms / maximum
      Added value: +10000
    • addedInput schema / properties / actions / items / properties / hold_ms / minimum
      Added value: +0
    • changedInput schema / properties / actions / items / properties / ms / description
      Previous value: -"[wait] Real-time pause in milliseconds, for time-driven things such as cooldowns and animations (~16ms = one frame at 60fps). Exactly one of ms or frames is required. Uncapped, but a batch whose total wait approaches 60s may be cut off by your client before the server answers: split it across calls."New value: +"[wait] Real-time pause in milliseconds, for time-driven things such as cooldowns and animations (~16ms = one frame at 60fps). Exactly one of ms or frames is required. Counts toward the batch's 600s time budget, and a batch whose total wait approaches 60s may be cut off by your client before the server answers: split it across calls."
    • addedInput schema / properties / actions / items / properties / ms / minimum
      Added value: +0
    • changedInput schema / properties / actions / items / properties / x / description
      Previous value: -"[mouse_button, mouse_motion] X position in viewport pixels (0,0 = top-left)"New value: +"[mouse_button, mouse_motion] X position in viewport pixels (0,0 = top-left), as get_ui_elements reports them; a stretch mode is converted"
    • changedInput schema / properties / actions / items / properties / y / description
      Previous value: -"[mouse_button, mouse_motion] Y position in viewport pixels (0,0 = top-left)"New value: +"[mouse_button, mouse_motion] Y position in viewport pixels (0,0 = top-left), as get_ui_elements reports them; a stretch mode is converted"
    • addedOutput schema / properties / projectPath
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / results / items / properties / details_dropped
      Added value: +{
      +  "description": "Present when the results of the batch outgrew what one reply can carry: this entry keeps only index, type, ok, frame, elapsed_ms and error. The action still ran. Read the state it left with get_ui_elements or take_screenshot.",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / results / items / properties / note
      Added value: +{
      +  "description": "Why a field is absent from this entry.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / results / items / properties / position / description
      Added value: +"[mouse_motion] Viewport position the injected event reached the root viewport at. Omitted, with `note` saying why, when no motion event arrived."
    • addedOutput schema / properties / results / items / properties / scrolled
      Added value: +{
      +  "description": "[click_element] Paths of the ScrollContainers scrolled to bring the target into view before the click. Absent when none moved.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / properties / still_held / description
      Previous value: -"Inputs this batch pressed and did not release, e.g. \"key:W\", \"action:jump\"."New value: +"Inputs this batch pressed that the engine still reports pressed when the batch ends, e.g. \"key:W\", \"action:jump\", \"mouse_button:left\"; a key is spelled as the engine names its keycode, whatever case the request used. Absent when none."
    • addedOutput schema / properties / warnings
      Added value: +{
      +  "description": "Present when the per-action errors could not be attributed completely: some may sit on the wrong entry or be missing.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / required
      Added value: +[
      +  "projectPath",
      +  "success",
      +  "results"
      +]
  2. Changed14 schema fields changedv3.8.0
    • addedInput schema / properties / actions / items / properties / frames
      Added value: +{
      +  "description": "[wait] Deterministic pause of N engine process frames, for stepping game logic rather than waiting on the clock. Exactly one of ms or frames is required. Max 600, budgeted at a 10fps floor, so a wait of several hundred frames may be cut off by your client before the server answers.",
      +  "type": "number"
      +}
    • addedInput schema / properties / actions / items / properties / hold_ms
      Added value: +{
      +  "description": "[key, mouse_button, action] Tap hold duration in milliseconds, overriding the default (one process frame plus one physics frame for key/action, zero gap for mouse_button). Use it for code polling is_action_pressed over real time. Rejected when pressed is also set. Max 10000.",
      +  "type": "number"
      +}
    • changedInput schema / properties / actions / items / properties / ms / description
      Previous value: -"[wait] Duration in milliseconds to pause before the next action (~16ms = one frame at 60fps)."New value: +"[wait] Real-time pause in milliseconds, for time-driven things such as cooldowns and animations (~16ms = one frame at 60fps). Exactly one of ms or frames is required. Uncapped, but a batch whose total wait approaches 60s may be cut off by your client before the server answers: split it across calls."
    • changedInput schema / properties / actions / items / properties / pressed / description
      Previous value: -"[key, mouse_button, action] Whether the input is pressed (true) or released (false). For mouse_button: omit to auto-click (press+release in one action); set explicitly only for hold/release. For key: defaults to true and does NOT auto-release - emit a second action with pressed:false to release."New value: +"[key, mouse_button, action] Omit to tap: the action presses, holds briefly, and releases by itself. Set true to press and hold across later actions (reported in still_held), false to release an earlier hold. Cannot be combined with hold_ms."
    • changedInput schema / properties / actions / items / properties / strength / description
      Previous value: -"[action] Action strength (0–1, default 1.0)"New value: +"[action] Action strength (0 to 1, default 1.0)"
    • addedInput schema / properties / actions / items / properties / text
      Added value: +{
      +  "description": "[text] String to type into whatever Control currently holds focus, expanded to one key press+release per character. Fails when nothing holds focus - click or focus the LineEdit first. Max 1000 characters.",
      +  "type": "string"
      +}
    • changedInput schema / properties / actions / items / properties / type / enum
      Previous value: -[
      -  "key",
      -  "mouse_button",
      -  "mouse_motion",
      -  "click_element",
      -  "action",
      -  "wait"
      -]New value: +[
      +  "key",
      +  "mouse_button",
      +  "mouse_motion",
      +  "click_element",
      +  "action",
      +  "text",
      +  "wait"
      +]
    • addedInput schema / properties / watch
      Added value: +{
      +  "description": "Godot NodePath:property strings sampled after every action and reported per result, e.g. \"/root/Main/Player:position\". Property subnames are allowed (\"/root/Main/Player:position:x\"). Read-only; an unresolvable path samples as null instead of failing the batch.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "maxItems": 16,
      +  "type": "array"
      +}
    • removedOutput schema / properties / actions_processed
      Removed value: -{
      -  "type": "number"
      -}
    • addedOutput schema / properties / results
      Added value: +{
      +  "description": "One entry per requested action, in order.",
      +  "items": {
      +    "properties": {
      +      "changes": {
      +        "properties": {
      +          "appeared": {
      +            "items": {
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "changed": {
      +            "items": {
      +              "type": "object"
      +            },
      +            "type": "array"
      +          },
      +          "disappeared": {
      +            "items": {
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          "focus": {
      +            "type": "string"
      +          },
      +          "scene": {
      +            "type": "string"
      +          },
      +          "truncated": {
      +            "type": "number"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "elapsed_ms": {
      +        "description": "Milliseconds since batch start.",
      +        "type": "number"
      +      },
      +      "error": {
      +        "type": "string"
      +      },
      +      "errors": {
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      },
      +      "focus": {
      +        "description": "Path of the focus owner after the action.",
      +        "type": "string"
      +      },
      +      "frame": {
      +        "description": "Process frames elapsed since batch start.",
      +        "type": "number"
      +      },
      +      "hit": {
      +        "description": "Path of the Control under the pointer after the action settled.",
      +        "type": "string"
      +      },
      +      "index": {
      +        "type": "number"
      +      },
      +      "ok": {
      +        "type": "boolean"
      +      },
      +      "position": {
      +        "properties": {
      +          "x": {
      +            "type": "number"
      +          },
      +          "y": {
      +            "type": "number"
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "pressed": {
      +        "description": "Whether the input action is still held after this entry.",
      +        "type": "boolean"
      +      },
      +      "signals": {
      +        "description": "Which of pressed, toggled, item_selected, text_submitted the target emitted within the settle frame. A signal emitted later (call_deferred, a tween, a timer) is not observed, so an absent entry means \"not within one frame\", not \"never\".",
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      },
      +      "skipped": {
      +        "description": "Present when an earlier failure ended the batch before this action.",
      +        "type": "boolean"
      +      },
      +      "type": {
      +        "type": "string"
      +      },
      +      "value": {
      +        "description": "Resulting text of the focused text Control.",
      +        "type": "string"
      +      },
      +      "watch": {
      +        "additionalProperties": true,
      +        "type": "object"
      +      }
      +    },
      +    "required": [
      +      "index",
      +      "type"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / properties / still_held
      Added value: +{
      +  "description": "Inputs this batch pressed and did not release, e.g. \"key:W\", \"action:jump\".",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / properties / success / description
      Added value: +"False when an action failed and the remaining actions were skipped."
    • removedOutput schema / properties / tip
      Removed value: -{
      -  "type": "string"
      -}
    • removedOutput schema / properties / warnings
      Removed value: -{
      -  "items": {
      -    "type": "string"
      -  },
      -  "type": "array"
      -}
  3. Changed1 schema field changedv3.6.0
    • changedInput schema / properties / actions / items / properties / pressed / description
      Previous value: -"[key, mouse_button, action] Whether the input is pressed (true) or released (false). For mouse_button: omit to auto-click (press+release in one action); set explicitly only for hold/release. For key: defaults to true and does NOT auto-release — emit a second action with pressed:false to release."New value: +"[key, mouse_button, action] Whether the input is pressed (true) or released (false). For mouse_button: omit to auto-click (press+release in one action); set explicitly only for hold/release. For key: defaults to true and does NOT auto-release - emit a second action with pressed:false to release."
  4. Addedv3.1.1
  5. Removedv3.0.0
  6. Addedv1.0.0

TDQS

A4.3/5.0
Behavior5/5

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

Beyond the destructiveHint annotation it discloses the semantics that matter most for a mutating input injector: an invalid batch injects nothing (all-or-nothing validation), a mid-batch failure skips the remainder, and a covered or clipped click is refused. It also flags warning precedence when errors are partial, none of which the annotations convey.

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?

Front-loaded and dense with no filler sentences; the hard constraints (injection atomicity, click refusal) come early. The 'Returns:' run-on listing field names is cryptic and largely redundant with the existing output schema, which slightly hurts readability.

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?

For a complex batch-input tool it covers atomicity, partial failure, truncation, and element resolution, and an output schema exists so return values are covered elsewhere. The notable omission is the precondition that input only lands on a running project/editor session, which an agent needs before calling.

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

Parameters3/5

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

Schema description coverage is 100%, so per-parameter semantics are already fully documented; the description's tap/hold and key/mouse/action notes largely restate the schema. The only genuinely additive detail is that click_element scrolls its target into view, which the schema does not say. Baseline 3 is appropriate.

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 opening 'Send input actions' names a concrete verb and resource, and the following sentences enumerate the action kinds (key, mouse_button, action, click_element) so the scope is unambiguous. It also distinguishes itself from the get_ui_elements sibling by explicitly delegating element discovery there ('click_element takes a node path or name (see get_ui_elements), not text').

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?

It gives concrete behavioral guidance: omit `pressed` to tap, set true to hold, false to release, and use a node path/name rather than text for click_element. It points at get_ui_elements for valid identifiers. It stops short of stating preconditions/alternatives (e.g. that the project must be running, or when to prefer run_script over synthetic input).

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