# Scene Tools Architecture

Scene tools cover scene-state queries, helper-object creation, viewport capture, scene maintenance, and scene-level truth/inspection operations.

This file is a family/internals reference.
It includes both:

- direct scene atomics
- grouped scene tools such as `scene_context`, `scene_create`, and `scene_inspect`

Inventory existence here does **not** imply public-default exposure on production-oriented MCP surfaces.
For normal guided usage, prefer goal-first entry through `router_set_goal(...)` and grouped scene surfaces where available.

For grouped scene tools, see `MEGA_TOOLS_ARCHITECTURE.md`.

---

# 1. scene_list_objects ✅ Done
Lists objects in the scene.

Example:
```json
{
  "tool": "scene_list_objects",
  "args": {}
}
```

---

# 2. scene_delete_object ✅ Done
Deletes a specific object.

Example:
```json
{
  "tool": "scene_delete_object",
  "args": {
    "name": "Cube.001"
  }
}
```

---

# 3. scene_clean_scene ✅ Done
Cleans the scene (by default keeps lights and cameras).

Example:
```json
{
  "tool": "scene_clean_scene",
  "args": {
    "keep_lights_and_cameras": true
  }
}
```

---

# 4. scene_duplicate_object ✅ Done
Duplicates an object and optionally moves it.

Example:
```json
{
  "tool": "scene_duplicate_object",
  "args": {
    "name": "Cube",
    "translation": [2.0, 0.0, 0.0]
  }
}
```

---

# 5. scene_set_active_object ✅ Done
Sets an object as active (important for modifiers).

Example:
```json
{
  "tool": "scene_set_active_object",
  "args": {
    "name": "Cube"
  }
}
```

---

# 6. scene_get_viewport ✅ Done
Gets a scene preview (viewport render) with selectable output mode.

Semantics:
- `camera_name="USER_PERSPECTIVE"` follows the live active 3D viewport
- named-camera capture follows render visibility, not only viewport visibility
- use `scene_isolate_object(...)` or `scene_hide_object(..., hide_render=True)`
  when the isolated set must also apply to named-camera screenshots

Args:
- width: int
- height: int
- shading: str (SOLID, WIREFRAME, MATERIAL, RENDERED)
- camera_name: str (optional)
- focus_target: str (optional - object to frame)
- output_mode: str ("IMAGE" default – FastMCP Image resource, or "BASE64", "FILE", "MARKDOWN")

Example:
```json
{
  "tool": "scene_get_viewport",
  "args": {
    "width": 1024,
    "height": 768,
    "shading": "WIREFRAME",
    "camera_name": "USER_PERSPECTIVE",
    "focus_target": "Cube"
  }
}
```

---

# 7. scene_create_light ✅ Done
Creates a light source.

Args:
- type: str (POINT, SUN, SPOT, AREA)
- energy: float (Watts)
- color: [r, g, b]
- location: [x, y, z]

Example:
```json
{
  "tool": "scene_create_light",
  "args": {
    "type": "POINT",
    "energy": 1000.0,
    "color": [1.0, 0.5, 0.0],
    "location": [0.0, 0.0, 5.0]
  }
}
```

---

# 8. scene_create_camera ✅ Done
Creates a camera object.

Args:
- location: [x, y, z]
- rotation: [rx, ry, rz] (radians)
- lens: float (focal length mm)

Example:
```json
{
  "tool": "scene_create_camera",
  "args": {
    "location": [0.0, -10.0, 5.0],
    "rotation": [1.1, 0.0, 0.0],
    "lens": 85.0
  }
}
```

---

# 9. scene_create_empty ✅ Done
Creates an Empty object (helper/parent).

Args:
- type: str (PLAIN_AXES, CUBE, SPHERE, etc.)
- size: float
- location: [x, y, z]

Example:
```json
{
  "tool": "scene_create_empty",
  "args": {
    "type": "CUBE",
    "size": 2.0,
    "location": [0.0, 0.0, 0.0]
  }
}
```

---

# 10. scene_get_mode ✅ Done
Reports the current Blender mode, active object, and selection count so AI agents can branch logic safely.

Example:
```json
{
  "tool": "scene_get_mode",
  "args": {}
}
```

---

# 11. scene_list_selection ✅ Done
Lists current selection information. In Object Mode it returns the selected object names/count. In Edit Mode it includes selected vertex/edge/face counts.

Example:
```json
{
  "tool": "scene_list_selection",
  "args": {}
}
```

---

# 12. scene_inspect_object ✅ Done
Provides a structured report for a specific object (transform, collections, materials, modifiers, mesh stats, custom properties).

