@deepblend/dsh-blender-contracts 0.2.13 → 0.2.15

package/lib/scene-spec.js

@@ -185,6 +185,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 +283,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,

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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://deepblend.local/schemas/scene-spec.schema.json",
   "title": "DeepBlend SceneSpec v1",
-  "description": "The structural source of truth for one DeepBlend scene (SPEC §8.1: 'SceneSpec 场景结构事实来源'). A .blend file is a compile artifact of this document, never the authority. Scenes are compiled from a SceneSpec and modified only through ScenePatch operations, so that every revision is diffable, replayable and auditable.",
+  "description": "The structural source of truth for one DeepBlend scene (SPEC \u00a78.1: 'SceneSpec \u573a\u666f\u7ed3\u6784\u4e8b\u5b9e\u6765\u6e90'). A .blend file is a compile artifact of this document, never the authority. Scenes are compiled from a SceneSpec and modified only through ScenePatch operations, so that every revision is diffable, replayable and auditable.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -26,6 +26,13 @@
         "$ref": "#/$defs/asset"
       }
     },
+    "armatures": {
+      "type": "array",
+      "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."
+    },
     "materials": {
       "type": "array",
       "items": {
@@ -83,7 +90,12 @@
       "properties": {
         "color": {
           "$ref": "#/$defs/unitColor",
-          "default": [0.02, 0.021, 0.026, 1]
+          "default": [
+            0.02,
+            0.021,
+            0.026,
+            1
+          ]
         },
         "strength": {
           "type": "number",
@@ -220,7 +232,7 @@
         "path": {
           "type": "string",
           "minLength": 1,
-          "description": "Project-relative POSIX path. Absolute paths and any '..' segment are rejected by the path guard (SPEC §15.2)."
+          "description": "Project-relative POSIX path. Absolute paths and any '..' segment are rejected by the path guard (SPEC \u00a715.2)."
         },
         "sha256": {
           "type": "string",
@@ -383,7 +395,7 @@
       "required": [
         "shape"
       ],
-      "description": "Procedural proxy geometry. M1 has no asset-ingest action yet, so fixtures build their hero objects from generators; asset-instance entities take over as the primary path once blender_asset_ingest lands (SPEC §11).",
+      "description": "Procedural proxy geometry. M1 has no asset-ingest action yet, so fixtures build their hero objects from generators; asset-instance entities take over as the primary path once blender_asset_ingest lands (SPEC \u00a711).",
       "properties": {
         "shape": {
           "type": "string",
@@ -461,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"
         },
@@ -480,7 +496,7 @@
         },
         "locked": {
           "type": "boolean",
-          "description": "A locked entity may still be patched explicitly, but the orchestrator must not propose changes to it autonomously (SPEC §12)."
+          "description": "A locked entity may still be patched explicitly, but the orchestrator must not propose changes to it autonomously (SPEC \u00a712)."
         },
         "visible": {
           "type": "boolean"
@@ -658,7 +674,11 @@
         },
         "targetKind": {
           "type": "string",
-          "enum": ["entity", "camera", "material"],
+          "enum": [
+            "entity",
+            "camera",
+            "material"
+          ],
           "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."
         },
@@ -768,7 +788,7 @@
         "maxSamplesBudget": {
           "type": "integer",
           "minimum": 1,
-          "description": "Upper bound a render action may use. Guards the render-cost threshold of SPEC §15.4."
+          "description": "Upper bound a render action may use. Guards the render-cost threshold of SPEC \u00a715.4."
         }
       }
     },
@@ -786,6 +806,57 @@
           "$ref": "#/$defs/renderProfile"
         }
       }
+    },
+    "bone": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "head",
+        "tail"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "description": "The bone's name inside its armature. A parent names another bone by this, so it is the identity a rig is written in terms of."
+        },
+        "head": {
+          "$ref": "#/$defs/vec3"
+        },
+        "tail": {
+          "$ref": "#/$defs/vec3"
+        },
+        "parent": {
+          "type": "string",
+          "description": "The name of another bone in the SAME armature, or absent for a root. Bones are declared in any order; the compiler resolves the hierarchy, because requiring parents-first would make a rig's declaration depend on its storage order."
+        }
+      }
+    },
+    "armature": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "bones"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "bones": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/bone"
+          },
+          "description": "At least one bone, because an armature with none is a rig that cannot move anything and would silently do nothing."
+        },
+        "transform": {
+          "$ref": "#/$defs/transform"
+        }
+      }
     }
   }
 }

package/package.json

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