# Usage Guide: check_errors Feature (Sprint S10B)

## Quick Start

### MCP Tool: `godotiq_check_errors`

Check GDScript files for compilation/parse errors before running the game.

```python
# Check current scene scripts + autoloads (default)
result = await godotiq_check_errors(scope="scene")

# Check all .gd files in the project
result = await godotiq_check_errors(scope="project")

# Check a specific file
result = await godotiq_check_errors(scope="res://scripts/player.gd")
```

### Pre-Run Gate

The `godotiq_run` tool now automatically validates scripts before starting the game. If broken scripts are found, it returns a `SCRIPT_ERRORS` error instead of starting:

```
{"error": "[SCRIPT_ERRORS] Cannot start game: 2 script(s) have errors. Use godotiq_check_errors for details."}
```

## Example Output

### Clean Result
```json
{
    "errors": [],
    "total": 0,
    "scripts_checked": 12,
    "scope": "scene"
}
```

### Errors Found
```json
{
    "errors": [
        {"file": "res://scripts/player.gd", "line": 42, "error": "Identifier not found: TONE_MAP_ACES"},
        {"file": "res://scripts/enemy.gd", "line": 0, "error": "Script has parse errors (cannot instantiate)"}
    ],
    "total": 2,
    "scripts_checked": 15,
    "scope": "scene"
}
```

## API Reference

### Bridge Wrapper: `check_errors(scope="scene") -> dict`
- Location: `src/godotiq/tools/bridge/check_errors.py`
- Thin wrapper calling `bridge.request("check_errors", params={"scope": scope})`
- Timeout: 15 seconds (configured in `src/godotiq/bridge/protocol.py`)

### MCP Tool: `godotiq_check_errors(scope="scene") -> dict`
- Location: `src/godotiq/tools/bridge/__init__.py`
- Annotations: readOnly, idempotent, non-destructive
- Error handling: BridgeConnectionError, BridgeTimeoutError, BridgeError, Exception
- Output limited via `apply_output_limit(result, "normal")`

### GDScript Handler: `_handle_check_errors(peer_id, id, params)`
- Location: `godot-addon/addons/godotiq/godotiq_server.gd`
- Scopes: "project" (all .gd), "scene" (tree + autoloads), or specific res:// path
- Uses `load() + can_instantiate() + reload()` for script validation
- Logger enrichment on Godot 4.5+ for detailed line/message info
- Reentrancy guarded via `_checking_errors` flag

### GDScript Pre-Run Check: `_handle_run` modification
- Location: `godot-addon/addons/godotiq/godotiq_server.gd`
- Saves all scenes, collects scripts from PackedScene.get_state()
- Synchronous `load() + can_instantiate()` validation
- Returns `SCRIPT_ERRORS` error and blocks game start if broken scripts found

### GDScript Logger: `godotiq_logger.gd`
- Location: `godot-addon/addons/godotiq/godotiq_logger.gd`
- Extends Godot 4.5+ Logger class
- Captures script error details (file, line, message) via `_log_error`
- Conditionally loaded at runtime; gracefully skipped on Godot < 4.5

## Files Created/Modified

| File | Type |
|------|------|
| `godot-addon/addons/godotiq/godotiq_logger.gd` | New — Logger subclass |
| `godot-addon/addons/godotiq/godotiq_server.gd` | Modified — handler, helpers, pre-run check |
| `src/godotiq/tools/bridge/check_errors.py` | New — bridge wrapper |
| `src/godotiq/tools/bridge/__init__.py` | Modified — MCP tool registration |
| `src/godotiq/bridge/protocol.py` | Modified — timeout config |
| `src/godotiq/prompts/godot_development_prompt_v2.md` | Modified — 5 prompt updates |
| `tests/test_tools/test_check_errors.py` | New — 17 tests |
