← Platforms

Godot

Remote debugging for Godot 4 games — a pure GDScript addon that connects your running game to OmniDebugLink, so AI tools can inspect the live scene tree, inject real input and key events, and capture screenshots on any export platform.

The Godot client is a zero-dependency GDScript addon: WebSocketPeer, JSON and image handling are all engine built-ins, so there is nothing to resolve, no native code and no threads. Drop the addon into a project, start it with a device token, and a game running on desktop, mobile or web exports becomes inspectable and drivable from your AI coding tool — traverse the scene tree, read logs, tap buttons, type text, fire InputMap actions, even inject hardware-level key events like Escape.

Core features

Requirements

• Godot 4.2 or newer.
• A device token from the OmniDebugLink console — one token pair is one device seat. Never share a token between two running instances: the newer connection replaces the older one.
• Outbound internet access from the running game. Works on desktop, mobile and web exports.

Install the addon

The Godot editor has no "install from git URL" flow, so the addon is copied into your project. Two options:

git clone https://github.com/omnidebuglink/omnidebuglink_godot.git

Wire it up

func _ready() -> void:
    OmniDebugLink.start("your-client-token")

if OS.get_environment("OMNIDEBUGLINK_TOKEN") != "":
    OmniDebugLink.start(OS.get_environment("OMNIDEBUGLINK_TOKEN"))
else:
    OmniDebugLink.actions_enabled = false  # or don't start() at all

Runtime API

Built-in tasks (25)

Everything below ships in the addon. The AI sees the full list — with per-task payload schemas — automatically; you never need to configure anything server-side. Write tasks are all gated by actions_enabled.

Read tasks

Write tasks

Basics

Custom tasks

Register your own task with a type, handler, description and payload schema. Handlers run on the main thread, may await (frames, timers), and return any JSON-friendly Dictionary; signal failure by returning OmniDebugLink.task_error("message"). Registering or unregistering automatically re-announces capabilities — no changes needed on the server side.

func _ready() -> void:
    OmniDebugLink.start("your-client-token")
    OmniDebugLink.tasks.register(
        "give_gold",
        func(payload: Dictionary) -> Dictionary:
            var amount := int(payload.get("amount", 100))
            GameState.gold += amount
            return {"gold": GameState.gold},
        "Adds gold to the player wallet.",
        {
            "type": "object",
            "properties": {"amount": {"type": "integer", "minimum": 1}},
            "required": ["amount"],
        }
    )

What read_logs captures

Good to know

• One token pair per device. If the SDK reports close code 4000, the token was claimed by another connection and it stops reconnecting by design — give each running instance its own token.
• The whole client is main-threaded. Do not call start() or task handlers from threads; for cross-thread logging, push messages through call_deferred.
• Coordinates are normalized 0-1 with a top-left origin, injected in canvas space so stretch modes map correctly — no window-pixel math on your side.
• C# (Godot .NET) projects work too: drive the GDScript autoload via GetNode("/root/OmniDebugLink").Call("start", token).
• Debug timers ignore the game clock. Waiting and timing keep running under time_scale = 0 and while the SceneTree is paused — a debugging tool must not be frozen by the game it debugs.