description: AAA-quality modeling playbook for the Blender MCP. Read BEFORE any modeling task. Codifies the AlphaFold-style refinement loop, reference-grounded modeling, parametric-first strategy, post-processing pipeline (retopo+UV+bake) and quality gates. Load when the user asks to "model X", "build Y", "create a chair/character/vehicle/environment" or anything that requires 3D content beyond a single primitive.

AAA Modeling Playbook

You are about to make 3D content with the blender-agent MCP. The default agent reflex is "call /object/create with a cube and hope." That reflex produces blockouts, not assets. This skill rewires it.

Three rules, drilled in:

No mesh before a brief. You collect references, write a spec, lock proportions, THEN model.
Recycle, don't lance. Model → render → critique → fix → repeat. The AlphaFold playbook: iteration 1 has 90% violations, iteration 8 has zero.
Parametric > generative > primitive. Try the parametric library first. Generate (external API) second. Hand-build with primitives only when nothing else fits.

The pipeline (canonical order)

flowchart TD
    A[1. Brief & references] --> B[2. Spec sheet]
    B --> C{3. Strategy}
    C -->|known shape| D[Parametric library]
    C -->|complex, organic| E[External generation]
    C -->|simple geometry| F[Primitive blockout]
    D --> G[4. Render contact sheet]
    E --> G
    F --> G
    G --> H[5. Self-critique]
    H -->|score < threshold| I[6. Refine]
    I --> G
    H -->|score >= threshold| J[7. Post-processing]
    J --> K[8. Validation & export]

Phase 0 — Make sure Blender is open (do this first, always)

Before any modeling tool call, call blender_launch. It reuses an already-open Blender if one is reachable, or launches a GUI Blender from the default install path otherwise. This guarantees:

tool calls don't fail with BLENDER_UNREACHABLE,
vision_snapshot gets the fast viewport path (instant) instead of falling back to a render,
the user can watch the work happen in a real window.

If you ever need to recover a wedged session, blender_quit then blender_launch. addon_restart reloads addon code without quitting.

Phase 1 — Brief & references (always, no exceptions)

Before any tool call, write a one-paragraph brief:

"Beach chair, Brazilian beach style, ~1.7m long, low recliner (~30° back angle), weathered teak frame, faded orange canvas, 7 wooden slats on the seat. Target: hero prop, exportable to UE5."

Then gather references. Free sources, in order:

| Source | When | How to access | |---|---|---| | Web search via the workspace web tool | Always start here | Search for "<object> reference sheet front side top", "<object> blueprint", "<object> turnaround" | | Polyhaven | HDRIs + sometimes models | Free, CC0 | | Sketchfab | Read-only inspection | Free models filterable | | [Three.dropbox folder of pose refs] | Character anatomy | Generic searches | | Existing assets in bpy.data | Continuing a session | /object/list + /render/render_still of a turntable |

You want at minimum 3 references: front, side, plus one stylistic/contextual reference. This mirrors AlphaFold's MSA — multiple aligned views constrain the answer.

If the user provided no references and the subject is non-trivial, ASK for at least one or use web search. Don't model blind.

Phase 2 — Spec sheet

Write a structured spec into your scratchpad before the first MCP call:

target: beach_chair
class: furniture/recliner
dimensions_m: [length: 1.70, width: 0.60, height_max: 0.95]
proportions:
  recline_angle_deg: 28
  seat_height_m: 0.40
  slat_count: 7
materials:
  frame: weathered_teak
  fabric: faded_canvas_orange
quality_target: hero_prop
polycount_budget: 8000_tris
texture_resolution: 2048
deliverables: [blend_file, fbx_export, render_turntable]

This spec drives every parameter call later. Anchored numbers in the spec ⇒ deterministic agent behavior. Drifting from the spec is a code smell.

Phase 3 — Strategy decision

Before modeling, branch:

Path A — Parametric (PREFERRED when applicable)

If the subject is in BlenderAgent/library/ (furniture, generic vegetation, basic vehicles), use it. One call → topologically clean mesh with correct proportions.

