godot-bootstrap

Godot Bootstrap

Everything required to take a machine from "Godot may or may not be installed" to "JSONRPC endpoint is reachable and the godot-repl skill can take over."

Quick state check

Run these probes; the result tells you which step to start at:

PROJECT=/path/to/project

command -v godot                                          && echo "godot on PATH"
test -f "$PROJECT/project.godot"                          && echo "✓ is a Godot project"
test -f "$PROJECT/addons/godot-repl/plugin.cfg"           && echo "✓ addon installed"
grep -qF 'res://addons/godot-repl/plugin.cfg' \
     "$PROJECT/project.godot" 2>/dev/null                 && echo "✓ addon enabled"
test -f "$PROJECT/.godot/repl_endpoint.json"              && echo "✓ endpoint exists"

State	Action
No project.godot	Step 0 — create project
Project, no addon	Step 2 — install addon
Addon present, not enabled	Step 2 — edit project.godot
All present, no endpoint	Step 3 — launch editor
Endpoint present	Hand off to godot-repl skill

Step 0: Create a project (only if missing)

Godot recognizes a directory as a project only if it contains a project.godot file. Minimum scaffold:

PROJECT=/path/to/new-project
NAME="MyProject"
mkdir -p "$PROJECT"

cat > "$PROJECT/project.godot" <<EOF
config_version=5

[application]
config/name="$NAME"
config/features=PackedStringArray("4.6", "GL Compatibility")
config/icon="res://icon.svg"

[rendering]
renderer/rendering_method="gl_compatibility"
EOF

Do NOT add run/main_scene to project.godot at this point — declaring it before the scene exists makes the first --headless --quit import print a Cannot open file 'res://main.tscn' ERROR (exit is still 0, but noisy). Add it after the scene file exists. The REPL pattern for setting it correctly is in godot-repl/references/recipes.md → "ProjectSettings" (it requires set_initial_value + a save-race mitigation).

cat > "$PROJECT/icon.svg" <<'EOF'
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg width="128" height="128" viewBox="0 0 128 128" xmlns="http://www.w3.org/2000/svg">
  <rect width="128" height="128" rx="20" fill="#478cbf"/>
</svg>
EOF

Validate (note the -e — without it, --quit runs the project and fails on no-main-scene):

"$GODOT" -e --headless --path "$PROJECT" --quit
# Expected: exit 0. .godot/ cache directory gets created.

Rendering driver: gl_compatibility works on 2D, web, and oldest GPUs — good default. Use forward_plus only when targeting modern desktop 3D.

Step 1: Locate the Godot binary

Probe order:

1. godot --version — if on PATH and reports 4.x, you're done. Save as $GODOT.
2. Per-platform common locations:
   • Windows: %LOCALAPPDATA%\Godot\Godot_v4.*.exe, C:\Program Files\Godot\godot.exe, %USERPROFILE%\scoop\apps\godot\current\godot.exe. Prefer the _console.exe variant — the non-console build silently detaches stdout on Windows, breaking --script output capture.
   • macOS: /Applications/Godot.app/Contents/MacOS/Godot
   • Linux: /usr/bin/godot, /usr/local/bin/godot, ~/.local/bin/godot, Flatpak flatpak run org.godotengine.Godot
3. If none found, ask the user for the absolute path and capture it as $GODOT. Don't try to install Godot for them — the download page has variant choices (Standard / .NET / mono) the user needs to make.

Verify version:

"$GODOT" --headless --version
# expected: 4.x.stable (or 4.x.beta / dev). Reject 3.x — godot-repl is 4.x-only.

Reuse $GODOT for the rest of the session. Don't rely on PATH from this point on.

Full per-platform path tables in references/platform-paths.md.

Step 2: Install and enable the godot-repl addon

Fetch the addon source from the published GitHub repository:

if [ -d /tmp/godot-repl-src/.git ]; then
    git -C /tmp/godot-repl-src pull --ff-only
else
    rm -rf /tmp/godot-repl-src
    git clone --depth 1 https://github.com/FrostyLeaves/godot-repl.git /tmp/godot-repl-src
