# Sprint 4b Usage Guide — Godot Bridge Tools

## Quick Start

Sprint 4b adds 4 new MCP tools for interacting with a running Godot editor and the project filesystem. After installing GodotIQ:

```bash
pip install -e ".[dev]"
```

The tools are automatically registered when the MCP server starts.

## Tools Overview

### 1. `godotiq_scene_tree` — Live Scene Tree Reader

Reads the active scene tree from a running Godot editor via WebSocket bridge.

```python
# Default: read top 3 levels of the scene tree
await godotiq_scene_tree()

# Filter to specific node types
await godotiq_scene_tree(filter_type="MeshInstance3D", depth=5)

# Read subtree from a specific root
await godotiq_scene_tree(root="Level/Enemies", include=["transform", "script"])
```

**Returns:** `{root, scene_path, total_nodes, returned_nodes, tree}`

**Requires:** Running Godot editor with GodotIQ addon enabled.

### 2. `godotiq_node_ops` — Batch Node Operations

Execute up to 50 scene tree operations as a single undo-able action.

```python
# Move and scale a node
await godotiq_node_ops(operations=[
    {"op": "move", "node": "Player", "position": [10, 0, 5]},
    {"op": "scale", "node": "Player", "scale": [2.0, 2.0, 2.0]},
])

# Add a child node
await godotiq_node_ops(operations=[
    {"op": "add_child", "parent": "Level", "type": "MeshInstance3D", "name": "NewMesh"},
])
```

**Supported ops:** `move`, `rotate`, `scale`, `set_property`, `add_child`, `delete`, `duplicate`, `reparent`

**Requires:** Running Godot editor with GodotIQ addon enabled.

### 3. `godotiq_script_ops` — GDScript File Operations

Read, write, patch, or create `.gd` files with GDScript convention validation.

```python
# Read a script
await godotiq_script_ops(op="read", path="res://scripts/player.gd")

# Patch a specific line (find-and-replace with uniqueness check)
await godotiq_script_ops(
    op="patch",
    path="scripts/player.gd",
    patches=[{"search": "var speed = 10", "replace": "var speed: float = 10.0"}],
)

# Create a new script
await godotiq_script_ops(
    op="create",
    path="scripts/new_enemy.gd",
    content="extends CharacterBody3D\n\nfunc _ready():\n\tpass\n",
)

# Dry-run validation
await godotiq_script_ops(op="write", path="test.gd", content="...", dry_run=True)
```

**No Godot editor required.** Works on the local filesystem.

### 4. `godotiq_file_ops` — General File Operations

Full filesystem operations within the Godot project directory.

```python
# List files with type filter
await godotiq_file_ops(op="list", filter="scenes", recursive=True)

# Read a file
await godotiq_file_ops(op="read", path="project.godot")

# Search across all scripts
await godotiq_file_ops(op="search", query="extends CharacterBody3D", filter="scripts")

# Directory tree with sizes
await godotiq_file_ops(op="tree", max_depth=2, show_sizes=True)

# Write a config file (use script_ops for .gd files)
await godotiq_file_ops(op="write", path="data/config.cfg", content="[settings]\nkey=value\n")

# Move/rename a file
await godotiq_file_ops(op="move", path="old_name.tscn", destination="new_name.tscn")

# Delete a file
await godotiq_file_ops(op="delete", path="temp_file.txt")
```

**Type filters:** `all`, `scenes`, `scripts`, `images`, `audio`, `fonts`, `models`, `shaders`, `resources`

**No Godot editor required.** Works on the local filesystem.

## Security

All filesystem tools enforce:
- **Path containment:** No access outside `GODOTIQ_PROJECT_ROOT`
- **Protected files:** `project.godot`, `.godot/`, `*.import`, `saves/` cannot be modified
- **Excluded directories:** `.godot`, `.git`, `__pycache__`, `node_modules`, `.import` are hidden from listing/search

## GDScript Addon

The bridge tools (`scene_tree`, `node_ops`) communicate via WebSocket with the GodotIQ addon running in the Godot editor. The addon handler is at:

- `godot-addon/addons/godotiq/godotiq_server.gd`

It processes `scene_tree` and `node_ops` requests and returns structured JSON responses.

## Running Tests

```bash
uv run pytest tests/test_bridge/ -v    # 121 bridge tests
uv run pytest -v                        # Full test suite
```