/parametric/list                    # see what's available
/parametric/build  name="chair_beach" params={length: 1.70, ...}

Parametric gives you: correct topology, predictable polycount, named parts (Seat, BackSlat_1..7, Leg_FL/FR/BL/BR), already-applied scale, ready-for-rigging.

Path B — External generation (when parametric absent)

For organic / one-off / "creative" shapes (dragon, sculpted bust, alien tree). Currently delegated to external services through their addon installs:

Hunyuan3D 2.1 (open-source, local, 16GB VRAM) — hy3dgen Python package + their addon.
Tripo3D / Meshy / Rodin (commercial APIs).

This skill does NOT implement those bridges yet — but when you face a "model me a dragon" prompt, write a TODO and fall back to Path C, then surface the gap.

Path C — Primitive blockout (last resort)

Building from CUBE, CYLINDER, etc. via /object/create. Only use for:

Architecture / level blockouts where geometry IS boxes.
Stylized low-poly where the look IS primitive.
Bootstrapping a base mesh that will be sculpted/remeshed afterwards.

If you find yourself doing more than ~10 primitive calls for a single "asset", STOP. You're rebuilding the parametric library inline. Promote that asset into BlenderAgent/library/ first.

Phase 4 — Look at what you built (the AlphaFold loop step 1)

After ANY model change, look at it before doing anything else. Two tiers — don't confuse them:

Inner loop (every iteration) → vision_snapshot. One fast PNG. On a GUI Blender it's an instant viewport screenshot; in background it falls back to a single ~16-sample EEVEE render. Sub-second either way. This is what you call dozens of times while refining.

vision_snapshot
  objectNames=["Chair_Frame", "Chair_Seat", "Chair_Back"]
  angle="three_quarter"
  outputPath="<workspace>/scripts/_out/critique/<asset>_iter_<N>.png"

Final gate (once, when the silhouette is approved) → vision_contact_sheet. 4 angles in a 2×2 grid, for the all-sides sign-off before post-processing/export.

vision_contact_sheet
  objectNames=[...]
  angles=["front","side","back","three_quarter"]
  resolution=512        # samples default 16, engine default EEVEE — both fast
  outputPath=".../contact_<asset>.png"

Never run a full Cycles beauty render inside the refine loop — it blocks the single Blender main thread for tens of seconds per frame and stalls everything behind it. Keep critique renders on EEVEE + low samples (the defaults). Cycles is for the final hero shot only.

Also useful:

vision_turntable — N renders rotating 360° (animation review). Heavy; use sparingly.
vision_topology_inspect — quad/tri/ngon counts, manifold/non-manifold edges, normal consistency, bounding box.
vision_scale_report — compares object dims against the spec.

Phase 5 — Self-critique (the recycling)

You are a multimodal LLM. Look at the contact sheet. Compare against the brief and references.

Score on 6 axes (1–5 each, target ≥4 across the board):

| Axis | Failure mode | |---|---| | Silhouette | Doesn't read as the intended object at a glance | | Proportions | Limbs/components wrong scale relative to each other | | Topology | Visible n-gons, pinching, intersecting geometry | | Material readability | Cores lavadas, no specular variation, missing roughness | | Lighting | Flat, no contact shadows, no rim light | | Reference match | If references provided, side-by-side dissimilar |

If any axis < 4, list the specific issue and the specific fix:

Axis: Proportions — score 2. Issue: backrest 30% too short compared to ref image. Fix: /parametric/update name="chair_beach" params={backrest_length_m: 0.85}.

This structured critique IS the recycling. Without it, refinement is a guess.

Phase 6 — Refine

Apply ONE class of fix per iteration. Don't change parameters AND materials AND lighting in the same iteration — you won't know which moved the score. (This is also AlphaFold discipline: each recycling step refines a specific representation, not everything at once.)

Stop when:

