swallowtail

Swallowtail

Contents

1. Prerequisites (check first) (lines 26-36)
2. The golden rule: discover, then drive (lines 38-73)
3. The spatial rule: anchor, read back, verify (don't place blind) (lines 75-101)
4. CLI conventions (lines 103-125)
5. Property value formats (lines 127-131)
6. Command groups (lines 133-165)
7. Build with composition, not monoliths (lines 167-179)
8. Write like a Godot developer (read these) (lines 181-219)
9. Core workflows (lines 221-314)
10. Pitfalls (lines 316-326)
11. Verifying a command works (for testing/QA) (lines 328-336)

swallowtail carries one workflow across the running Godot editor, the game process, and the debugger over a WebSocket the Swallowtail editor addon hosts. Discover the live API, create scenes, add nodes, write scripts, play the game, simulate input, inspect state, diagnose failures, apply fixes, and verify the result without leaving the interface. Every editor mutation goes through Godot's UndoRedo, so the user can Ctrl+Z anything.

Prerequisites (check first)

1. The Godot editor must be open with the swallowtail addon enabled. When a command fails because the editor isn't reachable, run swallowtail status (preflight) rather than guessing. It returns a verdict:
   • running means reachable. Never launch another editor (a second instance stacks and breaks discovery).
   • starting means the process is alive but still booting. Wait a few seconds and retry; do not launch.
   • crashed means a stale discovery file remains but the process is gone. Tell the user it crashed; you may relaunch exactly one editor.
   • closed means no discovery file, so the editor closed cleanly or never started. You may launch exactly one editor if the task needs it.
   • Launch with swallowtail launch [--headless] (run it from inside the project, or pass --project DIR). It applies these same verdict rules itself, starts the editor detached, and sends its output to <project>/.godot/swallowtail-launch.log instead of your terminal, which a raw launch corrupts. It waits until the editor accepts connections and exits non-zero if it never does. Where the CLI is not installed, the fallback is godot --path <project> --editor. Relaunch at most once; if it's still unreachable after one attempt, stop and report rather than looping launches. After a successful launch, status will read running/starting, which is your guard against opening a second.
   • Check project_match too. status reports which project the answering editor serves. When another project's editor holds the port, the verdict reads closed/crashed (nothing is serving this project) with project_match: false and the answering project_path, so follow the verdict and open one for this project. Commands refuse to run in that state rather than editing the other project, which is what the check exists to prevent.
2. The CLI binary. In this repo: task build → bin/swallowtail.exe. Invoke as bin/swallowtail.exe <group> <command> [--flags] (or task run -- <group> <command> [--flags]). Elsewhere, use the installed swallowtail.
3. Connection is automatic. The CLI finds the port from <project>/.godot/swallowtail.json (written by the addon) when run from inside the project dir; otherwise pass --port (default 9080).