Docs / Format mappings / blender

Blender

A host is Rig when it emits entities with POD components keyed by schema ids it supports (honors). Blender scenes (.blend) are encodings. Blender itself, its dependency graph, and an exporter that walks the evaluated scene are fulfillment - not this catalog.

Unlike OpenBIM, there is no rig.blender.* layer. Portable meaning is spatial / geometry / render / animation / simulation. Product names stay out of schema ids (same rule as rig.music.clock). Blender-only fields travel as x.blender.*.

The document is the evaluated scene. Modifier stacks, constraints, drivers, Geometry Nodes, library links, and overrides stay in the .blend file. An exporter evaluates that file, then writes ordinary entities. Two hosts that never ran Blender can exchange the picture. Changing a modifier means evaluating the .blend again.

Map

Blender idea Rig
Scene Unparented rig.spatial.vertex
Collection rig.spatial.group
Object name / scene path rig.meta.named (name, stableId)
Object parent + local matrix rig.spatial.transform + rig.spatial.relationship parent
Empty rig.spatial.vertex on the object entity
Mesh datablock rig.geometry.mesh. Polygons are loops / loopSizes; loop_triangles tessellation is indices
One material slot rig.render.material composes on the drawable
Principled BSDF That material: base colour / metallic / roughness / emission to albedoRgb / metallic / roughness / emissive. An image texture on base colour is albedoMap pointing at rig.media.asset_ref (kind image)
Active UV map / vertex normals Mesh texcoords / normals. Blender UVs and split normals live on loop corners; Rig packs one UV and one normal per vertex, so the corner value of the first loop wins
Curve (Bezier / NURBS) rig.geometry.path3d once resolved to commands, or rig.geometry.spline3d when it stays editable as NURBS
NURBS surface rig.geometry.nurbs_surface
Text object rig.media.text. The font is a rig.media.asset_ref (kind font)
Camera (lens, sensor, ortho) rig.spatial.camera. Lens and sensor become fovYDegrees and aspect; ortho scale becomes orthoHeight. Both look along local -Z
Sun light rig.render.light directional
Point / Spot light Same light, point / spot. Spot angle and blend become outerConeDegrees / innerConeDegrees
World HDRI background rig.render.environment + rig.media.asset_ref (kind image)
Armature / bones rig.anim.skeleton / bind / bone entities. Each bone is an entity: rest pose is bind when it differs, pose at save is rig.spatial.transform, parent is rig.spatial.relationship
Vertex groups + Armature modifier rig.anim.skin on the mesh entity. Group weights become the four heaviest jointWeights per vertex
Action + F-Curves rig.anim.clip + rig.anim.track, sampled. Frame numbers become seconds through the scene FPS
Linked duplicate / Collection instance (expanded) rig.spatial.instance
Linked library asset left unexpanded rig.media.asset_ref kind model
Rigid body / collision / joint rig.sim.rigidbody / rig.sim.collider / rig.sim.joint
Hidden object (hide_viewport / hide_render) rig.render.visibility on that entity (Rig hide does not inherit)
Source .blend One asset_ref (kind model) a writer merges authored transforms and visibility back onto

Axis, unit, time, and quaternion conversion sit at the edge. 3D is right-handed, +Y up (document Axes). Blender is right-handed, +Z up, so a point converts as (x, y, z) to (x, z, -y) and a rotation by conjugating with that basis change. Scene unit scale becomes document.defaultUnit (1.0 with metres is "m"). Blender quaternions are w, x, y, z; Rig rotation is [x, y, z, w]. Frames become seconds (frame / fps).

Bone locals need care: a Blender bone's local frame has +Y along the bone, so a child bone's rest offset is (0, bone length, 0) in its parent's frame, under a parent rotation that carries that frame. Convert each bone local by the same conjugation (C * L * C-inverse) as any other object - do not convert bone offsets as if they were armature-space points. The composed hierarchy, and inverseBind converted the same way, then agree with the converted mesh.

rig.anim.skin is four influences per vertex. A vertex weighted to more bones keeps the four heaviest weights and renormalizes - same rule as usd.md and spine.md.

