# Sprint 9a — Scene Construction: `godotiq_build_scene` + Creation Workflow

## Problema

L'agent AI non riesce a creare scene 3D complesse (es. griglia 8×8 di tile per un Tower Defense). Le cause:

1. **node_ops è chirurgico, non costruttivo**: fare 64 chiamate `add_child` separate è impraticabile. Anche in batch, l'agent deve generare 64 dict — non è naturale per il modello.

2. **L'agent genera codice runtime**: senza un modo efficiente di creare nodi statici, l'agent scrive uno script `map_builder.gd` che genera tile in `_ready()`. I nodi generati a runtime sono invisibili nell'editor e impossibili da debuggare.

3. **Il prompt MCP non ha un workflow di creazione**: dice come analizzare e modificare, ma non come costruire da zero.

## Soluzione

### Deliverable 1: Tool `godotiq_build_scene`

Un tool MCP che accetta descrizioni ad alto livello di scene da costruire e le crea in un colpo solo. Funziona via WebSocket → addon, come node_ops.

#### API Python-side

```python
@mcp.tool()
async def godotiq_build_scene(
    scene: str = "",              # target scene path (default: current open scene)
    parent: str = "",             # parent node path (default: scene root)
    detail: str = "brief",
    # Modes — usa UNO di questi:
    grid: dict | None = None,     # grid pattern
    line: dict | None = None,     # line pattern
    scatter: dict | None = None,  # scatter/list pattern
    nodes: list[dict] | None = None,  # explicit node list (batch add_child)
) -> dict:
```

#### Mode 1: Grid

Crea una griglia NxM di nodi. Perfetto per terreni, tile map, grids.

```python
godotiq_build_scene(
    parent="Terrain",
    grid={
        "scene": "res://assets/tile.glb",
        "prefix": "Tile",
        "rows": 8,
        "cols": 8,
        "spacing": 1.0,
        "origin": [0, 0, 0],
        "axis": "xz",
    }
)
# → Crea 64 nodi in UNA chiamata, UNA undo action
```

Con overrides per path tiles:
```python
grid={
    ...,
    "overrides": {
        "0,3": {"scene": "res://assets/tile-straight.glb", "name": "Path_0_3"},
        "1,3": {"scene": "res://assets/tile-corner.glb", "name": "Path_1_3", "rotation": [0, 90, 0]},
    }
}
```

#### Mode 2: Line

Crea nodi lungo una linea o path. Perfetto per strade, recinzioni, muri.

```python
godotiq_build_scene(
    parent="Path",
    line={
        "scene": "res://assets/fence.glb",
        "prefix": "Fence",
        "points": [[0,0,0], [5,0,0], [5,0,5]],
        "spacing": 1.0,
        "align_to_path": true,
    }
)
```

#### Mode 3: Scatter

Piazza nodi in posizioni esplicite.

```python
godotiq_build_scene(
    parent="Decorations",
    scatter={
        "items": [
            {"scene": "res://assets/tree.glb", "position": [1, 0, 2], "name": "Tree_1"},
            {"scene": "res://assets/rock.glb", "position": [3, 0, 7], "name": "Rock_1", "scale": [1.5, 1.5, 1.5]},
        ]
    }
)
```

#### Mode 4: Nodes (batch add_child semplificato)

```python
godotiq_build_scene(
    parent="Main",
    nodes=[
        {"type": "Node3D", "name": "Terrain"},
        {"type": "Camera3D", "name": "Camera", "position": [8, 10, 8], "rotation": [-35, 45, 0]},
        {"scene": "res://Enemy.tscn", "name": "Enemy_1", "position": [0, 0, 3]},
    ]
)
```

### Handler GDScript-side

Il handler in `godotiq_server.gd`:
1. Riceve i params (grid, line, scatter, o nodes)
2. Espande il pattern in lista piatta di node specs
3. Crea UNA EditorUndoRedoManager action
4. Per ogni nodo: load/instantiate, set transform/properties, add_child
5. Commit action
6. Restituisce conteggio + errori

Pattern da replicare: guardare come `_handle_node_ops` gestisce `add_child` con undo/redo.

### Deliverable 2: Sezione "Creation Workflow" nel prompt MCP

Aggiungere al prompt MCP una sezione che guida l'agent attraverso il workflow di creazione:
1. Setup scene structure (nodes mode)
2. Build terrain (grid mode)
3. Add decorations (scatter mode)
4. Add key objects (placement + scatter)
5. Create scripts (logic only)
6. Verify (spatial_audit + signal_map + save)

### Deliverable 3: Tests

- Unit test per expand_grid: N nodi, spacing, overrides
- Unit test per expand_line: spacing, rotation, multi-segment
- Integration test: grid 3x3, scatter 3 items, nodes 4 items
- Backward compatibility: tutti i test esistenti passano

## File da creare/modificare

| File | Azione |
|------|--------|
| `src/godotiq/tools/bridge/build_scene.py` | CREA |
| `godot-addon/addons/godotiq/godotiq_server.gd` | MODIFICA |
| `src/godotiq/server.py` | MODIFICA |
| `src/godotiq/prompts/godot_development.md` | MODIFICA |
| `tests/test_tools/test_build_scene.py` | CREA |

## File da NON toccare

- File bridge esistenti (node_ops, script_ops, etc.)
- Parser
- Tool esistenti (scene_map, spatial_audit, etc.)
- Test esistenti
