# Installation

Add the addon to an existing project, bootstrap a new one, or build from source.

> **Development tooling only**
>
> Nothing here belongs in a shipped game. Read [Before you ship](https://regiellis.github.io/godot-mcp-go/docs/before-you-ship) before your first export: disable the plugin, exclude `addons/swallowtail/*` in every preset, and scan the pck.

## Requirements

- **Godot 4.7**, the version this is developed and released against. **4.3 through 4.8** work in beta.
- **Go 1.26+** to build the CLI, or a prebuilt release binary.

> **4.7 is the target, 4.3 is the floor and it is beta**
>
> The addon loads and serves on Godot 4.3 through 4.8. Registration is per group, so an engine that cannot compile a group skips it and lists the file under `unavailable_groups` in `engine.commands` rather than the plugin failing whole. Six APIs newer than 4.3 refuse with the version they need: `scene close` needs 4.5, and below 4.7 every close needs `--discard` because the editor cannot report which tabs hold unsaved work; `csg bake` and the AGX tonemap need 4.4; runtime error capture needs 4.5, below which `runtime errors` answers `capture: "unavailable"` rather than an empty list. The 3.x line is out of scope: run Godot's own `--convert-3to4` first.
>
> **Builds this release was run against:** the official **4.3**, **4.4.1**, **4.5.2**, **4.6.3** and **4.7.2** stables and **4.8-dev7**, one headless editor per version against its own copy of the project. Each registered all 337 commands with `unavailable_groups` absent, answered on the game channel, and recorded a playtest session. On 4.8 the addon runs unmodified, and `engine.search` picks up 4.8's `FuzzySearch` automatically. Scene serialization can differ between engine builds. Keep a version-control checkpoint before moving a project to another engine version.
>
> Moving a project between versions has its own guide: [Porting between Godot versions](https://regiellis.github.io/godot-mcp-go/docs/guides/porting-godot-versions).

> **C# / .NET**
>
> C# projects are supported: `csharp.setup` scaffolds the solution, `script.create` authors C# templates, and `csharp.build` / `script.validate` compile with structured diagnostics. It needs a **Godot .NET editor build** and the **.NET SDK**. See [C# projects](https://regiellis.github.io/godot-mcp-go/docs/csharp).

Download and unpack the bundle for your OS and CPU from the [releases page](https://github.com/regiellis/godot-mcp-go/releases). Add the directory containing the CLI to PATH, keeping its `addons/` directory beside it. On Windows the binary is `swallowtail.exe`. Go is only needed to build from source. No agent or MCP configuration is required.

## Into an existing project

From an unpacked release bundle, install the addon into any Godot project:

```bash
swallowtail install --project /path/to/your/project --enable --skill=false
```

This copies `addons/swallowtail/` and enables the plugin in `project.godot`, including the two game-side autoloads the `runtime` and `input` groups need. Enabling from the editor's plugin checkbox injects the same pair, so nothing needs pre-committing either way.

> **A broken install path in 0.6.0 through 0.8.2**
>
> On those versions, `install --enable` turned the plugin on without writing the game-side autoloads (`MCPGameInspector`, `MCPGameInput`), so every `runtime.*` and `input.*` command failed on a fresh install while the editor-side commands worked. If a project was installed by an affected version, toggle the plugin off and back on in **Project Settings > Plugins**, which injects the pair. `swallowtail doctor` reports the missing entries and the repair command.

Omit `--skill=false` to also install the optional agent skill. The [terminal quickstart](https://regiellis.github.io/godot-mcp-go/docs/quickstart) builds and plays a scene from an empty project.

## Bootstrap a new project

Starting from nothing? Create a fresh Godot 4.7 project and wire the addon in one command:

```bash
swallowtail create --path ./mygame --install --enable
```

Writes a `project.godot` (config version 5, 4.7 feature tag), an original placeholder `icon.svg`, and a `.gitignore`. It never overwrites an existing `project.godot`.

## Build the CLI from source

```bash
go build -o bin/swallowtail ./cmd/swallowtail
# or, with Task installed:
task build          # -> bin/swallowtail(.exe)
```

## Pin the MCP port (per project)

The addon binds the first free port in **9080-9095** and writes it to `.godot/swallowtail.json`, so the CLI auto-discovers it and you rarely think about ports. Running **two projects at once**, pin each to a distinct port so they never contend: **Project → Project Settings → Swallowtail → Network → Port** (turn on *Advanced Settings* to see it). Set an explicit port; `0`, the default, means auto-pick.

The value is saved in that project's `project.godot`, so two concurrent projects listen deterministically on their own ports. `SWALLOWTAIL_PORT` in the environment still overrides everything, and the default `0` is never written to `project.godot`, so leaving the setting alone keeps the file clean.

## Bundled greybox assets (optional)

Copy the bundled CC0 asset packs into a project for prototyping:

```bash
swallowtail install-assets --list
swallowtail install-assets --pack kenney_prototype_textures
```

## Before you ship

The addon must not ride into an exported game. [Before you ship](https://regiellis.github.io/godot-mcp-go/docs/before-you-ship) has the two steps and the pck scan that proves they worked.

## Troubleshooting

If the CLI can't connect, run the environment preflight:

```bash
swallowtail doctor
```

It checks the godot binary and version, that the project resolves, whether the addon is installed and enabled, the effective port source (env, per-project pin, or auto), whether an editor is actually reachable, and the .NET SDK on C# projects. Pass `--project DIR` to target a specific project, or `--json` for machine-readable output. It exits non-zero only when a check fails; a warning (no editor running yet, say) doesn't fail the run, so `doctor` is safe to run before you've launched anything.

> **Windows audio note**
>
> If the editor crashes with `ERROR: WASAPI: GetBufferSize`, another app has taken *exclusive* control of your audio device. Turn off exclusive mode in Windows Sound settings, or launch with `--audio-driver Dummy`. It is an OS/audio issue, not the addon.