All 6 axes ≥ 4, OR
5 iterations passed without score increase (you're in a local minimum — change strategy: try Path B, or change reference, or escalate to user).

Phase 7 — Post-processing pipeline

Once silhouette is approved, run the AAA pipeline:

1. /mesh/voxel_remesh       voxelSize=0.005       # uniform topology, removes intersections
2. /mesh/quad_remesh        targetQuads=4000      # QuadriFlow → quad-dominant topology
3. /mesh/shade_smooth                              # smooth normals + autosmooth
4. /uv/smart_project        angleLimit=66          # one-shot UV unwrap
5. /material/create_pbr     name="Frame"           # PBR material slot
6. /bake/bake_texture       map="DIFFUSE"          # bake albedo to 2k
7. /bake/bake_texture       map="NORMAL"           # bake normal map
8. /modifier/add            type="DECIMATE" ratio=0.5  # LOD1
9. /export/fbx              ...                    # ready for engine

Each step has known knobs. The spec tells you what numbers to pass.

Phase 8 — Validation & export

Final gates:

| Check | Tool | Pass criterion | |---|---|---| | Polycount within budget | /vision/topology_inspect | tris ≤ spec polycount_budget | | Single mesh per logical part | /object/list | counts match spec parts | | No n-gons | /vision/topology_inspect | ngonCount == 0 (unless explicitly allowed) | | UVs unwrapped | /uv/info (TODO: add if missing) | every selectable face has UV | | Dimensions sane | /vision/scale_report | within 10% of spec | | Final render acceptable | /vision/contact_sheet + self-critique | all 6 axes ≥ 4 |

Then export and commit the demo script that built it.

The AlphaFold transferred principles (cheat sheet)

| AF concept | Modeling-3D equivalent | Where it lives in this MCP | |---|---|---| | MSA (multiple sequence alignment) | Multi-reference grounding | Phase 1 — gather ≥3 refs | | Pair representation (residue-i × residue-j) | Anatomy/proportions matrix | BlenderAgent/library/anatomy/proportions.py | | Recycling (iterate the whole model 8× before output) | Render-critique-refine loop | Phase 4–6 | | pLDDT (per-residue confidence) | Per-part topology/scale report | /vision/topology_inspect, /vision/scale_report | | SE(3)-equivariant transformer | Local-space tool operations | Every tool that operates on object-local axes | | Diffusion refinement (AF3) | Post-processing pipeline | Phase 7 |

Common failures and their fixes

| Symptom | Real cause | Fix | |---|---|---| | "It looks like blocks." | Phase 1 skipped. No references, no spec. | Stop modeling. Go gather references. Write spec. Restart. | | "Render is washed out." | Color management compensation forgotten. | Hyper-saturate Base Color (×2.5) or switch view transform to Standard. | | "Mesh has holes / intersects itself." | Modelled at primitive level, never unified. | /mesh/voxel_remesh before any other postproc. | | "Won't import to engine." | UVs missing / non-manifold / scale not applied. | Phase 7 + Phase 8 ran in full. | | "Took 100 calls to make a chair." | Strategy decision skipped Path A. | Add to parametric library. Future calls = 1. | | "Agent keeps refining the same problem." | No structured critique scoring. | Force the 6-axis score; require numbers. |

When to escalate to user

Subject explicitly demands hand-sculpted detail (faces, hands, fur close-ups) — out of scope for parametric/primitive paths.
Reference image needed but no web access + user didn't provide.
Polycount budget impossible (e.g. "low-poly dragon at 500 tris" but spec needs scales).
Spec internally inconsistent (length=2m, width=3m, slat_count=200 on 0.5m wide chair).

Escalate by writing a one-line message in your response, not by halting silently.

Where to look next

BlenderAgent/library/anatomy/proportions.py — proportion priors for humans, common animals, furniture.
Tools/test/tools/vision.test.ts — examples of contact_sheet usage.
scripts/demo_beach_chair_v2.ps1 — end-to-end example using parametric + visual loop.
.claude/skills/tool-chains/SKILL.md — composing tools into atomic flows.

AAA Blender Modeling Playbook

Recommended for