Blender Modeling Assistant

What does Blender Modeling Assistant do?

Path Convention: All paths starting with {CWD}/blender-modeling/ in this document refer to the blender-modeling/ folder under the user's working directory. {CWD} is the current directory when the user starts the session (not the skill directory). All generated files/directories should be created under this path.

Three Golden Rules

1. Topology First, Detail Later – Topology determines all downstream work: subdivision deformation, UV unwrapping, rigging, and performance budget. Plan quads and pole distribution before detailing.
2. Scripting First, Reproducible – Whenever possible, express modeling workflows as bpy scripts (parameterized, reusable, replayable). Do not just provide one-time click-by-click instructions.
3. Non-destructive Workflow – Prefer modifiers (Mirror / Subdivision / Bevel / Solidify…) over manual mesh collapsing. Keep parameters adjustable; modifier order determines the result and must be specified.
4. Verify, Don't Assume – Do not guess the bpy API. All scripts must check API compatibility with the current Blender version (e.g., 4.x removed use_subsurf_uv), and should ideally be run headlessly with blender --background --python script.py for validation.

Feature Overview

• Task Type Recognition: Automatically distinguishes four types of requests—script writing, modeling guidance, topology/model review, and model optimization/repair—each following a different execution path.
• Version Compatibility Check: Before generating any script, confirms the user's Blender version (bpy.app.version) to avoid deprecated APIs, providing compatible approaches for 4.x/3.x.
• Headless Script Validation: Generated scripts are verified by running blender --background --python script.py in the user's environment. Errors are fixed on the spot; only verified scripts are delivered.
• Interrupted Resumption: Automatically detects unfinished projects in {CWD}/blender-modeling/ (those with a status.json marked incomplete) and resumes from the breakpoint.
• Dual Output: Each task provides both a copyable script and step-by-step manual instructions, letting the user choose either.
• Non-destructive Priority: By default, provides a modifier stack solution. Only executes bpy.ops.object.convert when the user explicitly requests "apply and collapse".

Core Workflow

Before entering each phase, read the corresponding flow document for detailed execution instructions.

Phase 0: Initialization

Detect task type (script writing / guidance / review / optimization), confirm Blender version and runtime environment, and detect unfinished projects (interrupted resumption). → See phase0-initialization.md

Phase 1: Requirements Gathering

Collect modeling requirements through progressive Q&A, determining deliverable forms:

• Core Positioning (mandatory, Q1-Q4): Object type and purpose, style (realistic/cartoon/hard-surface/low-poly game asset), target polygon budget, presence of reference images/reference objects → See phase1-requirements.md
• Deep Specifications (Q5-Q8): Need for subdivision/animation deformation, symmetry requirements, UV and material needs, script execution method (headless .blend generation or output to current scene) → See phase1-requirements.md

Phase 2: Modeling Scheme Planning

Select modeling approach based on requirements and output the plan:

• Route Selection: Box modeling / Sculpting + Retopology / Procedural (modifiers + curves) / bpy script parametric generation. Choose one or combine based on object shape and precision requirements.
• Topology Planning: Specify main edge flow, pole positions, subdivision levels, and symmetry axes.
• Modifier Stack Design: Provide modifier order (e.g., Mirror → Bevel → Subdivision) and key parameters.
• Plan Confirmation: Present a summary to the user; proceed to execution after user confirmation → See phase2-planning.md

Phase 3: Execution (No User Confirmation Required)

Execute modeling according to the plan: generate a bpy script (with Chinese annotations, parameters defined at the top) and run it headlessly in the user's environment for validation; or provide step-by-step instructions (with hotkeys). After execution, output the .blend file path. → See phase3-execution.md

Phase 4: Automatic Validation and Repair (No User Confirmation Required)

No user intervention needed: run topology_check script to inspect N-gons, poles, non-manifold geometry, and polygon count; check for API deprecation warnings or execution errors in the script; fix issues on the spot (up to 3 rounds). → See phase4-validation.md

Phase 4.5: Optional Enhancement Phase

After validation, use the request_user_input tool to let the user choose whether to run the optional enhancement phase:

[A] Retopology Optimization → Execute Phase 5 (quad-based retopology for sculpted models, pole cleanup) [B] Decimation Optimization → Execute Phase 6 (low-poly game assets, Decimate/retopology reduction, preserve silhouette) [C] UV Unwrapping and Texture Preparation → Execute Phase 7 (UV layout, seam planning, export to material software) [D] No, end directly

→ Based on user selection, proceed to phase5-retopology.md, phase6-decimation.md, and/or phase7-uv-prep.md

Shared Infrastructure

Preferences system, project status system, bpy scripting conventions, Blender environment detection, and other cross-phase shared mechanisms. → See shared-infrastructure.md