Valid modes: 'WIREFRAME', 'SOLID', 'MATERIAL', 'RENDERED'


**Sculpting operators require Blender context** - use the Blender MCP's `execute_blender_code` tool, which has full context. For high-resolution mesh deformation, direct vertex manipulation is more reliable than sculpt brush operators.

---

## QUICK START

### Create Base Terrain Mesh

```python
import bpy

# Remove existing terrain
for obj in [o for o in bpy.data.objects if o.name.startswith('Terrain')]:
    bpy.data.objects.remove(obj, do_unlink=True)

# Create 100x100 grid terrain
size = 100
subdivisions = 100
vertices = []
faces = []

for y in range(subdivisions + 1):
    for x in range(subdivisions + 1):
        x_pos = (x / subdivisions - 0.5) * size
        y_pos = (y / subdivisions - 0.5) * size
        vertices.append((x_pos, y_pos, 0.0))

for y in range(subdivisions):
    for x in range(subdivisions):
        i = y * (subdivisions + 1) + x
        faces.append([i, i + 1, i + subdivisions + 2, i + subdivisions + 1])

mesh = bpy.data.meshes.new('TerrainMesh')
mesh.from_pydata(vertices, [], faces)
mesh.update()

obj = bpy.data.objects.new('Terrain', mesh)
bpy.context.collection.objects.link(obj)

for poly in mesh.polygons:
    poly.use_smooth = True

print(f'Terrain created: {len(vertices)} vertices, {len(faces)} faces')

Add Multires Modifier

import bpy

terrain = bpy.data.objects.get('Terrain')
if terrain:
    multires = terrain.modifiers.new('Multires', 'MULTIRES')
    print(f'Multires added to {terrain.name}')
    # To subdivide: use Blender UI or bpy.ops.object.multires_subdivide
    # after setting active object and entering Object mode

STANDARD WORKFLOWS

Workflow 1: Direct Vertex Terrain Sculpting

Step 1: Create Height Variation

import bpy
import math

terrain = bpy.data.objects.get('Terrain')
mesh = terrain.data

zones = {
    'peak':   {'center': (25, 25),   'radius': 15, 'height': 30},
    'valley': {'center': (-20, -20), 'radius': 10, 'height': -15},
    'ridge':  {'center': (0, 30),    'radius': 20, 'height': 20}
}

for v in mesh.vertices:
    x, y = v.co.x, v.co.y
    height = 0

    for zone in zones.values():
        cx, cy = zone['center']
        radius = zone['radius']
        dist = math.sqrt((x - cx)**2 + (y - cy)**2)
        if dist < radius:
            falloff = 1.0 - (dist / radius)
            height += zone['height'] * falloff

    v.co.z = height

mesh.update()
print(f'Height variation applied to {len(mesh.vertices)} vertices')

Step 2: Apply Erosion Patterns

import bpy
import math

terrain = bpy.data.objects.get('Terrain')
mesh = terrain.data

for v in mesh.vertices:
    x, y = v.co.x, v.co.y
    noise = 0
    noise += math.sin(x * 0.1) * 2.0
    noise += math.sin(y * 0.15) * 1.5
    noise += math.sin(x * 0.3 + y * 0.3) * 0.8
    v.co.z += noise

mesh.update()
print('Erosion patterns applied')

Step 3: Smooth Terrain

import bpy

terrain = bpy.data.objects.get('Terrain')
mesh = terrain.data

iterations = 3
for _ in range(iterations):
    new_z = []
    for v in mesh.vertices:
        connected_heights = [v.co.z]
        for edge in mesh.edges:
            if v.index in edge.vertices:
                other_idx = edge.vertices[0] if edge.vertices[1] == v.index else edge.vertices[1]
                connected_heights.append(mesh.vertices[other_idx].co.z)
        new_z.append(sum(connected_heights) / len(connected_heights))

    for v, z in zip(mesh.vertices, new_z):
        v.co.z = z

mesh.update()
print(f'Smoothing applied ({iterations} iterations)')

Workflow 2: Vertex Groups for Material Zones

import bpy

terrain = bpy.data.objects.get('Terrain')
mesh = terrain.data

heights = [v.co.z for v in mesh.vertices]
min_h = min(heights)
max_h = max(heights)
h_range = max_h - min_h

groups = {
    'Valley': terrain.vertex_groups.new(name='Valley'),
    'Slope':  terrain.vertex_groups.new(name='Slope'),
    'Peak':   terrain.vertex_groups.new(name='Peak')
}

for v in mesh.vertices:
    norm = (v.co.z - min_h) / h_range if h_range > 0 else 0
    if norm < 0.3:
        groups['Valley'].add([v.index], 1.0, 'ADD')
    elif norm < 0.7:
        groups['Slope'].add([v.index], 1.0, 'ADD')
    else:
        groups['Peak'].add([v.index], 1.0, 'ADD')

print(f'Vertex groups created. Height range: {min_h:.2f} to {max_h:.2f}')

Workflow 3: Organic Model Base Creation

Pattern: Create low-res base -> Add Multires -> Set up symmetry -> Sculpt details

import bpy
import math

segments = 8
rings = 8
vertices = []
faces = []

for ring in range(rings + 1):
    theta = math.pi * ring / rings
    for seg in range(segments):
        phi = 2 * math.pi * seg / segments
        x = math.sin(theta) * math.cos(phi)
        y = math.sin(theta) * math.sin(phi)
        z = math.cos(theta)
        vertices.append((x, y, z))

for ring in range(rings):
    for seg in range(segments):
        i = ring * segments + seg
        j = i + segments
        i_next = ring * segments + (seg + 1) % segments
        j_next = i_next + segments
        faces.append([i, i_next, j_next, j])

mesh = bpy.data.meshes.new('HeadBase')
mesh.from_pydata(vertices, [], faces)
mesh.update()

obj = bpy.data.objects.new('HeadBase', mesh)
bpy.context.collection.objects.link(obj)
multires = obj.modifiers.new('Multires', 'MULTIRES')

print(f'Organic base created: {len(vertices)} vertices')

TROUBLESHOOTING

Sculpting Operators Fail

For fine-grained sculpt brushes, use Blender's Sculpt Mode UI. For scripted terrain deformation, direct vertex manipulation is both more reliable and more controllable:

import bpy

# Direct vertex modification - always works
mesh = bpy.data.objects['Terrain'].data
for v in mesh.vertices:
    v.co.z += some_height_function(v.co.x, v.co.y)
mesh.update()

Multires Subdivision

bpy.ops.object.multires_subdivide() requires an active object in Object mode. With MCP (full context), this works:

import bpy

terrain = bpy.data.objects.get('Terrain')
bpy.context.view_layer.objects.active = terrain
bpy.ops.object.multires_subdivide(modifier='Multires')

Alternatively, increase base mesh resolution (subdivisions = 200) instead of using Multires.

Viewport Shading Not Updating

import bpy

for area in bpy.context.screen.areas:
    if area.type == 'VIEW_3D':
        for space in area.spaces:
            if space.type == 'VIEW_3D':
                space.shading.type = 'MATERIAL'  # NOT 'MATERIAL_PREVIEW' (4.5+)

VALIDATION CHECKLIST

Base mesh created (verify vertex count)
Smooth shading applied (poly.use_smooth = True)
Height variations applied and visually correct
Vertex groups created (if using material zones)
No mesh errors (check for manifold issues if exporting)
Viewport shading uses 'MATERIAL' not 'MATERIAL_PREVIEW'

VERSION HISTORY

v2.0.0 (2026-06-10) - MCP migration

Removed HTTP Bridge section and curl health-check steps
Removed requests.post() wrappers
Added import bpy to all code blocks
Updated target: Blender 5.1+
Added note that bpy.ops sculpt operators work with MCP full context
Removed absolute paths to blender-ai-compatibility

v1.1.0 (2025-10-24) - Article III compliance v1.0.0 (2025-10-24) - Initial release

Status: Production Ready Maintainer: VFX Pipeline Team Dependencies: Blender 5.1+

blender-sculpting

Blender Sculpting Skill

API Notes (5.1+)