# Configuration

The plugin accepts user-level Cordis configuration and a small set of safe runtime controls.

| Field | Default | Description |
|---|---:|---|
| `enabled` | `true` | Enables the plugin bundle. |
| `godotExecutable` | empty | Absolute path to an existing Godot executable. |
| `preferredMode` | `web` | Initial `web` or `native` mode. |
| `autoRebuild` | `true` | Rebuild after relevant project file changes. |
| `debounceMs` | `600` | File-change debounce delay. |
| `webExportPreset` | `Web` | Godot Web export preset name. |
| `outputDirectory` | `.godot-harness/web` | Project-relative managed output directory. |
| `bindHost` | `127.0.0.1` | Fixed loopback binding. Other values are rejected. |
| `port` | `auto` | Dynamic port or a bounded explicit local port. |
| `maxLogLines` | `2000` | Maximum retained log entries. |
| `exportTimeoutMs` | `120000` | Web export timeout. |
| `processGraceMs` | `2000` | Grace period before forced child-process cleanup. |

## Persisted user settings

Changes made in the plugin Settings view are stored in `godot-preview.settings.json` under `DSH_HOME`. Only `godotExecutable`, `preferredMode`, `autoRebuild`, and `debounceMs` are persisted. The file contains no credentials. Leaving `godotExecutable` empty enables PATH discovery; every discovered executable is resolved to an absolute real path before launch.

## Project requirements

The active Harness conversation workspace is the security root and must contain a regular `project.godot` file. The Client obtains this path from the authenticated `sessions` service rather than browser text input. Generated preview content is written below `.godot-harness`; the plugin does not edit scenes, scripts, assets, or the project's formal release directory.

Recommended `.gitignore` entry:

```gitignore
.godot-harness/
```

The plugin does not add this entry without user action. Watch events below `.git`, `.godot`, `.godot-harness`, `build`, `dist`, `export`, `logs`, and `node_modules` are ignored. Recursive watching is supported on the target Windows/macOS platforms; unsupported platforms keep manual rebuild available and report a warning.

The initial release manages one active preview service per installed Web profile. Starting a different workspace disposes the previous managed preview before switching.

## Web preset

Create a Godot Web export preset named `Web`. For the broadest compatibility, use GDScript and the Compatibility renderer. Threaded Web builds require cross-origin isolation headers; the initial plugin workflow is optimized for a non-threaded Debug export.