# Sprint 4a — Foundation + Connection Layer

## Objective

Create the GodotIQ Godot addon (pure GDScript) and the Python bridge layer that connects the MCP server to the addon via WebSocket. Implement 4 bridge tools: `godotiq_screenshot`, `godotiq_run`, `godotiq_perf_snapshot`, `godotiq_editor_context`.

After this sprint: 17 MCP tools total (13 Phase 1 + 4 bridge).

---

## IMPORTANT CONSTRAINTS

### DO NOT TOUCH these files/directories:
- `src/godotiq/parsers/` — Phase 1 parsers, working perfectly
- `src/godotiq/tools/code/` — Phase 1 tools
- `src/godotiq/tools/spatial/` — Phase 1 tools
- `src/godotiq/tools/animation/` — Phase 1 tools
- `src/godotiq/tools/assets/` — Phase 1 tools
- `src/godotiq/tools/memory/` — Phase 1 tools (project_summary, file_context)
- `src/godotiq/resolvers/` — Phase 1 resolvers
- `src/godotiq/index.py` or `src/godotiq/project_index.py` — Phase 1 project index
- `src/godotiq/session.py` — Phase 1 session layer
- `tests/` existing test files — do NOT modify, only ADD new ones
- Any file not explicitly mentioned below

### Dependencies
- Phase 2 adds ONE new Python dependency: `websockets>=12.0`
- Add it to `pyproject.toml` under `[project] dependencies`
- All existing dependencies stay untouched

### Language
- GDScript files: English comments, English variable names
- Python files: English code, English docstrings

---

## Architecture Overview

The sprint creates a bidirectional bridge:

```
Python MCP Server <--WebSocket--> Godot Editor Addon <--EngineDebugger--> Running Game
```

### Components:
1. **Godot Addon** (5 GDScript files) — EditorPlugin + WebSocket server + EngineDebugger bridge + Game runtime autoload
2. **Python Bridge Layer** (4 files) — WebSocket client + message protocol + session manager
3. **Bridge MCP Tools** (4 files) — screenshot, run, perf_snapshot, editor_context
4. **Tests** (4 files) — protocol, connection, tool tests

### Key Design Decisions:
- WebSocket server runs in editor process (port 6007, configurable via `.godotiq.json`)
- Uses `TCPServer` + `WebSocketPeer.accept_stream()` (Godot 4 pattern)
- Game-side communication via `EngineDebugger` IPC (editor ↔ game)
- Lazy bridge connection (connects on first tool use)
- Retry logic for screenshot (viewport may not be ready)
- Graceful fallback for editor_context (works without addon)

---

## Files to Create (18 total)

### Godot Addon (5 files)
| # | Path | Purpose |
|---|------|---------|
| 1 | `godot-addon/addons/godotiq/plugin.cfg` | Plugin metadata |
| 2 | `godot-addon/addons/godotiq/godotiq_plugin.gd` | EditorPlugin lifecycle |
| 3 | `godot-addon/addons/godotiq/godotiq_server.gd` | WebSocket server + dispatch |
| 4 | `godot-addon/addons/godotiq/godotiq_debugger.gd` | EngineDebugger bridge |
| 5 | `godot-addon/addons/godotiq/godotiq_runtime.gd` | Game autoload (screenshot, perf) |

### Python Bridge (4 files)
| # | Path | Purpose |
|---|------|---------|
| 6 | `src/godotiq/bridge/__init__.py` | Package init |
| 7 | `src/godotiq/bridge/protocol.py` | Message protocol (dataclasses + JSON) |
| 8 | `src/godotiq/bridge/connection.py` | Async WebSocket client |
| 9 | `src/godotiq/bridge/session.py` | Shared connection manager |

### Bridge MCP Tools (5 files)
| # | Path | Purpose |
|---|------|---------|
| 10 | `src/godotiq/tools/bridge/__init__.py` | Package init |
| 11 | `src/godotiq/tools/bridge/screenshot.py` | godotiq_screenshot tool |
| 12 | `src/godotiq/tools/bridge/run.py` | godotiq_run tool |
| 13 | `src/godotiq/tools/bridge/perf_snapshot.py` | godotiq_perf_snapshot tool |
| 14 | `src/godotiq/tools/bridge/editor_context.py` | godotiq_editor_context tool |

### Tests (4 files)
| # | Path | Purpose |
|---|------|---------|
| 15 | `tests/test_bridge/__init__.py` | Test package init |
| 16 | `tests/test_bridge/test_protocol.py` | Protocol encode/decode tests |
| 17 | `tests/test_bridge/test_connection.py` | Connection mock tests |
| 18 | `tests/test_bridge/test_tools.py` | Tool validation tests |

### Files to Modify
| Path | Change |
|------|--------|
| `pyproject.toml` | Add `websockets>=12.0` + `pytest-asyncio` |
| `src/godotiq/server.py` (or tool registration) | Register 4 new bridge tools |

---

## Protocol

### Request format (Python → Godot):
```json
{"id": "req_001", "method": "screenshot", "params": {"scale": 0.5}}
```

### Response format (Godot → Python):
```json
{"id": "req_001", "status": "ok", "result": {"image": "base64...", "width": 960}}
```

### Error format:
```json
{"id": "req_001", "status": "error", "error": {"code": "GAME_NOT_RUNNING", "message": "..."}}
```

### Event format (push, no request):
```json
{"event": "game_started", "data": {}}
```

---

## Tool Specifications

### godotiq_screenshot
- Params: viewport ("game"), scale (0.5), format ("webp"/"png"/"jpg")
- Returns: base64 image + dimensions
- Requires: game running
- Retry: 3 attempts with 0.5s delay

### godotiq_run
- Params: action ("play"/"stop"), scene ("main"/"current"/path)
- Returns: action confirmation

### godotiq_perf_snapshot
- No params
- Returns: fps, draw_calls, triangles, objects, memory, node counts
- Requires: game running

### godotiq_editor_context
- No params
- Returns: editor version, open scenes, selected nodes, game state
- Fallback: works without addon (returns filesystem info)

---

## Error Handling
Bridge errors return user-friendly dicts (not exceptions):
```python
{"error": "message", "hint": "Enable the GodotIQ addon..."}
```
