godot-repl

name

godot-repl

description

Evaluates raw GDScript directly on the Godot Editor's main thread (or in the running project's runtime process) via local JSONRPC over TCP. Use whenever you want to run GDScript or call any in-engine API — modify .tscn scenes, query the scene tree, change ProjectSettings, set Node properties, run @tool scripts, inspect a running game's live state, work with Resources, drive EditorInterface. Triggers: edit Godot scene, modify tscn, query SceneTree, run GDScript, inspect Node, ProjectSettings, EditorInterface, hot reload, Godot editor automation, evaluate GDScript expression, in-engine query, Godot API call.

Godot REPL

Send any GDScript to a running Godot editor (or its runtime child process). The engine evaluates it on the main thread; you get a structured result, captured print() output, or a typed error.

It's a REPL. Anything the engine can execute, you can send. Top-level declarations (var, func, class, const, signal, enum) persist across calls in the same session. The last expression auto-returns when it's not a statement.

Setup check

The editor must be running with the godot-repl addon enabled. Verify:

test -f "<project>/.godot/repl_endpoint.json" && cat "<project>/.godot/repl_endpoint.json"

{"editor":  {"host": "127.0.0.1", "port": 6010, "pid": 12345},
 "runtime": {"host": "127.0.0.1", "port": 6011, "pid": 12346}}

If that file is missing, the editor isn't running or the addon isn't enabled — use the godot-bootstrap skill.

Quick start — the wrapper

Two wrappers, same flags, same behavior — pick the one for your platform:

Platform	Wrapper
Windows (cmd, PowerShell, or Git-Bash)	addons\godot-repl\repl.bat
Linux, macOS	addons/godot-repl/repl.sh

Both wrappers handle endpoint discovery, JSONRPC envelope construction, NDJSON stream reading, and result parsing. Pass GDScript, get the result.

Inline (one-liner)

:: Windows
addons\godot-repl\repl.bat -e "Engine.get_version_info().string"
:: → 4.6.stable

# Linux / macOS
./addons/godot-repl/repl.sh -e 'Engine.get_version_info().string'
# → 4.6.stable

Multi-line GDScript (avoid quote-escaping)

GDScript doesn't support ; as a statement separator, so anything beyond one expression needs newlines. Use stdin or a file.

PowerShell here-string:

@'
var root = EditorInterface.get_edited_scene_root()
return root.get_child_count()
'@ | & "addons\godot-repl\repl.bat" -

cmd doesn't have heredocs — use -f with a file:

:: write query.gd via your editor / Write tool, then:
addons\godot-repl\repl.bat -f query.gd

bash heredoc:

./addons/godot-repl/repl.sh - <<'EOF'
var root = EditorInterface.get_edited_scene_root()
return root.get_child_count()
EOF

Full flag table and behavior in references/wrapper.md.

Don't guess — introspect

Godot's ClassDB exposes every class, method, property, and signal at runtime. Before calling something you're not 100% sure about, verify it exists — it's a one-liner via REPL and the answer is exact to your Godot version:

./repl.sh -e 'ClassDB.class_has_method("Node", "add_child")'
# → true

# Find method by partial name
./repl.sh - <<'EOF'
return ClassDB.class_get_method_list("Camera2D").filter(
    func(m): return "zoom" in m.name
).map(func(m): return m.name)
EOF

Common entry points (one-liners worth memorizing):

Want to know	Call
Does this method exist?	ClassDB.class_has_method("Node", "add_child")
What's the full method signature?	ClassDB.class_get_method_list("Node") (filter by .name)
What properties does this class have?	ClassDB.class_get_property_list("Node")
What signals?	ClassDB.class_get_signal_list("Node")
Is X a subclass of Y?	ClassDB.is_parent_class("Camera2D", "Node2D")
What singletons are loaded?	Engine.get_singleton_list()
What's my Godot version?	Engine.get_version_info()

More patterns (find by intent, list inheritors, dump enum constants, etc.) in references/recipes.md → "Discovery & introspection."

When ClassDB isn't enough (conceptual questions, usage idioms, lifecycle ordering), check Godot's official docs at https://docs.godotengine.org/en/<version>/ — get <version> from repl.info. ClassDB tells you what exists; the docs tell you what's idiomatic.

Endpoints

• editor — modify .tscn, change ProjectSettings, use EditorInterface, save resources, trigger Play
• runtime (only when the project is running) — inspect a live SceneTree, mutate Node properties on a playing game, read runtime state

Default is editor. Pass --target runtime to the wrapper for the runtime endpoint.

Ports are dynamic. The addon picks the lowest free port from 6010..6020 for editor and 6011..6021 for runtime. The wrappers read <project>/.godot/repl_endpoint.json automatically; raw-TCP clients must do the same — never hardcode 6010.

Methods

Method	Purpose
repl.eval	Evaluate GDScript, return result
repl.validate	Compile-only check, no execution, no side effects
repl.reset	Clear a session's accumulated declarations
repl.cancel	Stop the server from waiting on an in-flight eval
repl.list_sessions	Enumerate active sessions
repl.info	Server metadata (version, target, uptime, capabilities)
repl.abilities / repl.get_ability	Discover godot-agent-* extension packages

Full JSONRPC schema, response shapes, and notification details: references/methods.md.

Async work

await works as normal — the server awaits the resulting Signal and responds with the final value:

await get_tree().create_timer(2.0).timeout
var img = await ResourceLoader.load_threaded_get_resource("res://big.png")
return img.get_size()

Default timeout is 60s. Override with --timeout-ms (wrapper) or params.timeout_ms (raw JSONRPC).

Error kinds

The result.kind tells you what happened:

• value — eval succeeded; result.value is the return value
• compile_error — GDScript didn't compile
• runtime_error — code ran but the engine reported an error
• timeout — timeout_ms exceeded
• cancelled — another agent called repl.cancel

RPC-layer errors (error.code set, not result.kind) — PARSE_ERROR, METHOD_NOT_FOUND, INVALID_PARAMS — indicate protocol failures, not user code failures.

Going further

• references/methods.md — full JSONRPC schema for every method and notification
• references/wrapper.md — repl.sh / repl.bat flags and behavior
• references/raw-client.md — raw NDJSON-over-TCP clients (PowerShell / bash / Python) for mid-flight cancel, batch, persistent connections, or wrapper bypass
• references/recipes.md — common GDScript snippets plus the Godot-side quirks you'll meet (PackedScene.pack child-drop, ProjectSettings.save race, ConfigFile cache, async open_scene_from_path, lambda body limits, multi-line dict indentation)
• references/abilities.md — author a godot-agent-* package that registers with this REPL