@deepblend/dsh-blender-provider-local 0.2.15 → 0.2.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepblend/dsh-blender-provider-local",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "type": "module",
   "description": "Local Blender Provider: the BlenderRuntime Service over ctx.subprocess (batch execution).",
   "main": "lib/index.js",
@@ -11,7 +11,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@deepblend/dsh-blender-contracts": "0.2.15"
+    "@deepblend/dsh-blender-contracts": "0.2.17"
   },
   "license": "MIT",
   "repository": {

package/python/bootstrap.py

@@ -233,6 +233,13 @@ def action_compile_scene(request, options):
         # WHICH ENTITIES ARE SKINNED, AND TO WHAT. The vertex groups are the evidence that weights
         # exist at all: an entity bound to an armature with no groups renders as a static object while
         # the file says it is rigged, and the reading is where that difference becomes visible.
+        # WHAT THE PHYSICS DID, per entity. Not the settings: a body that is configured and never
+        # enabled looks exactly like one that fell, and only a reading of where it ended up tells them
+        # apart.
+        "simulation": [
+            {"entityId": entity_id, **entry}
+            for entity_id, entry in sorted((report.get("simulation") or {}).items())
+        ],
         "skinned": [
             {
                 "entityId": entity_id,

package/python/deepblend_scene.py

@@ -1030,6 +1030,82 @@ def _apply_interpolation(action, data_path, axis, keyframes, track, guard):
         )
 
 
+def _insert_keyframes(target, bpy_attr, axis, keyframes):
+    """Insert one component's keyframes on a target that has `keyframe_insert`.
+
+    EXTRACTED RATHER THAN COPIED: an object and a pose bone are keyframed by the same three lines, and
+    a second copy is the one that would miss the next fix — the identity-first rule below is exactly the
+    kind of thing that gets learned once and applied in one place.
+    """
+    for keyframe in keyframes:
+        frame = int(keyframe["frame"])
+        value = float(keyframe["value"])
+        setattr(target, bpy_attr, _with_component(getattr(target, bpy_attr), axis, value))
+        target.keyframe_insert(data_path=bpy_attr, index=axis, frame=frame)
+
+
+def build_bone_animation(armature_obj, track, guard):
+    """Animate ONE pose bone of an armature.
+
+    WHY A BONE IS NOT AN OBJECT: the values live on the ARMATURE's pose, so the keyframes are inserted
+    through the pose bone while the action belongs to the armature. Everything else — the property
+    vocabulary, the two-keyframe minimum, the interpolation — is the same, which is why the insertion
+    itself is shared rather than re-implemented.
+
+    The bone is named by the track; a name the armature does not have is refused, because a track that
+    silently animates nothing is a scene that claims to move and does not.
+    """
+    bone_name = track.get("boneName")
+    if not isinstance(bone_name, str) or bone_name == "":
+        raise ActionError(
+            "SCENE_VALIDATION_FAILED",
+            'animation track "%s" targets a bone but names none' % (track.get("id"),),
+        )
+    pose_bone = armature_obj.pose.bones.get(bone_name)
+    if pose_bone is None:
+        raise ActionError(
+            "SCENE_VALIDATION_FAILED",
+            'animation track "%s" targets bone "%s", which armature "%s" does not have'
+            % (track.get("id"), bone_name, armature_obj.get("deepblend_id")),
+        )
+
+    property_name = track.get("property", "")
+    if "." not in property_name:
+        raise ActionError(
+            "SCENE_VALIDATION_FAILED",
+            'animation track "%s" names property "%s" without a component' % (track.get("id"), property_name),
+        )
+    attr, _, component = property_name.rpartition(".")
+    bpy_attr = TRACK_PROPERTY_ATTR.get(attr)
+    if bpy_attr is None or component not in ("x", "y", "z"):
+        raise ActionError(
+            "SCENE_VALIDATION_FAILED",
+            'animation track "%s" names unsupported property "%s"' % (track.get("id"), property_name),
+            {"supported": sorted("%s.%s" % (name, axis) for name in TRACK_PROPERTY_ATTR for axis in "xyz")},
+        )
+
+    keyframes = track.get("keyframes") or []
+    if len(keyframes) < 2:
+        raise ActionError(
+            "SCENE_VALIDATION_FAILED",
+            'animation track "%s" has %d keyframe(s); at least 2 are required to describe motion'
+            % (track.get("id"), len(keyframes)),
+        )
+
+    axis = "xyz".index(component)
+    pose_bone.rotation_mode = "XYZ"
+    _insert_keyframes(pose_bone, bpy_attr, axis, keyframes)
+
+    action = armature_obj.animation_data.action if armature_obj.animation_data is not None else None
+    if action is None:
+        raise ActionError(
+            "BLENDER_SCRIPT_ERROR",
+            'animation track "%s" inserted keyframes but produced no action' % (track.get("id"),),
+        )
+    _apply_interpolation(action, bpy_attr, axis, keyframes, track, guard)
+    return action
+
+
 def build_animation(obj, track, guard):
     """Key one animation track onto an object, returning the action name.
 
@@ -1072,11 +1148,7 @@ def build_animation(obj, track, guard):
     # values, or the first insert would capture a value from a different property.
     obj.rotation_mode = "XYZ"
 
-    for keyframe in keyframes:
-        frame = int(keyframe["frame"])
-        value = float(keyframe["value"])
-        setattr(obj, bpy_attr, _with_component(getattr(obj, bpy_attr), axis, value))
-        obj.keyframe_insert(data_path=bpy_attr, index=axis, frame=frame)
+    _insert_keyframes(obj, bpy_attr, axis, keyframes)
 
     action = obj.animation_data.action if obj.animation_data is not None else None
     if action is None:
@@ -1414,6 +1486,104 @@ def skin_entity(obj, armature_obj, armature_id, guard):
     return True
 
 
+def build_rigid_bodies(spec, entity_objects, guard):
+    """Give the entities their physics, and BAKE the result into the checkpoint.
+
+    WHY THE COMPILE BAKES: a rigid body that has not been baked is a SETTING, not a motion — Blender
+    evaluates it on the fly in the viewport and a batch render of an unbaked simulation renders the
+    initial pose. Baking here is what makes the checkpoint mean "this is what the simulation did", and
+    it is why `simulation.bake: false` exists for a build that only wants the setup.
+
+    Returns a reading of what the physics DID, not of what it was told: each active body's height at the
+    first and the last frame of the scene's range. MEASURED, and the lesson from the animation slice is
+    why this is not just "the setup exists": a body that is configured correctly and never enabled looks
+    exactly like one that fell, unless something reads where it ended up.
+    """
+    settings = spec.get("simulation") or {}
+    scene = bpy.context.scene
+    if "gravity" in settings:
+        scene.gravity[2] = -abs(float(settings["gravity"]))
+
+    # THE PHYSICS WORLD HAS TO EXIST BEFORE A BODY CAN BE ATTACHED TO IT. MEASURED: without this line
+    # `obj.rigid_body` is None and the assignment fails with an AttributeError — Blender's rigid-body
+    # settings live on a scene-level world, and a scene that has never had one has nowhere to put them.
+    if scene.rigidbody_world is None:
+        bpy.ops.rigidbody.world_add()
+    # AND THE WORLD NEEDS A COLLECTION, which a fresh one does not have. MEASURED, in three steps that
+    # each looked like it should work: without the world there is nowhere to put a body; with the world
+    # but no collection, `world.collection` is None; and only an object LINKED INTO that collection
+    # gets its `rigid_body` materialised. The Blender UI does all three when a user clicks "Rigid Body".
+    if scene.rigidbody_world.collection is None:
+        collection = bpy.data.collections.new("DeepBlendRigidBodies")
+        scene.collection.children.link(collection)
+        scene.rigidbody_world.collection = collection
+
+    bodies = {}
+    for entity in spec.get("entities") or []:
+        entry = entity.get("rigidBody")
+        if entry is None:
+            continue
+        obj = entity_objects.get(entity["id"])
+        if obj is None:
+            raise ActionError(
+                "SCENE_SPEC_INVALID",
+                'entity "%s" declares a rigid body but has no object to attach it to' % (entity["id"],),
+            )
+        # JOINING THE PHYSICS COLLECTION IS WHAT CREATES `obj.rigid_body`. MEASURED, twice: adding the
+        # world is not enough — Blender materialises the rigid-body settings when the object is linked
+        # into the world's own collection, so an object that has "a rigid body" the obvious way is an
+        # object with `None`.
+        if obj.name not in scene.rigidbody_world.collection.objects:
+            scene.rigidbody_world.collection.objects.link(obj)
+
+        obj.rigid_body.type = "ACTIVE" if entry["kind"] == "active" else "PASSIVE"
+        if entry.get("mass") is not None:
+            obj.rigid_body.mass = float(entry["mass"])
+        if entry.get("friction") is not None:
+            obj.rigid_body.friction = float(entry["friction"])
+        bodies[entity["id"]] = entry
+
+    if not bodies:
+        return {}
+
+    # THE GROUND BODIES DO NOT MOVE, so they need the physics world to have something to collide against
+    # and Blender needs to be told the world exists at all.
+    scene.use_gravity = True
+
+    reading = {}
+    first_frame = int((spec.get("project") or {}).get("frameStart", 1))
+    last_frame = int((spec.get("project") or {}).get("frameEnd", first_frame))
+    if settings.get("bake", True):
+        scene.frame_set(first_frame)
+        # `bake_all` walks every cache in the scene, which is what a compile wants: the caller asked for
+        # a checkpoint that shows the simulation, not for one cache to be fresh.
+        try:
+            bpy.ops.ptcache.bake_all(bake=True)
+        except Exception as exc:
+            guard.warnings.append({
+                "code": "SIMULATION_BAKE_FAILED",
+                "message": "the simulation could not be baked: %s" % (error_text(exc),),
+            })
+
+    for entity_id in bodies:
+        obj = entity_objects[entity_id]
+        scene.frame_set(first_frame)
+        bpy.context.view_layer.update()
+        first = float((obj.matrix_world.translation)[2])
+        scene.frame_set(last_frame)
+        bpy.context.view_layer.update()
+        last = float((obj.matrix_world.translation)[2])
+        reading[entity_id] = {
+            "kind": bodies[entity_id]["kind"],
+            "firstFrameZ": round(first, 6),
+            "lastFrameZ": round(last, 6),
+            "droppedZ": round(first - last, 6),
+        }
+    scene.frame_set(first_frame)
+    bpy.context.view_layer.update()
+    return reading
+
+
 def build_scene(spec, options, guard):
     """Compile a SceneSpec into a live Blender scene.
 
@@ -1560,6 +1730,10 @@ def build_scene(spec, options, guard):
             target = cameras.get(target_id)
         elif kind == "material":
             target = materials.get(target_id)
+        elif kind == "bone":
+            # A BONE TRACK TARGETS THE ARMATURE, because the bones belong to it: the armature id is
+            # what resolves, and `boneName` picks the bone inside it.
+            target = armature_objects.get(target_id)
         else:
             target = entity_objects.get(target_id)
         if target is None:
@@ -1570,9 +1744,26 @@ def build_scene(spec, options, guard):
             )
         if kind == "material":
             action = build_material_animation(target, track, guard)
+        elif kind == "bone":
+            action = build_bone_animation(target, track, guard)
         else:
             action = build_animation(target, track, guard)
-        actions.append({"id": track.get("id"), "targetKind": kind, "targetEntityId": target_id, "action": action.name})
+        actions.append({
+            "id": track.get("id"),
+            "targetKind": kind,
+            "targetEntityId": target_id,
+            "action": action.name,
+            **({"boneName": track.get("boneName")} if kind == "bone" else {}),
+            # WHAT THE ACTION ACTUALLY DROVE, read off its own fcurves. MEASURED, and a surviving
+            # mutation is why: keying the ARMATURE OBJECT instead of the pose bone still moves the mesh
+            # — the mesh is parented to the armature, so the two frames differ either way — and the
+            # two-frame proof passed. The data paths are the difference: `pose.bones["chest"]…` is the
+            # bone, `rotation_euler` on the object is not.
+            "dataPaths": sorted({curve.data_path for curve in action_fcurves(action)}),
+        })
+
+    report_progress("build_simulation", 70)
+    simulation_reading = build_rigid_bodies(spec, entity_objects, guard)
 
     report_progress("configure_render", 85)
     render_config = configure_scene(scene, spec, profile, guard)
@@ -1618,6 +1809,7 @@ def build_scene(spec, options, guard):
         "profileName": profile_name,
         "entityObjectNames": {key: value.name for key, value in entity_objects.items()},
         "armatureNames": {key: value.name for key, value in armature_objects.items()},
+        "simulation": simulation_reading,
         "skinned": {
             key: {
                 "armatureId": entry["armatureId"],