fi

Copy into the target project:

mkdir -p "$PROJECT/addons"
cp -r /tmp/godot-repl-src/addons/godot-repl "$PROJECT/addons/godot-repl"

Enable in <project>/project.godot. The minimum needed if the project has no other plugins:

[editor_plugins]

enabled=PackedStringArray("res://addons/godot-repl/plugin.cfg")

If the project already has plugins, append to the enabled= array — don't replace.

Step 3: Launch the editor and verify the endpoint

"$GODOT" -e --path "$PROJECT" >/dev/null 2>&1 &

-e = editor mode (vs -d for runtime). Background (&) so you can keep working. Stdout redirected — engine prints a lot of init noise.

Poll for the endpoint file (2–5 s typical):

for i in $(seq 1 30); do
    [ -f "$PROJECT/.godot/repl_endpoint.json" ] && break
    sleep 0.5
done
cat "$PROJECT/.godot/repl_endpoint.json"

Expected (port numbers shown are defaults; see note below):

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

Ports are dynamic. The addon picks the lowest free port in 6010..6020 (editor) / 6011..6021 (runtime). If another editor instance was already running, you'll see port: 6011 (or higher) for editor — that's normal. Always read the live endpoint.port from this file rather than assuming 6010/6011.

The runtime entry appears only when the project is also running (-d or via the editor's Play button). For .tscn / scene / resource work the editor endpoint is sufficient.

If the file doesn't appear after 15 seconds:

• Verify the addon is enabled in project.godot (grep enabled= "$PROJECT/project.godot")
• Verify Godot is 4.x ("$GODOT" --version)
• Open the editor by hand and check the Output panel for [godot-repl] lines

Step 4: Hand off

Once the endpoint file exists and the port responds to {"jsonrpc":"2.0","method":"repl.info","params":{},"id":1}, you're done — hand off to the godot-repl skill. That skill takes the endpoint as given and teaches the JSONRPC surface.

Lifecycle

Restart a stuck editor

PID=$(jq -r '.editor.pid' "$PROJECT/.godot/repl_endpoint.json")
kill "$PID"; sleep 2                                       # POSIX
"$GODOT" -e --path "$PROJECT" >/dev/null 2>&1 &

$pid_ = (Get-Content "$project\.godot\repl_endpoint.json" | ConvertFrom-Json).editor.pid
Stop-Process -Id $pid_ -Force                              # Windows

After a force-kill, .godot/repl_endpoint.json may contain a stale entry — the addon prunes dead pids on a 2-second timer on next launch.

Update the addon

git -C /tmp/godot-repl-src pull
rm -rf "$PROJECT/addons/godot-repl"
cp -r /tmp/godot-repl-src/addons/godot-repl "$PROJECT/addons/godot-repl"
# restart the editor for new code to load

Sessions persist to <project>/.godot/repl_sessions/ and survive addon updates — repl.list_sessions will surface them again after restart.

Uninstall

rm -rf "$PROJECT/addons/godot-repl"
# remove the entry from project.godot enabled=PackedStringArray(...)

Headless one-shot --script (orthogonal to REPL)

For batch jobs that don't need a persistent session — generate an asset, validate config, run a single test — use --headless --script instead of REPL. This is how the 21 test files in tests/ are structured:

"$GODOT" --headless --path "$PROJECT" --script "res://path/to/job.gd"

The script must extends SceneTree and call quit(exit_code). --headless --script and the REPL are independent execution models.

Failure map

Symptom	Cause	Fix
godot: command not found	Not on PATH	Step 1 — find absolute path
Editor opens Project Manager instead	--path points to a dir with no project.godot	Step 0
Editor opens but no repl_endpoint.json	Addon not enabled	Step 2 — enabled= line
repl_endpoint.json exists but TCP refuses	Editor booting, crashed, or wrong Godot version	Wait 5s; check pid; check --version
--script runs silently on Windows	Using the non-console.exe binary	Step 1 — pick _console.exe