# Sprint 11a — Complete Specification

## Overview

Fix 7 critical issues discovered during a "Living Miniature City" build test with GodotIQ. All issues impact usability of the AI-assisted Godot development workflow. Additionally, create a new `verify_motion` tool and rewrite the MCP development prompt.

## Scope

### Files to Modify
| File | Changes |
|------|---------|
| `godot-addon/addons/godotiq/godotiq_server.gd` | Fix run handler, add reload_script + set_main_scene handlers, add node_names to build_scene response, add filesystem scan |
| `src/godotiq/tools/bridge/run.py` | Add adaptive timeout based on project asset count |
| `src/godotiq/tools/bridge/script_ops.py` | Add best-effort bridge reload after .gd writes |
| `src/godotiq/tools/bridge/build_scene.py` | Pass-through (node_names comes from GDScript side) |
| `src/godotiq/tools/bridge/verify_motion.py` | NEW — verify property changes over time |
| `src/godotiq/tools/bridge/__init__.py` | Register verify_motion MCP tool |
| `src/godotiq/prompts/godot_development.md` | NEW — fresh prompt with all quirks and patterns |

### Files NOT to Touch
- Parsers (`src/godotiq/parsers/`)
- Analysis tools (scene_map, dependency_graph, etc.)
- Existing tests (must pass unchanged)

---

## Issue 1: play_main_scene() Unreliable — Switch to play_current_scene()

### Problem
`EditorInterface.play_main_scene()` returns "launched" but `is_playing_scene()` remains false. The game doesn't start. No error is raised.

### Root Cause (from research)
`play_main_scene()` can silently fail if the main scene path is not properly set or the project hasn't been saved recently. This is a known Godot editor quirk.

### Solution
Replace `_handle_run` in `godotiq_server.gd`:

1. **Always use `play_current_scene()`** instead of `play_main_scene()`
2. **Auto-open scene before playing**: If a scene param is provided, call `EditorInterface.open_scene_from_path()` first. If no scene param and no scene is open, read `application/run/main_scene` from ProjectSettings and open that.
3. **Increase default timeout** from 5s to 15s
4. **Use 0.25s polling** instead of 0.5s for faster detection
5. **Return success/failure** in the response with `waited_seconds`

### Edge Cases
- No scene param AND no scene open AND no main_scene in project.godot → Return error "No scene to play"
- Scene param doesn't end with .tscn → Search for it
- Scene param doesn't start with res:// → Prepend it

---

## Issue 2: Script Cache Staleness After .gd Creation

### Problem
When a new .gd file is created via `script_ops`, Godot's internal cache doesn't recognize it. `can_instantiate()` returns false. The pre-flight check in `_handle_run` may reject the scene.

### Root Cause (from research)
Godot's `global_script_class_cache` and resource database are not updated until `filesystem.scan()` is called. `GDScript.reload()` is needed for individual script recompilation.

### Solution

**A) New GDScript handler: `reload_script`**
- Loads the script via `load(path)`
- Calls `.reload()` on it
- Calls `EditorInterface.get_resource_filesystem().scan()`
- Returns `{reloaded: true/false, error: "..."}`

**B) Python-side integration in `script_ops.py`**
- After any write/create of a .gd file, attempt `bridge.request("reload_script", params={"path": path})`
- Best effort — silently skip if bridge is not connected
- No new response fields; the reload is transparent

**C) Filesystem scan in `build_scene`**
- After creating nodes, call `EditorInterface.get_resource_filesystem().scan()` to ensure any scene resources are recognized

---

## Issue 3: class_name Problems with New Scripts

### Problem
Using `class_name` on scripts created during the current editor session causes "not found" / "cannot instantiate" errors due to cache staleness.

### Solution
Document the `load()` pattern in the MCP prompt as the recommended approach for scripts created during a session. This is a prompt-only fix — no code changes needed beyond Issue 2's reload mechanism.

---

## Issue 4: Timeout Too Short for Asset-Heavy Projects

### Problem
5-second hardcoded timeout. Projects with 120+ GLB files need 10-12 seconds to load.

### Root Cause (from research)
Godot loading times scale with file count: 17-68 seconds reported for 20,000+ file projects. Even for 100+ GLB files, 10-15 seconds is typical.

### Solution

**A) GDScript side**: Default timeout increased to 15s (part of Issue 1 fix)

**B) Python side**: Adaptive timeout in `run.py`:
- Count `.glb` files in project root
- >100 GLB → 20s timeout
- >50 GLB → 15s timeout
- Otherwise → 10s timeout
- User can override with explicit timeout parameter

**C) Prompt**: Document loading expectations

---

## Issue 5: Node Not Found in Scene Tree

### Problem
Nodes created by build_scene are not found later because state_inspect (game-side) uses `get_node_or_null()` which requires exact paths.

### Solution

**A) build_scene returns `node_names`**: Add a `node_names` array to the response listing all created node names. This gives the agent exact names to reference.

**B) Note**: `_find_node_by_name_or_path` already has recursive fallback in the editor-side code. The game-side `state_inspect` is forwarded to the runtime and not controlled by the editor server, so improving it requires runtime changes which are out of scope. The `node_names` response helps the agent construct correct paths.

---

## Issue 6: Cannot Verify Animations/Movement

### Problem
Screenshots are single frames — cannot verify if objects are moving or animating.

### Solution

**A) New MCP tool: `godotiq_verify_motion`**
- Takes a node path, property name, and duration
- Captures property value, waits, captures again
- Returns before/after values and a "MOVING" or "STATIC" verdict

**B) Prompt pattern**: Document the "double state_inspect" pattern as a manual alternative

---

## Issue 7: Cannot Set Main Scene Programmatically

### Problem
No way via GodotIQ to set `application/run/main_scene` in project.godot.

### Solution

**A) New GDScript handler: `set_main_scene`**
- Takes a scene path parameter
- Calls `ProjectSettings.set_setting("application/run/main_scene", path)`
- Calls `ProjectSettings.save()`
- Returns success/failure

**B) Integration into run flow**: When `_handle_run` is called with a scene param and the main_scene is not set in project.godot, automatically call set_main_scene before playing.

**C) No separate Python MCP tool** — handled entirely in GDScript, exposed through the run flow and exec.

---

## New Prompt File: godot_development.md

Create a fresh version of the MCP prompt incorporating:
- All existing tool reference and workflows from the git HEAD version
- New "Known Godot Quirks" section (Issues 1-7)
- Script Loading Pattern guidance (load() vs class_name)
- Verifying Movement and Animations pattern
- Game Loading Time documentation
- Setting Main Scene guidance

---

## Verification Requirements

### Automated
- `pytest tests/ -v` must pass with no regressions
- All existing test files remain unchanged

### Manual Testing Checklist
1. Write .gd with error → verify reload catches it
2. `run(action="play", scene="res://Main.tscn")` → verify opens and runs
3. Project with 100+ GLB → verify no timeout
4. `build_scene` → verify `node_names` in response
5. verify_motion tool → verify MOVING/STATIC detection
6. Addon GDScript → verify no syntax errors, all existing handlers work

### Addon Correctness
Per user request: ensure the godotiq_server.gd changes are syntactically valid and don't break any existing handler flow. The dispatch table must remain complete and correct.
