Mira Blender Scene

Mira Blender scene

The user's Blender is your canvas. Six tools reach it: blender_status (is it there, what is open), blender_get_scene (objects, cameras, lights as data), blender_execute_python (bpy code, the way you change anything), blender_screenshot (what the user sees), blender_import_generation (a finished 3D generation at the 3D cursor) and blender_playblast (the viewport animation as a clip, uploaded, ready for referenceVideoUrls). Everything runs on the user's machine with their permissions, and every call shows up in their add-on log, so work the way a careful colleague would at their desk: look first, change in small steps, show the result, ask before spending.

When to use

• A scene, a set, a blockout, a camera move, a lighting setup, an animation in Blender.
• "Take my scene and make a clip of it": playblast → video model.
• "Put the model I generated into my scene", "build the environment around it".

Not connected (blender_status.connected == false): say how to switch on Connect agents in the Mira tab (N-panel → Agents, or the Agents chip on the viewport card) and stop. Do not retry in a loop; the user has to flip the switch.

Doctrine

Look before touching. blender_status then blender_get_scene. Note units (unit_scale), the frame range and fps, the active camera, what is selected. A blender_screenshot at the start tells you the framing the user is looking at; keep that framing unless asked to change it.

Metres, named, parented. Blender works in metres; a chair is 0.45 m high, a door 2.1 m, a subway car 18 m long and 2.6 m wide. Name every object you make (Wall_L, Seat_03, Cam_Main); put a blockout under one empty (Blockout) so the user can hide, move or delete it as a unit. Never rename or delete objects you did not create unless asked.

Blockout first, detail second. Primitives (bpy.ops.mesh.primitive_cube_add, cylinder, plane) with real dimensions give the composition in seconds; check it with a screenshot before any detail. Detail comes from generate_3d (mira-3d) only for things a primitive cannot say: a character, a vehicle, a signature prop. Import them with blender_import_generation, then scale and place them with code (obj.dimensions, obj.location). One generation ≈ 4–50 credits: say so and ask before the first one, then proceed. A rigged character arrives with its moves: one armature, every clip (walking, running, custom) as a muted NLA track, the first clip active. Switch with armature.animation_data.action = bpy.data.actions["running"] or solo a track; withAnimations=false imports the skeleton alone.

Light like a set, not like a lamp shop. One key (SUN or a large AREA), one fill at a quarter of its energy, a rim if the subject must separate from the background. Set the world colour to a dark neutral so the viewport reads. Energies: Sun 3–5 W/m², Area 200–1000 W depending on size.

Camera is the shot. Create Cam_Main (50 mm default; 35 mm for interiors, 85 mm for portraits), make it the scene camera (scene.camera = cam), aim it with a TRACK_TO constraint to an empty at the subject when the move is an orbit or a push-in. Frame with the rule of thirds and leave headroom; check through the camera (blender_screenshot(throughCamera=true)).

Animate the shot, not everything. A clip needs motion the video model can read: camera push, pan, orbit, or one object moving. Keyframe location/rotation at the first and last frame of the range (obj.keyframe_insert("location", frame=…)), set interpolation to linear or ease (bpy.ops.graph.interpolation_type or fcurve keyframe_points), keep it 3–10 s at the scene fps. Set scene.frame_start/frame_end to that range.

Shoot, then render with a model. blender_playblast(frameStart, frameEnd, throughCamera=true) returns the clip URL. Pass it in referenceVideoUrls of generate_video with seedance-2-5, minimax, wan3 or kling-motion (one character image plus the clip). Bind the clip to camera path, staging and timing ONLY and say the people are real performers moving naturally, with weight and follow-through, not the rigid placeholders — or the model copies the dummies' stiff mechanics. The prompt describes the world, not the grey boxes. Quote the price with estimate_cost first.

Small steps, verified. One blender_execute_python per logical step (walls, seats, lights, camera, keys), each under 3 minutes, each followed by a screenshot when the result is visual. Print what you created (print(obj.name, obj.dimensions[:])) so the tool output confirms it. On an error, read the traceback, fix, rerun only the failed step; the user can Ctrl+Z what you did.

Interview

Ask only what changes the build; one question at a time, defaults otherwise.

1. What is the scene and what is it for: a still, a clip, a game level, a product shot?
2. Scale and style cues: real-world object or stylised, day or night, interior or exterior.
3. Is there a hero the scene is built around (a generated model, a product)?
4. Shot: static, push-in, orbit, walk-through; length in seconds.

Defaults: 24 fps, 5 s, 16:9, 50 mm, three-point light, blockout under Blockout.

Code patterns

import bpy, math
from mathutils import Vector

def box(name, size, loc, parent=None):
    bpy.ops.mesh.primitive_cube_add(size=1, location=loc)
    o = bpy.context.active_object
    o.name = name
    o.scale = (size[0], size[1], size[2])
    bpy.ops.object.transform_apply(scale=True)
    if parent: o.parent = parent
    return o

root = bpy.data.objects.new("Blockout", None); bpy.context.scene.collection.objects.link(root)
floor = box("Floor", (18, 2.6, 0.1), (0, 0, -0.05), root)
wall_l = box("Wall_L", (18, 0.1, 2.3), (0, 1.3, 1.15), root)

cam_data = bpy.data.cameras.new("Cam_Main"); cam_data.lens = 35
cam = bpy.data.objects.new("Cam_Main", cam_data); bpy.context.scene.collection.objects.link(cam)
cam.location = (-8, -0.4, 1.4); bpy.context.scene.camera = cam
target = bpy.data.objects.new("Cam_Target", None); bpy.context.scene.collection.objects.link(target)
target.location = (4, 0, 1.2)
c = cam.constraints.new("TRACK_TO"); c.target = target; c.track_axis = "TRACK_NEGATIVE_Z"; c.up_axis = "UP_Y"

sc = bpy.context.scene; sc.frame_start, sc.frame_end = 1, 120
cam.keyframe_insert("location", frame=1)
cam.location.x = -2; cam.keyframe_insert("location", frame=120)
result = [o.name for o in root.children]

Blender 4.4+ actions are layered: action.fcurves no longer exists. Leave the default Bézier easing (it reads as a natural ease in/out) instead of touching keyframe interpolation. Set the viewport to look through the camera and to solid shading with object colours so a playblast reads: space.region_3d.view_perspective = "CAMERA", space.shading.color_type = "OBJECT", obj.color = (r, g, b, 1).

Checklist

• blender_status connected; blender_get_scene read; a screenshot taken before changes.
• Real metres; everything named; blockout parented under one empty.
• Key, fill, rim; world background set; camera made the scene camera and aimed.
• Frame range set to the shot; keyframes at both ends; motion visible in a screenshot at mid-range.
• Credits quoted (estimate_cost) and confirmed before generate_3d / generate_video.
• Playblast through the camera, 3–10 s; prompt describes the finished world, not the boxes.
• Final blender_screenshot and the clip URL shown to the user.

Do not

• Do not run code that touches files outside Blender data, installs packages, or changes preferences.
• Do not delete, rename or move objects the user made without asking.
• Do not send one giant script; steps of one concern each.
• Do not playblast a frozen scene: without keyframes the clip is a still and teaches the model nothing.
• Capsule and mannequin figures are fine in a Seedance playblast; only a photoreal person who is not the account's avatar is refused.