# Retopology Guide
BlenderMCP includes a comprehensive retopology toolkit for creating game-ready, optimized meshes from high-poly sources.
## Quick Start: Retopo Pipeline Prompt
The easiest way to start is to use the **Retopo Pipeline** prompt, which provides guided workflows:
```
Use the "retopo_pipeline" prompt to guide me through retopologizing this mesh
```
Claude will walk you through the complete process from analysis to export.
## Manual Retopology Workflows
### Workflow 1: Sculpted Character → Game-Ready
```
1. Analyze the mesh topology
2. Use QuadriFlow to create quad-dominant mesh with 8000 faces
3. Mark sharp edges at 45° for proper shading
4. Verify final polycount
```
**Example prompts:**
- "Analyze the topology of this sculpted character"
- "Use QuadriFlow to retopologize to 8000 faces, preserving sharp features"
- "Mark sharp edges at 45 degrees for clean shading"
### Workflow 2: High-Poly Scan → LOD Mesh
```
1. Clean up with voxel remesh
2. Decimate to 25% of original polycount
3. Mark UV seams automatically
4. Verify topology is clean
```
**Example prompts:**
- "Clean up this scanned mesh with voxel remesh, voxel size 0.1"
- "Decimate this mesh to 25% of its current polycount"
- "Automatically mark UV seams at 60 degree angles"
### Workflow 3: Hard-Surface Asset → Clean Topology
```
1. Detect and fix topology issues
2. Use QuadriFlow with sharp edge preservation
3. Mark sharp edges at 30° for hard-surface look
4. Check with wireframe viewport screenshot
```
## Tool Reference
### Mesh Analysis Tools
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `mesh_stats` | Get topology metrics | `active_only` (bool) |
| `detect_topology_issues` | Find topology problems | `angle_sharp` (degrees), `distance_doubles` |
**Example usage:**
- "Show me detailed topology statistics for this mesh"
- "Detect all topology issues with a 30-degree sharp angle threshold"
### Remeshing Tools
| Tool | Purpose | Key Parameters | Notes |
|------|---------|----------------|-------|
| `voxel_remesh` | Uniform topology | `voxel_size`, `adaptivity` | Good for cleanup |
| `quadriflow_remesh` | Quad-dominant mesh | `target_faces`, `preserve_sharp` | Requires manifold input |
| `decimate` | Reduce polycount | `ratio`, `mode` | Modes: COLLAPSE, DISSOLVE, UNSUBDIVIDE |
| `shrinkwrap_reproject` | Project to surface | `high`, `low`, `method` | Preserves silhouette |
**Example usage:**
- "Use voxel remesh with 0.05 voxel size to clean up this mesh"
- "Create a quad mesh with 5000 faces using QuadriFlow"
- "Decimate this mesh to 50% using collapse mode"
- "Shrinkwrap the low-poly mesh to match the high-poly surface"
### Viewport & Prep Tools
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `mark_seams_by_angle` | Auto UV seams | `angle` (degrees) |
| `mark_sharp_by_angle` | Mark sharp edges | `angle` (degrees) |
| `set_view_projection` | Toggle ortho/persp | `projection` |
| `align_view_to_axis` | Snap to axis view | `axis`, `side` |
**Example usage:**
- "Mark UV seams on edges sharper than 60 degrees"
- "Mark sharp edges at 30 degrees for hard-surface shading"
- "Switch to orthographic view"
- "Align view to front (Y positive)"
## Important Notes
### QuadriFlow Preconditions
QuadriFlow requires a **manifold mesh** with **consistent normals**. If it fails:
1. Run `detect_topology_issues()` to identify problems
2. Fix issues using suggested operations:
- Mesh > Clean Up > Merge by Distance
- Mesh > Normals > Recalculate Outside
- Fill holes manually with F key
### Best Practices
- Always run `mesh_stats()` before and after operations to track changes
- Use `detect_topology_issues()` early to catch problems
- Smaller voxel size = more detail but higher polycount
- Mark sharp edges AFTER remeshing for best results
- Use viewport screenshots to get visual feedback
### Common Issues
**"QuadriFlow requires manifold mesh"**
- Solution: Run `detect_topology_issues()`, then fix non-manifold edges and inverted normals
**"Too many/few faces after remeshing"**
- Solution: Adjust `target_faces` for QuadriFlow or `voxel_size` for voxel remesh
**"Shading looks wrong"**
- Solution: Use `mark_sharp_by_angle()` to mark hard edges after remeshing
