# Usage Guide — Sprint 3d: Animation Intelligence Tools

## Quick Start

The animation tools are registered as MCP tools on the GodotIQ server. They're available automatically when the server starts with a loaded Godot project.

```bash
# Start the MCP server (stdio transport)
python -m godotiq
```

## MCP Tools

### godotiq_animation_info

Complete animation understanding for a scene or specific node.

**Parameters:**
- `scene` (str, required): Path to .tscn file (res:// or relative)
- `node` (str, optional): Filter to a specific AnimationPlayer node
- `detail` (str, optional): `"brief"` | `"normal"` (default) | `"full"`

**Example usage in an AI assistant:**
```
Use godotiq_animation_info with scene="res://scenes/player.tscn"
```

**Example output structure:**
```json
{
  "scene": "res://scenes/player.tscn",
  "animation_players": [{
    "name": "AnimationPlayer",
    "path": "AnimationPlayer",
    "animations": [
      {"name": "idle", "length": 2.0, "loop_mode": "linear", "track_count": 4}
    ],
    "animation_count": 4
  }],
  "animation_trees": [],
  "code_animations": {
    "play_calls": ["idle", "walk", "attack"],
    "travel_calls": [],
    "anim_maps": [{"name": "ANIM_MAP", "entries": {"idle": "idle"}}],
    "looping_lists": [{"name": "LOOPING_ANIMS", "entries": ["idle", "walk"]}]
  },
  "summary": {
    "total_animations": 5,
    "total_players": 1,
    "total_trees": 0,
    "inline_count": 4,
    "code_only_count": 1,
    "sources": ["tscn_inline", "code"]
  }
}
```

### godotiq_animation_audit

Find animation problems across the project or in a specific scene.

**Parameters:**
- `scope` (str, optional): `"all"` (default) | `"scene"`
- `scene` (str, optional): Path to .tscn file when scope="scene"

**Example usage:**
```
Use godotiq_animation_audit with scope="all"
Use godotiq_animation_audit with scope="scene" scene="res://scenes/player.tscn"
```

**Example output structure:**
```json
{
  "scope": "all",
  "scenes_scanned": 12,
  "animated_scenes": 5,
  "total_animations": 28,
  "total_issues": 3,
  "by_severity": {"critical": 1, "warning": 1, "info": 1},
  "issues": [
    {
      "type": "broken_track",
      "severity": "critical",
      "scene": "res://scenes/enemy.tscn",
      "animation": "attack",
      "track_path": "NonExistent:position",
      "missing_node": "NonExistent",
      "message": "Track targets non-existent node 'NonExistent'"
    }
  ]
}
```

## Check Types (Animation Audit)

| Type | Severity | Description |
|------|----------|-------------|
| broken_track | CRITICAL | Track targets non-existent node in scene tree |
| orphan_animation | WARNING | Animation defined but never referenced in code/tree |
| missing_animation | WARNING/INFO | Code .play()s a name not found in scene (INFO for GLB) |
| empty_player | WARNING | AnimationPlayer with no animations |
| orphan_tree_state | WARNING | AnimationTree state refs animation not in player |
| code_only_animations | INFO | Animation only referenced in code, can't validate |
| no_loop_suspect | INFO | Short idle/walk/run animation without looping |

## Internal API

For direct use in tests or scripts:

```python
from godotiq.tools.animation import (
    _build_animation_info,
    _build_animation_audit,
    _extract_code_animations,
    _extract_tscn_animations,
    _extract_animation_players,
    _extract_animation_trees,
    _extract_animation_libraries,
    _build_animation_summary,
)
```

## Running Tests

```bash
# All tests (425 total)
uv run pytest -v

# Animation-specific tests
uv run pytest tests/test_tools/test_animation_info.py -v      # 12 tests
uv run pytest tests/test_tools/test_animation_audit.py -v     # 14 tests
uv run pytest tests/test_tools/test_animation_registration.py -v  # 2 tests
uv run pytest tests/test_tools/test_extraction_helpers.py -v  # extraction unit tests
```
