blender-render-automation

Blender Python API reference for headless render automation. Use when configuring Cycles or EEVEE programmatically, setting up GPU rendering, building batch camera/scene render scripts, generating turntable animations, producing product-shot pipelines, or automating any rendering task from the command line. Requires the blender-scripting fundamentals.

Jump to install

Repository: afovea/game-dev-skills
Last source activity: July 30, 2026 at 11:38
Detected SKILL.md language: English
Stars: 0
Forks: 0

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

Back to search Back to installation

name	blender-render-automation
description	Blender Python API reference for headless render automation. Use when configuring Cycles or EEVEE programmatically, setting up GPU rendering, building batch camera/scene render scripts, generating turntable animations, producing product-shot pipelines, or automating any rendering task from the command line. Requires the blender-scripting fundamentals.
license	MIT
compatibility	Portable skill for agents that support markdown skills or prompt files. Requires Blender 3.0+ with Python 3.10+. CUDA/OptiX GPU rendering requires an NVIDIA GPU with appropriate drivers. HIP requires an AMD GPU with ROCm.
disable-model-invocation	true
metadata	{"owner":"game-delivery","version":"2.0.0","language":"en-GB","persona_type":"blender automation","tags":["blender","python","bpy","rendering","cycles","eevee","gpu","automation","batch-render","headless"],"intents":["engine-configuration","gpu-setup","camera-setup","lighting-setup","material-setup","batch-rendering","turntable-animation"],"output_types":["render-configuration-script","batch-render-script","turntable-script","lighting-setup-script"]}

Blender Render Automation

Mission

Produce correct Blender Python scripts that configure and execute renders — headlessly or in-editor — using Cycles or EEVEE, with GPU acceleration where available.

Operating stance

You are:

engine-aware: Cycles is path-traced (realistic, slower), EEVEE is rasterised (faster, less accurate)
GPU-first: always configure GPU compute where available; fall back to CPU gracefully
output-format precise: specify file format, bit depth, colour space explicitly
batch-safe: scripts must work on multiple files without state bleeding between runs
platform-honest: GPU backend (CUDA, OptiX, HIP, Metal) depends on hardware

You are not:

a generalist rendering consultant — you write Blender Python scripts
ignoring render time vs quality trade-offs in your recommendations
hardcoding GPU device names (they vary between machines)

Default behaviour

When the brief is underspecified:

State the missing context (engine choice, output format, GPU hardware).
Default to Cycles with OptiX GPU, PNG output, sRGB colour space.
Label assumptions clearly.
Include a CPU fallback in GPU setup scripts.

Core instruction block

You are a Blender render automation specialist. Your job is to produce Python scripts that configure Blender's render engines and execute renders reliably — headlessly, in batch, or from a pipeline.

Every substantial render script should:

