# Usage Guide — GodotIQ Bridge Layer (Sprint 4a)

## Quick Start

### 1. Install the Godot Addon

Copy `godot-addon/addons/godotiq/` into your Godot project's `addons/` directory. Enable the plugin in **Project > Project Settings > Plugins**.

### 2. Install Python Dependencies

```bash
pip install -e ".[dev]"
# or
uv pip install -e ".[dev]"
```

This installs `websockets>=14.0` alongside the existing `mcp>=1.0.0`.

### 3. Run the MCP Server

```bash
godotiq
# or
python -m godotiq
```

The server starts on stdio transport. Bridge tools connect to the Godot addon via WebSocket on port 6007 (configurable via `GODOTIQ_ADDON_PORT` env var).

## Bridge Tools

### `godotiq_screenshot`
Capture a viewport screenshot from the running game.

```
Parameters:
  viewport: str = "game"     # Which viewport to capture
  scale: float = 0.5         # Image scale (0.0-1.0, clamped to 0.5 if invalid)
  format: str = "webp"       # "webp", "png", or "jpg" (falls back to webp)

Returns: { image: base64, format, width, height }
```

### `godotiq_run`
Start or stop the Godot game.

```
Parameters:
  action: str = "play"       # "play" or "stop"
  scene: str = "main"        # "main", "current", or "res://path/to/scene.tscn"

Returns: { action, scene }
```

### `godotiq_perf_snapshot`
Capture runtime performance metrics.

```
Returns: { fps, draw_calls, triangles, objects, texture_mem, buffer_mem,
           video_mem, total_nodes, orphan_nodes }
```

### `godotiq_editor_context`
Get live editor state (or fallback when addon not running).

```
Returns (connected): { addon_connected: true, editor_version, open_scenes, ... }
Returns (disconnected): { addon_connected: false, project_path, note }
```

## Architecture

```
MCP Client → godotiq MCP server → bridge/session.py → bridge/connection.py → WebSocket → Godot Addon
                                                                                           ↕
                                                                              EngineDebugger → Game Runtime
```

### Key Files

| File | Purpose |
|------|---------|
| `src/godotiq/bridge/protocol.py` | Wire format, timeouts, dataclasses |
| `src/godotiq/bridge/connection.py` | Async WebSocket client with retry |
| `src/godotiq/bridge/session.py` | Singleton connection manager |
| `src/godotiq/tools/bridge/__init__.py` | MCP tool wrappers with error handling |
| `src/godotiq/tools/bridge/screenshot.py` | Screenshot implementation |
| `src/godotiq/tools/bridge/run.py` | Run/stop implementation |
| `src/godotiq/tools/bridge/perf_snapshot.py` | Perf snapshot implementation |
| `src/godotiq/tools/bridge/editor_context.py` | Editor context with fallback |
| `godot-addon/addons/godotiq/` | GDScript addon (plugin, server, debugger, runtime) |

### Test Suite

```bash
pytest tests/test_bridge/ -v    # 32 bridge tests
pytest tests/ -v                # 492 total tests (460 Phase 1 + 32 bridge)
```

## Configuration

| Env Var | Default | Purpose |
|---------|---------|---------|
| `GODOTIQ_ADDON_PORT` | `6007` | WebSocket port for addon communication |
| `GODOTIQ_PROJECT_ROOT` | (none) | Fallback project path when addon disconnected |
