@deepblend/dsh-blender-contracts 0.2.15 → 0.2.16

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,7 @@
       "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."
     },
     "materials": {
       "type": "array",
@@ -677,15 +677,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": [

package/package.json

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