Custom properties (ID properties), panel state, and evaluated-only hints travel as x.blender.*. Area lights stay in the .blend file - rig.render.light has no area lights. Shape keys stay in the .blend file, like USD blend shapes.

Sketch

A scene, a collection with a cube and a camera, and a sun:

{
  "entities": [
    {
      "id": "scene",
      "components": {
        "rig.meta.named": { "name": "Scene", "stableId": "Scene" },
        "rig.spatial.vertex": {}
      }
    },
    {
      "id": "cube",
      "components": {
        "rig.meta.named": { "name": "Cube", "stableId": "Scene/Rig/Cube" },
        "rig.spatial.relationship": { "parent": "scene" },
        "rig.spatial.transform": { "position": [0, 1, 0] },
        "rig.geometry.mesh": {
          "positions": [
            -1, -1, -1, 1, -1, -1, 1, 1, -1, -1, 1, -1,
            -1, -1, 1, 1, -1, 1, 1, 1, 1, -1, 1, 1
          ],
          "indices": [
            0, 1, 2, 0, 2, 3, 4, 7, 6, 4, 6, 5, 0, 4, 5, 0, 5, 1,
            1, 5, 6, 1, 6, 2, 2, 6, 7, 2, 7, 3, 3, 7, 4, 3, 4, 0
          ],
          "loops": [
            0, 1, 2, 3, 4, 7, 6, 5, 0, 4, 5, 1, 1, 5, 6, 2, 2, 6, 7, 3, 3, 7, 4, 0
          ],
          "loopSizes": [4, 4, 4, 4, 4, 4],
          "mode": "triangles"
        },
        "rig.render.material": {
          "albedoRgb": [0.8, 0.2, 0.1],
          "roughness": 0.45
        }
      }
    },
    {
      "id": "camera",
      "components": {
        "rig.meta.named": { "name": "Camera", "stableId": "Scene/Rig/Camera" },
        "rig.spatial.relationship": { "parent": "scene" },
        "rig.spatial.transform": { "position": [0, 2, 6] },
        "rig.spatial.camera": { "fovYDegrees": 40, "nearClip": 0.1, "farClip": 100 }
      }
    },
    {
      "id": "sun",
      "components": {
        "rig.meta.named": { "name": "Sun", "stableId": "Scene/Rig/Sun" },
        "rig.spatial.relationship": { "parent": "scene" },
        "rig.spatial.transform": {
          "rotation": [-0.4226, 0, 0, 0.9063]
        },
        "rig.render.light": {
          "type": "directional",
          "intensity": 3
        }
      }
    }
  ]
}

(Wrap in a full document with "rig" set to the current VERSION before validating.)

Stay out

Stay out Why
Modifier stack, Geometry Nodes Evaluation stays in the .blend. The .rig is the evaluated picture
Constraints, drivers, NLA strips Solvers and blending are fulfillment. Actions sample to tracks; the rest evaluates, then exports
Library linking, overrides, proxies Linking stays in the .blend file. Expand an instance, or leave it as asset_ref
Shader node trees, Cycles / Eevee settings Networks and renderers are fulfillment. Only the Principled base channels port
Shape keys, sculpt / multires detail Mesh morphs and detail layers stay encoding until a second host stores them
UV maps beyond the active one, split normals per corner One texcoords / normals packing on the mesh
Area lights, particle systems No home in the catalog yet
rig.blender.* Product names stay out of schema ids

Encodings (fulfillment)

Surface Role
.blend Evaluate, then map the result into the table above
tools/blender-addon/ Blender add-on (Export > Rig Document) that walks the evaluated scene and emits this map. Bones, skins, and sampled actions included; see its README for the supported subset
glTF / FBX / OBJ export from Blender The interchange route into hosts that read meshes only; treat it as a mesh bake, not this map
Textures and other sidecars .rigz data/; asset_ref.path is relative to data/
Source asset_ref kind model; a writer merges authored transforms and visibility back onto the .blend, same bargain as kicad.md
x.blender.* Custom properties, light energy in Blender units, extra UV layer names - travel; do not port

Example: examples/blender-scene.json.