Example:
```json
{
  "tool": "scene_inspect_object",
  "args": {
    "name": "Cube"
  }
}
```

---

# 13. scene_snapshot_state ✅ Done
Captures a lightweight JSON snapshot of the scene state (object transforms, hierarchy, modifiers, selection) for client-side storage and later diffing.

Args:
- include_mesh_stats: bool (default False) - includes vertex/edge/face counts for meshes
- include_materials: bool (default False) - includes material names assigned to objects

Returns: Dict with `hash` (SHA256 for change detection) and `snapshot` (JSON payload)

Example:
```json
{
  "tool": "scene_snapshot_state",
  "args": {
    "include_mesh_stats": true,
    "include_materials": false
  }
}
```

---

# 14. scene_compare_snapshot ✅ Done
Compares two scene snapshots and returns a structured diff summary (added/removed/modified objects).

Args:
- baseline_snapshot: str (JSON string from scene_snapshot_state)
- target_snapshot: str (JSON string from scene_snapshot_state)
- ignore_minor_transforms: float (default 0.0) - threshold for ignoring small transform changes

Note: This tool runs entirely on the MCP server side without requiring RPC to Blender.

Example:
```json
{
  "tool": "scene_compare_snapshot",
  "args": {
    "baseline_snapshot": "{...}",
    "target_snapshot": "{...}",
    "ignore_minor_transforms": 0.001
  }
}
```

---

# 15. scene_inspect_material_slots ✅ Done
Audits material slot assignments across the entire scene, providing a comprehensive view of how materials are distributed across all objects.

Args:
- material_filter: str (optional) - filter results by material name
- include_empty_slots: bool (default True) - include slots with no material assigned

Returns structured data including:
- total_slots: total number of material slots
- assigned_slots: number of slots with materials
- empty_slots: number of empty slots
- warnings: list of issues (empty slots, missing materials)
- slots: detailed slot data for each object

Example:
```json
{
  "tool": "scene_inspect_material_slots",
  "args": {
    "material_filter": null,
    "include_empty_slots": true
  }
}
```

---

# 16. scene_inspect_mesh_topology ✅ Done
Reports detailed topology stats for a given mesh object (vertex/edge/face counts, triangle/quad/ngon distribution). Optionally performs expensive checks for non-manifold geometry.

Args:
- object_name: str
- detailed: bool (default False) - if True, checks for non-manifold edges and loose geometry.

Returns: Dict with:
- vertex_count, edge_count, face_count
- triangle_count, quad_count, ngon_count
- non_manifold_edges (if detailed)
- loose_vertices, loose_edges (if detailed)

Example:
```json
{
  "tool": "scene_inspect_mesh_topology",
  "args": {
    "object_name": "Cube",
    "detailed": true
  }
}
```

---

# 17. scene_inspect_modifiers ✅ Done
Audits modifier stacks for a specific object or the entire scene. returns details like enabled state, viewport/render visibility, and type-specific properties (e.g., Subsurf levels).

Args:
- object_name: str (optional) - if None, scans all objects.
- include_disabled: bool (default True) - if False, skips modifiers disabled in both viewport and render.

Example:
```json
{
  "tool": "scene_inspect_modifiers",
  "args": {
    "object_name": "Cube",
    "include_disabled": false
  }
}
```

---

# 18. scene_get_constraints ✅ Done (internal via scene_inspect)
Returns object (and optional bone) constraints.

**Note:** Internal action (no `@mcp.tool`). Use `scene_inspect(action="constraints", ...)`.

Args:
- object_name: str
- include_bones: bool (default False)

Returns: Dict with:
- constraints (object-level)
- bone_constraints (optional, for armatures)

Example:
```json
{
  "tool": "scene_inspect",
  "args": {
    "action": "constraints",
    "object_name": "Rig",
    "include_bones": true
  }
}
```

---

# 19. scene_set_mode ✅ Done
Sets the Blender interaction mode (OBJECT, EDIT, SCULPT, POSE, WEIGHT_PAINT, TEXTURE_PAINT).

**Tag:** `[SCENE][SAFE]`

Args:
- mode: str - target mode (case-insensitive)

Example:
```json
{
  "tool": "scene_set_mode",
  "args": {
    "mode": "EDIT"
  }
}
```

Use Case:
- Switching between Object and Edit mode for mesh operations
- Critical for workflows requiring mode changes

---

# Rules
1. **Prefix `scene_`**: All tools must start with this prefix.
2. **Atomicity**: One tool = one action. Do not group actions into one tool with an `action` parameter.
