Godot Bridge

Components

• gdscript-lsp-proxy: bridges stdio-based LSP clients to Godot's TCP-based GDScript language server.
• godot-bridge: CLI for plugin-backed editor control.
• Godot Bridge plugin: runs in the editor and exposes the command surface used by the CLI.

Environment assumptions

• Godot should be running with the target project open when using the live editor bridge or the GDScript LSP.
• The Godot Bridge plugin defaults to 127.0.0.1:6505 unless configured otherwise.
• The Godot GDScript LSP defaults to localhost:6005 unless configured otherwise.
• The repository containing the bridge code may be different from the game project currently open in Godot.

CLI usage

• Prefer godot-bridge ... when the binary is installed and available on PATH.
• If the binary is not installed, use the environment's local invocation for this repository, for example go run ./cmd/godot-bridge ... from the cli/ directory.
• Do not assume the current working directory is already correct. Use an explicit working directory or full command path when needed.
• Use --json when structured output is needed for follow-up reasoning.
• Treat non-zero exits as command failures and read stderr for error details.

Recommended CLI workflow

1. Run godot-bridge status to confirm the bridge is reachable.
2. Run godot-bridge editor state --json to inspect the current scene and selection.
3. If you need command discovery, run godot-bridge spec.
4. For scene structure, use godot-bridge node tree [PATH] --json or godot-bridge node get PATH --detail full --json.
5. For edits, prefer small explicit operations such as node add, node modify, node move, node delete, then scene save.
6. Use godot-bridge screenshot --json for the editor viewport and godot-bridge game screenshot --json for the running game window.
7. For live runtime output, godot-bridge debug watch --json can stay connected while other CLI commands run in parallel.

Editor Safety

• Keep one editor instance per target project unless you intentionally need more.
• Do not replace plugin files inside a live project while the editor is running. Close the editor, update files, then relaunch.
• Prefer status, editor state, node tree, and node get for bridge validation before reaching for scene run.
• Use scene run sparingly in manual validation because it spawns a game child process. Prefer a short self-terminating test scene if you need runtime output.
• If a run was interrupted or the editor crashed, check for leftover Godot child processes before relaunching more test sessions.
• For more detailed live-editor workflow guidance, see docs/godot-agent-workflow.md in this repository.

Common commands

• godot-bridge status
• godot-bridge spec
• godot-bridge editor state --json
• godot-bridge node tree /root/Main --json
• godot-bridge node get /root/Main/Player --detail full --json
• godot-bridge node add Sprite2D --parent /root/Main --name Hero --props '{"position":[200,150]}'
• godot-bridge node modify /root/Main/Hero --props '{"position":[240,180]}'
• godot-bridge signal connect --source /root/Main/Button --signal pressed --target /root/Main/Game --method on_button_pressed
• godot-bridge project get --prefix input/ --json
• godot-bridge animation list /root/Main/AnimationPlayer --json
• godot-bridge sprite-frames new res://art/player.tres --data '{"animations":[{"name":"idle","speed":6,"loop":true,"frames":[{"texture":"res://art/player_sheet.png","region":{"x":0,"y":0,"w":16,"h":16}}]}]}'
• godot-bridge sprite-frames from-manifest --sheet res://art/player_sheet.png --manifest res://art/player_sheet.json --out res://art/player_frames.tres --node /root/Main/Player
• godot-bridge node modify /root/Main/Player --props '{"sprite_frames":"res://art/player.tres","animation":"idle","autoplay":"idle"}'
• godot-bridge scene save
• godot-bridge debug watch --events output,error
• godot-bridge screenshot --json
• godot-bridge game screenshot --json
• godot-bridge resource list res:// --json
• godot-bridge resource reimport res://art/hero.png

Notes

• resource list uses Godot's resource filesystem view, so paths should be res://....
• resource reimport is useful after writing assets directly to disk so the editor notices them immediately.
• scene run without a path runs the main scene. With a path, it opens and runs that scene.
• screenshot and game screenshot return metadata in text mode and image payload data in JSON mode.
• debug watch uses its own websocket connection and can run alongside other CLI commands.