@deepblend/dsh-blender-contracts 0.2.14 → 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'
 }
 
@@ -185,6 +187,10 @@ export function validateSceneSpec(spec) {
   // ---- uniqueness ---------------------------------------------------------
   const collections = [
     ['assets', document.assets ?? []],
+    // ARMATURES ARE A COLLECTION LIKE ANY OTHER: they have ids, they can collide, and other things
+    // reference them by id. Leaving them out of this list meant the cross-reference check had nothing to
+    // look in, so a skinned entity was reported as naming a rig that does not exist — its own rig.
+    ['armatures', document.armatures ?? []],
     ['materials', document.materials ?? []],
     ['entities', document.entities],
     ['lights', document.lights ?? []],
@@ -279,6 +285,11 @@ export function validateSceneSpec(spec) {
       })
     }
     requiresId('materials', entity.materialId, `${at}.materialId`, 'material')
+    // AND THE RIG IT IS SKINNED TO. MEASURED: this check was missing at first, and the contract suite
+    // caught it — the schema can say `armatureId` is a string, but only a cross-reference can say it
+    // names something the scene declares. An entity skinned to an armature nobody declares would render
+    // as a static object while the file says it is rigged, which is the failure this code exists for.
+    requiresId('armatures', entity.armatureId, `${at}.armatureId`, 'armature')
     if (entity.type !== 'empty' && entity.materialId === undefined) {
       notices.push({
         severity: 'notice', code: 'SCENE_ENTITY_MATERIAL_DEFAULTED', path: at,
@@ -351,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 SLICE DOES NOT DO YET: bind a mesh to a bone (skinning) and animate a bone \u2014 those are the next two slices, and a rig that exists but drives nothing is honest about being exactly that."
+      "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",
@@ -473,6 +473,10 @@
           "type": "string",
           "description": "Required when type is asset-instance."
         },
+        "armatureId": {
+          "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."
+        },
         "generator": {
           "$ref": "#/$defs/generator"
         },
@@ -673,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.14",
+  "version": "0.2.16",
   "type": "module",
   "description": "DeepBlend Studio Service Definition, protocol contracts, and stable error codes.",
   "main": "lib/index.js",