# build_scene Usage Guide

## Overview

`godotiq_build_scene` creates multiple Godot nodes in a single MCP call with full Ctrl+Z undo support. It replaces repeated `node_ops` add_child calls for batch node creation.

## Modes

### Grid — Tile maps, floors, walls
```python
godotiq_build_scene(parent="Terrain", grid={
    "scene": "res://tiles/grass.tscn",
    "rows": 8, "cols": 8,
    "spacing": 2.0,
    "origin": [0, 0, 0],
    "axis": "xz",           # "xz" (default) or "xy"
    "prefix": "Tile",
    "overrides": {
        "3,0": {"scene": "res://tiles/road.tscn"},
        "3,1": {"scene": "res://tiles/road.tscn", "name": "RoadTile"}
    }
})
```

### Line — Paths, fences, power lines
```python
godotiq_build_scene(parent="Fences", line={
    "scene": "res://props/fence_post.tscn",
    "points": [[0, 0, 0], [10, 0, 0], [10, 0, 10]],
    "spacing": 1.5,
    "align_to_path": True,   # Rotate nodes to face path direction
    "prefix": "Post"
})
```

### Scatter — Handpicked placements
```python
godotiq_build_scene(parent="Decorations", scatter={"items": [
    {"scene": "res://props/tree.tscn", "name": "Tree1", "position": [5, 0, 3]},
    {"scene": "res://props/rock.tscn", "name": "Rock1", "position": [8, 0, 1], "scale": [2, 2, 2]},
    {"scene": "res://props/bush.tscn", "position": [3, 0, 7]}
]})
```

### Nodes — Mixed types, scene structure
```python
godotiq_build_scene(nodes=[
    {"type": "Node3D", "name": "Terrain"},
    {"type": "Node3D", "name": "Decorations"},
    {"type": "Camera3D", "name": "MainCamera", "position": [0, 10, 10], "rotation": [-45, 0, 0]},
    {"type": "DirectionalLight3D", "name": "Sun", "rotation": [-60, 30, 0]}
])
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `target_scene` | str | "" | .tscn path (auto-detected) |
| `parent` | str | "" | Parent node path (scene root if empty) |
| `detail` | str | "brief" | Output verbosity |
| `grid` | dict | None | Grid pattern config |
| `line` | dict | None | Line pattern config |
| `scatter` | dict | None | Scatter placement config |
| `nodes` | list | None | Explicit node definitions |

## Limits

- **Max 256 nodes per call** — split larger layouts into multiple calls
- **Exactly one mode required** — grid, line, scatter, or nodes
- **30-second timeout** — large batches may take time

## Response

```json
{
    "created": 64,
    "errors": [],
    "total_requested": 64,
    "parent": "Terrain",
    "truncated": false
}
```

## Error Recovery

- `NO_SCENE` → Open a scene in Godot editor
- `PARENT_NOT_FOUND` → Create the parent node first
- `NO_NODES` → Check mode data (grid/line/scatter/nodes)
- Partial success → Check `errors` array, fix and retry
- Truncated → Split into multiple calls (< 256 nodes each)
