@deepblend/dsh-blender-contracts 0.2.15 → 0.2.17

package/lib/scene-spec.js

@@ -96,6 +96,8 @@ export const ANIMATION_PROPERTIES_BY_KIND = Object.freeze({
 export function collectionNameForKind(kind) {
   if (kind === 'camera') return 'cameras'
   if (kind === 'material') return 'materials'
+  // A BONE TRACK RESOLVES AGAINST THE ARMATURES, because that is the collection its id belongs to.
+  if (kind === 'bone') return 'armatures'
   return 'entities'
 }
 
@@ -360,6 +362,25 @@ export function validateSceneSpec(spec) {
     // is what every track written before kinds existed meant.
     const kind = track.targetKind ?? 'entity'
     requiresId(collectionNameForKind(kind), track.targetEntityId, `${at}.targetEntityId`, kind)
+    // AND THE BONE INSIDE IT. MEASURED: this is the same shape as `armatureId` last round — the schema
+    // can say `boneName` is a string, and only a cross-reference can say the armature HAS that bone.
+    // A track pointing at a bone nobody declares animates nothing while the file says the rig moves.
+    if (kind === 'bone') {
+      if (typeof track.boneName !== 'string' || track.boneName.length === 0) {
+        errors.push({
+          severity: 'error', code: 'SCENE_REFERENCE_MISSING', path: `${at}.boneName`,
+          message: 'a bone track must name the bone it drives',
+        })
+      } else {
+        const armature = (document.armatures ?? []).find(entry => entry?.id === track.targetEntityId)
+        if (armature !== undefined && !(armature.bones ?? []).some(bone => bone?.name === track.boneName)) {
+          errors.push({
+            severity: 'error', code: 'SCENE_REFERENCE_MISSING', path: `${at}.boneName`,
+            message: `bone "${track.boneName}" does not exist in armature "${track.targetEntityId}"`,
+          })
+        }
+      }
+    }
 
     // A property that does not belong to the target's kind is not a typo the
     // compiler can shrug off: `emissionStrength` on an entity, or `location.x` on a

package/lib/schemas/scene-spec.schema.json

@@ -31,7 +31,23 @@
       "items": {
         "$ref": "#/$defs/armature"
       },
-      "description": "Armatures this scene declares (SPEC \u00a720 M6, character animation). Each is one skeleton, created as its own object and named `<prefix><id>` like every other product object. WHAT THIS DOES NOT DO YET: animate a bone. Entities ARE skinned to an armature now (`entity.armatureId`, with Blender's automatic weights), so a rig drives its mesh \u2014 but nothing moves the rig until animation tracks can target bones, which is the next slice."
+      "description": "Armatures this scene declares (SPEC \u00a720 M6, character animation). Each is one skeleton, created as its own object and named `<prefix><id>` like every other product object. Entities are skinned to an armature (`entity.armatureId`, with Blender's automatic weights) and animation tracks can drive a bone of it (`targetKind: \"bone\"` with `boneName`), so a rig both moves and moves its mesh."
+    },
+    "simulation": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "gravity": {
+          "type": "number",
+          "description": "Downward acceleration in m/s\u00b2. Blender's own default (-9.81) applies when absent."
+        },
+        "bake": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether the compile bakes the simulation into the checkpoint. Baking is what makes a render show the physics rather than the initial pose, and it is not instant \u2014 so a build that wants the SETUP without paying for the bake can say so."
+        }
+      },
+      "description": "Scene-level physics settings. The bodies themselves are per-entity (`entity.rigidBody`), because which things move is a property of those things."
     },
     "materials": {
       "type": "array",
@@ -477,6 +493,10 @@
           "type": "string",
           "description": "The armature this entity is skinned to, named by `armatures[].id`. The compiler binds the mesh with Blender's own automatic weights, so the entity follows the bones with no weight table to write by hand. A name the scene does not declare is refused rather than ignored, because an entity that is silently unskinned renders as a static object while the file says it is rigged."
         },
+        "rigidBody": {
+          "$ref": "#/$defs/rigidBody",
+          "description": "This entity takes part in physics (SPEC \u00a720 M6, complex simulation). WHAT THIS SLICE DOES: rigid bodies \u2014 active ones fall and collide, passive ones are what they collide with, and the compile BAKES the result into the checkpoint so a render shows it. WHAT IT DOES NOT DO YET: cloth, soft bodies and fluids, which are the next slices."
+        },
         "generator": {
           "$ref": "#/$defs/generator"
         },
@@ -677,15 +697,21 @@
           "enum": [
             "entity",
             "camera",
-            "material"
+            "material",
+            "bone"
           ],
           "default": "entity",
-          "description": "What `targetEntityId` names: an entity (default), a camera, or a material. Only entity tracks existed before, which is why \"the camera orbits the product\" and \"the dial lights up\" both had to be faked with entity transforms."
+          "description": "What `targetEntityId` names: an entity (default), a camera, a material, or AN ARMATURE whose bone this track drives (with `boneName`). Ids are unique per collection, so the kind is the only thing that says whether \"watch-dial\" means the mesh or the material \u2014 and `bone` is what made a rig able to move rather than merely exist."
         },
         "targetEntityId": {
           "type": "string",
           "description": "The id of the target named by `targetKind`. The field name says Entity because every track written before target kinds existed used it and revisions are immutable; renaming it would make r0001-r0023 unreadable. Resolution is against the collection `targetKind` names, which matters because ids are unique per collection, not globally."
         },
+        "boneName": {
+          "type": "string",
+          "maxLength": 64,
+          "description": "Required when targetKind is `bone`: the name of the bone inside the named armature. A name the armature does not have is refused \u2014 a track that silently animates nothing is a scene that claims to move and does not."
+        },
         "property": {
           "type": "string",
           "enum": [
@@ -857,6 +883,33 @@
           "$ref": "#/$defs/transform"
         }
       }
+    },
+    "rigidBody": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind"
+      ],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": [
+            "active",
+            "passive"
+          ],
+          "description": "`active` means physics moves it; `passive` means it moves nothing and everything collides with it \u2014 a floor is passive, which is why the two are one field rather than a boolean: a body that is not simulated and a body that is simulated are not the only two things a body can be."
+        },
+        "mass": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "description": "Kilograms, for an active body. Blender's own default applies when it is absent, and the default is stated rather than duplicated: a second copy of it here is the one that would go stale."
+        },
+        "friction": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Blender's own default applies when absent."
+        }
+      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepblend/dsh-blender-contracts",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "type": "module",
   "description": "DeepBlend Studio Service Definition, protocol contracts, and stable error codes.",
   "main": "lib/index.js",