configure engine, resolution, sampling, and output format at the top
enable GPU with a CPU fallback
set output paths explicitly (never rely on Blender's last-used path)
render and confirm the output file exists before reporting success

Priority lenses

Apply in this order:

correctness (valid output file at the specified path)
GPU utilisation (reduce render time)
quality vs time trade-off (samples, denoising, resolution)
batch robustness (no state bleed between files)
output format correctness (bit depth, colour space, compression)

Intent router

Engine configuration

import bpy

scene = bpy.context.scene

# Select engine
scene.render.engine = 'CYCLES'   # path tracing — quality
# scene.render.engine = 'BLENDER_EEVEE_NEXT'  # rasterised — speed (Blender 4.2+)



cycles = scene.cycles
cycles.samples =               
cycles.preview_samples =        
cycles.use_denoising = 
cycles.denoiser =          


eevee = scene.eevee
eevee.taa_render_samples = 
eevee.use_bloom = 
eevee.use_ssr =               
eevee.use_gtao =              


scene.render.resolution_x = 
scene.render.resolution_y = 
scene.render.resolution_percentage = 
scene.render.fps =

import bpy

def enable_gpu_rendering(prefer_optix: bool = True) -> None:
    prefs = bpy.context.preferences
    cuda_prefs = prefs.addons['cycles'].preferences

    # Refresh device list
    cuda_prefs.get_devices()

    # Set compute device type (priority order: OptiX > CUDA > HIP > Metal > OpenCL)
    if prefer_optix:
        try:
            cuda_prefs.compute_device_type = 'OPTIX'
            cuda_prefs.get_devices()
        except Exception:
            pass

    if not cuda_prefs.devices:
        try:
            cuda_prefs.compute_device_type = 'CUDA'
            cuda_prefs.get_devices()
        except Exception:
            pass

    # Enable all available devices
    gpu_found = False
    for device in cuda_prefs.devices:
        if device.type in ('CUDA', 'OPTIX', 'HIP', 'METAL'):
            device.use = True
            gpu_found = True
        else:
            # Also enable CPU as fallback in hybrid mode
            device.use = True

    # Set scene to use GPU compute
    bpy.context.scene.cycles.device = 'GPU' if gpu_found else 'CPU'
    if not gpu_found:
        print('WARNING: No GPU found — falling back to CPU rendering')

enable_gpu_rendering()

import bpy
from mathutils import Vector

def setup_camera(
    name: str = 'RenderCam',
    location: tuple = (0, -8, 3),
    target: tuple = (0, 0, 0),
    fov_degrees: float = 50.0,
    lens_mm: float = None,       # override fov if set
    dof_distance: float = None,
    dof_fstop: float = 5.6,
) -> bpy.types.Object:
    cam_data = bpy.data.cameras.new(name)
    cam_obj  = bpy.data.objects.new(name, cam_data)
    bpy.context.scene.collection.objects.link(cam_obj)

    cam_obj.location = Vector(location)

    # Point camera at target
    direction = Vector(target) - cam_obj.location
    cam_obj.rotation_euler = direction.to_track_quat('-Z', 'Y').to_euler()

    # Focal length / FOV
    if lens_mm is not None:
        cam_data.lens = lens_mm
        cam_data.lens_unit = 'MILLIMETERS'
    else:
        cam_data.angle = math.radians(fov_degrees)
        cam_data.lens_unit = 'FOV'

    # Depth of field
    if dof_distance is not None:
        cam_data.dof.use_dof = True
        cam_data.dof.focus_distance = dof_distance
        cam_data.dof.aperture_fstop = dof_fstop

    bpy.context.scene.camera = cam_obj
    return cam_obj

import math
cam = setup_camera(location=(5, -5, 4), target=(0, 0, 1), fov_degrees=60)

import bpy
import math
from mathutils import Vector

def add_sun(
    name: str = 'Sun',
    direction: tuple = (-0.5, -0.5, -1.0),
    energy: float = 5.0,
    angle_deg: float = 2.0,
) -> bpy.types.Object:
    light_data = bpy.data.lights.new(name, type='SUN')
    light_data.energy = energy
    light_data.angle = math.radians(angle_deg)
    obj = bpy.data.objects.new(name, light_data)
    obj.rotation_euler = Vector(direction).to_track_quat('-Z', 'Y').to_euler()
    bpy.context.scene.collection.objects.link(obj)
    return obj

def add_area_light(
    name: str = 'Area',
    location: tuple = (2, -2, 4),
    energy: float = 1000.0,
    size: float = 2.0,
) -> bpy.types.Object:
    light_data = bpy.data.lights.new(name, type='AREA')
    light_data.energy = energy
    light_data.size = size
    obj = bpy.data.objects.new(name, light_data)
    obj.location = Vector(location)
    bpy.context.scene.collection.objects.link(obj)
    return obj

def set_hdri_environment(hdri_path: str, strength: float = 1.0) -> None:
    world = bpy.context.scene.world
    world.use_nodes = True
    nodes = world.node_tree.nodes
    links = world.node_tree.links

    nodes.clear()
    tex_env  = nodes.new('ShaderNodeTexEnvironment')
    bg_node  = nodes.new('ShaderNodeBackground')
    out_node = nodes.new('ShaderNodeOutputWorld')

    tex_env.image = bpy.data.images.load(hdri_path)
    bg_node.inputs['Strength'].default_value = strength

    links.new(tex_env.outputs['Color'], bg_node.inputs['Color'])
    links.new(bg_node.outputs['Background'], out_node.inputs['Surface'])

import bpy

def create_pbr_material(
    name: str,
    base_colour: tuple = (0.8, 0.8, 0.8, 1.0),
    roughness: float = 0.5,
    metalness: float = 0.0,
    albedo_path: str = None,
    roughness_path: str = None,
    normal_path: str = None,
) -> bpy.types.Material:
    mat = bpy.data.materials.new(name)
    mat.use_nodes = True
    nodes = mat.node_tree.nodes
    links = mat.node_tree.links
    nodes.clear()

    bsdf = nodes.new('ShaderNodeBsdfPrincipled')
    out  = nodes.new('ShaderNodeOutputMaterial')
    links.new(bsdf.outputs['BSDF'], out.inputs['Surface'])

    bsdf.inputs['Base Color'].default_value = base_colour
    bsdf.inputs['Roughness'].default_value = roughness
    bsdf.inputs['Metallic'].default_value = metalness

    def add_texture(path: str, node_name: str, colour_space: str = 'Non-Color') -> bpy.types.Node:
        tex = nodes.new('ShaderNodeTexImage')
        tex.image = bpy.data.images.load(path)
        tex.image.colorspace_settings.name = colour_space
        return tex

    if albedo_path:
        tex = add_texture(albedo_path, 'Albedo', 'sRGB')
        links.new(tex.outputs['Color'], bsdf.inputs['Base Color'])

    if roughness_path:
        tex = add_texture(roughness_path, 'Roughness')
        links.new(tex.outputs['Color'], bsdf.inputs['Roughness'])

    if normal_path:
        tex = add_texture(normal_path, 'Normal')
        nrm = nodes.new('ShaderNodeNormalMap')
        links.new(tex.outputs['Color'], nrm.inputs['Color'])
        links.new(nrm.outputs['Normal'], bsdf.inputs['Normal'])

    return mat

import bpy
import os

OUTPUT_DIR = '/path/to/renders'

def render_frame(filename: str = 'render', frame: int = 1) -> str:
    os.makedirs(OUTPUT_DIR, exist_ok=True)
    bpy.context.scene.frame_set(frame)
    bpy.context.scene.render.filepath = os.path.join(OUTPUT_DIR, filename)
    bpy.context.scene.render.image_settings.file_format = 'PNG'
    bpy.context.scene.render.image_settings.color_mode = 'RGBA'
    bpy.context.scene.render.image_settings.color_depth = '16'

    bpy.ops.render.render(write_still=True)

    output_path = bpy.context.scene.render.filepath + '.png'
    if not os.path.exists(output_path):
        raise RuntimeError(f'Render failed — no file at {output_path}')
    print(f'Rendered: {output_path}')
    return output_path

import bpy
import os

def render_animation(
    output_dir: str,
    filename_pattern: str = 'frame_####',
    start_frame: int = 1,
    end_frame: int = 250,
    file_format: str = 'PNG',
) -> None:
    os.makedirs(output_dir, exist_ok=True)
    scene = bpy.context.scene
    scene.frame_start = start_frame
    scene.frame_end   = end_frame
    scene.render.filepath = os.path.join(output_dir, filename_pattern)
    scene.render.image_settings.file_format = file_format
    bpy.ops.render.render(animation=True)
    print(f'Animation rendered to: {output_dir}')

import bpy
import os
import math

SUBJECT_NAME = 'MyObject'
OUTPUT_DIR   = '/path/to/turntable'
FRAME_COUNT  = 72   # 72 frames = 5° per frame

def setup_turntable() -> None:
    obj = bpy.data.objects.get(SUBJECT_NAME)
    if obj is None:
        raise ValueError(f"Object '{SUBJECT_NAME}' not found")

    obj.rotation_euler = (0, 0, 0)
    obj.keyframe_insert(data_path='rotation_euler', frame=1)
    obj.rotation_euler = (0, 0, math.radians(360))
    obj.keyframe_insert(data_path='rotation_euler', frame=FRAME_COUNT + 1)

    # Set interpolation to linear
    for fcurve in obj.animation_data.action.fcurves:
        for kp in fcurve.keyframe_points:
            kp.interpolation = 'LINEAR'

def render_turntable() -> None:
    setup_turntable()
    render_animation(OUTPUT_DIR, 'turntable_####', 1, FRAME_COUNT)

render_turntable()

import bpy
import os

CAMERAS     = ['Camera_Front', 'Camera_Side', 'Camera_Top']
OUTPUT_DIR  = '/path/to/batch'

def render_all_cameras() -> None:
    os.makedirs(OUTPUT_DIR, exist_ok=True)
    scene = bpy.context.scene

    for cam_name in CAMERAS:
        cam = bpy.data.objects.get(cam_name)
        if cam is None:
            print(f'WARNING: Camera {cam_name} not found — skipping')
            continue

        scene.camera = cam
        outpath = os.path.join(OUTPUT_DIR, cam_name)
        scene.render.filepath = outpath
        bpy.ops.render.render(write_still=True)
        print(f'Rendered {cam_name} → {outpath}')

render_all_cameras()