@volter/editor-blender 0.1.150 → 0.1.151

package/LICENSE

@@ -29,18 +29,27 @@ ARTWORK is not.
   provenance file and emits `blender.icons.json`.
 
   The remaining 149 glyphs are our own drawings in Blender's idiom, and
-  `contributions/blender.palette.json` is a transcription of Blender's default
-  theme colours. Neither the traced paths nor anything derived from them may
-  be copied into an Apache-2.0 or MIT part of this repository —
-  `packages/editor`'s own icon set included.
+  `themes/blender.json` is a transcription of Blender's default theme colours.
+  Neither the traced paths nor anything derived from them may be copied into an
+  Apache-2.0 or MIT part of this repository — `packages/editor`'s own icon set
+  included.
+
+  THE PRODUCT ICON FONT CARRIES THE SAME TRACED GLYPHS.
+
+  `producticons/blender-icons.otf` (with `producticons/blender-product-icon-theme.json`)
+  is generated from `contributions/blender.icons.json` by
+  `scripts/workbench/generate-icons.mjs`, so it includes the traced glyphs and is
+  under GPL-3.0-or-later with them. `themes/blender.json`, the colour theme, and the
+  product icon theme are this package's Code-OSS contributions.
 
   ONE SOURCE FILE FOLLOWS BLENDER'S OWN CODE.
 
-  `contributions/blender-pose.ts` evaluates a pose as Blender does, and is
-  written from Blender's source: its damped-track constraint follows
-  `damptrack_do_transform` statement by statement, and its NLA stack, channel
-  blending, bone matrices and F-Curve evaluation follow the Blender functions
-  its header names. It is a derivative work of GPL-2.0-or-later code and,
+  `contributions/blender-pose.ts` places the NLA's strips as Blender does, and
+  is written from Blender's source: which strip a frame falls on, the action
+  frame it shows, its influence (one keyed influence F-Curve evaluated as
+  `fcurve_eval_keyframes` does) and where the active action sits follow the
+  Blender functions its header names. The pose itself is three.js's
+  (`blender-mixer-pose.ts`, the package's own licence). It is a derivative work of GPL-2.0-or-later code and,
   exercising Blender's "or later", is conveyed under the GNU General Public
   License, version 3 or later, not the AGPL. The file says so in its header.
   It may not be copied into an Apache-2.0 or MIT part of this repository.

package/README.md

@@ -1,12 +1,12 @@
 # Blender integration
 
 Blender modeling documents, inspectors, commands, layouts and presentation for
-Volter Editor. The integration talks to the independent Blender engine over its
+Cyclotron. The integration talks to the independent Blender engine over its
 worker wire and contributes its editing surfaces through the SDK.
 
 The package uses the project contracts and shared Three rendering/capture
 utilities. It imports no editor-core internals and no game runtime. Its
-contributions are enumerated in package.json; the eventual product composes
+contributions are enumerated in package.json; Cyclotron composes
 that list through the host's contribution loader.
 
 Run `npm run typecheck -w @volter/editor-blender` through the active World.
@@ -24,6 +24,6 @@ While opening, the document shows the last available model photograph as a
 labeled read-only preview and a loading panel. Without a preview it shows a
 full status surface. A failed open offers Retry and Return to previous model.
 
-This is a private migration staging package. Full editor startup, live editing,
-wire/branding migration and existing-consumer cutover remain unfinished. Passing
-a package build is not proof that the complete editor is ready to release.
+A package build does not establish product readiness. Verify file persistence,
+native history, visible presentation and resource cleanup through Cyclotron's
+own document and command doors.

package/contributions/blender-animation-editors.tsx

@@ -7,15 +7,9 @@
  *   character plays it; the channel list is one row per bone with the frames it keys.
  * - **NLA** (`SPACE_NLA`): each armature's tracks, bottom track last as Blender lists them, their
  *   strips over scene frames, and the active action's own line on top.
- *
- * WHILE A GAME RUNS both show what the game is animating, read-only, the way a game engine's
- * animator view highlights the live state: each character's clips as its last update posed them
- * (`blender-play-skin.ts`'s `live`), with the frame and influence of each. Nothing is written
- * then: the game owns its copy.
  */
 import { type ReactNode, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
 import { blenderRnaSet, blenderRnaVersion, subscribeBlenderRna } from '../host/blender-runtime-host';
-import { liveAnimation, subscribeLiveAnimation } from '../src/play-live';
 import {
   type AnimationEditor,
   setTimelineViewState,
@@ -23,7 +17,7 @@ import {
   timelineViewState,
   timelineViewVersion,
 } from '../src/timeline-view-state';
-import { PlayModeSwitch } from './blender-game-panel';
+import { PlayModeSwitch } from './blender-play-area';
 import { blenderSkin, blenderSkinVersion, subscribeBlenderSkin } from './blender-runtime-skin';
 import {
   CHANNEL_HEIGHT,
@@ -69,21 +63,6 @@ export function AnimationEditorMenu() {
   );
 }
 
-/** Re-render on every frame while a game runs (its animation changes each update), else never. */
-function useLive() {
-  const live = useSyncExternalStore(subscribeLiveAnimation, liveAnimation, () => null);
-  const [, setTick] = useState(0);
-  useEffect(() => {
-    if (!live) return;
-    let frame = requestAnimationFrame(function tick() {
-      setTick((n) => (n + 1) % 1_000_000);
-      frame = requestAnimationFrame(tick);
-    });
-    return () => cancelAnimationFrame(frame);
-  }, [live]);
-  return live;
-}
-
 function useMeasured() {
   const ref = useRef<HTMLDivElement | null>(null);
   const [size, setSize] = useState({ w: 0, h: 0 });
@@ -190,36 +169,27 @@ const address = (armature: string) => `bpy.data.objects[${JSON.stringify(armatur
 export function BlenderActionEditor() {
   useSyncExternalStore(subscribeBlenderRna, blenderRnaVersion, blenderRnaVersion);
   useSyncExternalStore(subscribeBlenderSkin, blenderSkinVersion, blenderSkinVersion);
-  const live = useLive();
   const { ref, size } = useMeasured();
   const [refusal, setRefusal] = useState<string | null>(null);
   const play = blenderSkin.state();
   const armature = blenderSkin.subject ?? play.armature;
-  const running = live?.live().find((one) => one.armature === armature) ?? null;
-  // READ-ONLY WHILE ANY GAME RUNS: the game owns its copy, and the document is not edited under it.
-  const gameRunning = live !== null;
-  const top = running?.layers.at(-1) ?? null;
-  const action = running ? top?.action ?? null : play.action;
-  const channels = useMemo(
-    () => (running && action ? live!.channels(running.armature, action) : blenderSkin.channels()),
-    // The live clip's keys do not change while it plays; the edited clip's change with its revision.
-    [running ? action : play.action, play.engineCalls, live],
-  );
+  const action = play.action;
+  // The edited clip's keys change with its revision.
+  const channels = useMemo(() => blenderSkin.channels(), [play.action, play.engineCalls]);
   const frames = channels.flatMap((channel) => channel.keys);
   const start = frames.length ? Math.min(...frames) : play.start;
   const end = frames.length ? Math.max(...frames) : play.end;
   const width = Math.max(0, size.w - CHANNELS_WIDTH);
   const { toX, majors, toFrame } = ruler(start, end, width);
-  const frame = running ? top?.frame ?? start : play.frame;
+  const frame = play.frame;
   const rowTop = (i: number) => SCRUB_HEIGHT + CHANNEL_HEIGHT * (i + 1);
   const height = SCRUB_HEIGHT + CHANNEL_HEIGHT * (channels.length + 2);
   const summary = [...new Set(frames)].sort((a, b) => a - b);
 
   const pick = async (name: string) => {
-    if (!armature || gameRunning) return;
+    if (!armature) return;
     setRefusal(null);
-    // ONE WRITE, as Blender's own selector makes it: assigning the action lets Blender choose the
-    // slot that fits this armature (measured: `OBArmature` for a UAL1 clip on a renamed rig).
+    // Assign the action once and let Blender choose the slot for this armature.
     try {
       await blenderRnaSet(address(armature), 'action', `bpy.data.actions[${JSON.stringify(name)}]`);
     } catch (error) {
@@ -234,8 +204,8 @@ export function BlenderActionEditor() {
         aria-label="Action"
         data-testid="action-editor-action"
         value={action ?? ''}
-        disabled={!armature || gameRunning}
-        title={gameRunning ? 'A game is running; it chooses the clips while it runs' : 'The action this armature plays (animation_data.action)'}
+        disabled={!armature}
+        title="The action this armature plays (animation_data.action)"
         onChange={(event) => void pick(event.target.value)}
         style={{
           height: TIMELINE_CHROME.unit,
@@ -248,13 +218,8 @@ export function BlenderActionEditor() {
         }}
       >
         {action === null ? <option value="">No action</option> : null}
-        {(running && action ? [action] : blenderSkin.actionNames()).map((name) => <option key={name} value={name}>{name}</option>)}
+        {blenderSkin.actionNames().map((name) => <option key={name} value={name}>{name}</option>)}
       </select>
-      {running ? (
-        <span data-testid="action-editor-live" style={{ color: TIMELINE_THEME.playhead }}>
-          ● game running: {running.layers.map((layer) => `${layer.action} @${layer.frame.toFixed(1)} ×${layer.influence.toFixed(2)}`).join(' + ')}
-        </span>
-      ) : null}
       <div style={{ flex: 1 }} />
       {refusal ? <span style={{ color: TIMELINE_CHROME.refusal }}>{refusal}</span> : null}
     </Header>
@@ -274,10 +239,9 @@ export function BlenderActionEditor() {
           <svg
             width={width}
             height={height}
-            style={{ display: 'block', cursor: gameRunning ? 'default' : 'ew-resize' }}
+            style={{ display: 'block', cursor: 'ew-resize' }}
             aria-label="Action Editor"
             onPointerDown={(event) => {
-              if (gameRunning) return;
               const box = event.currentTarget.getBoundingClientRect();
               blenderSkin.transport?.seekFrame(Math.round(toFrame(event.clientX - box.left)));
             }}
@@ -298,42 +262,27 @@ export function BlenderActionEditor() {
 export function BlenderNlaEditor() {
   useSyncExternalStore(subscribeBlenderRna, blenderRnaVersion, blenderRnaVersion);
   useSyncExternalStore(subscribeBlenderSkin, blenderSkinVersion, blenderSkinVersion);
-  const live = useLive();
   const { ref, size } = useMeasured();
   const play = blenderSkin.state();
   const stacks = blenderSkin.stacks();
-  const running = live?.live() ?? null;
   const width = Math.max(0, size.w - CHANNELS_WIDTH);
   const { toX, majors } = ruler(play.start, play.end, width);
-  type Row = { label: string; kind: 'armature' | 'action' | 'track'; strips: { name: string; start: number; end: number; mute: boolean }[]; live?: string; mute?: boolean };
+  type Row = { label: string; kind: 'armature' | 'action' | 'track'; strips: { name: string; start: number; end: number; mute: boolean }[]; mute?: boolean };
   const rows: Row[] = [];
   for (const stack of stacks) {
-    const layers = running?.find((one) => one.armature === stack.armature)?.layers ?? null;
-    const influence = (track: string | null) => {
-      const layer = layers?.find((one) => one.track === track);
-      return layer ? `@${layer.frame.toFixed(1)} ×${layer.influence.toFixed(2)}` : undefined;
-    };
     rows.push({ label: stack.armature, kind: 'armature', strips: [] });
-    const activeAction = layers ? layers.find((one) => one.track === null)?.action ?? null : stack.action;
-    const activeLive = influence(null);
-    rows.push({ label: activeAction ? `[Action] ${activeAction}` : '[Action] (none)', kind: 'action', strips: [], ...(activeLive ? { live: activeLive } : {}) });
+    rows.push({ label: stack.action ? `[Action] ${stack.action}` : '[Action] (none)', kind: 'action', strips: [] });
     for (const track of [...(stack.animation?.tracks ?? [])].reverse()) {
-      const playingHere = influence(track.name);
       rows.push({
         label: track.name,
         kind: 'track',
         mute: track.mute,
         strips: track.strips.map((strip) => ({ name: strip.name, start: strip.start, end: strip.end, mute: strip.mute })),
-        ...(playingHere ? { live: playingHere } : {}),
       });
     }
   }
   const height = SCRUB_HEIGHT + CHANNEL_HEIGHT * (rows.length + 1);
-  const header = (
-    <Header>
-      {running ? <span data-testid="nla-live" style={{ color: TIMELINE_THEME.playhead }}>● game running: each playing track shows the game's frame and influence; the strips are the file's layout</span> : null}
-    </Header>
-  );
+  const header = <Header />;
   return (
     <Frame header={header}>
       <div ref={ref} style={{ flex: 1, minHeight: 0, overflowY: 'auto', overflowX: 'hidden' }}>
@@ -353,7 +302,7 @@ export function BlenderNlaEditor() {
                   color: row.kind === 'armature' ? TIMELINE_CHROME.textHi : row.mute ? '#6a6a6a' : TIMELINE_CHROME.text,
                 }}
               >
-                {row.label}{row.live ? <span style={{ color: TIMELINE_THEME.playhead }}> {row.live}</span> : null}
+                {row.label}
               </div>
             ))}
           </div>
@@ -370,15 +319,14 @@ export function BlenderNlaEditor() {
                     width={Math.max(2, toX(strip.end) - toX(strip.start))}
                     height={CHANNEL_HEIGHT - 4}
                     rx={2}
-                    fill={strip.mute || row.mute ? '#4a4a4a' : running ? (row.live ? '#5a7fb8' : '#555555') : '#7b7b7b'}
-                    opacity={running ? 0.6 : 1}
+                    fill={strip.mute || row.mute ? '#4a4a4a' : '#7b7b7b'}
                     stroke="#1a1a1a"
                   />
                   <text x={toX(strip.start) + 4} y={y + CHANNEL_HEIGHT - 7} fill="#ffffff" fontSize={10}>{strip.name}</text>
                 </g>
               ));
             })}
-            {running ? null : <Playhead x={toX(play.frame)} frame={play.frame} height={height} />}
+            <Playhead x={toX(play.frame)} frame={play.frame} height={height} />
           </svg>
         </div>
       </div>

package/contributions/blender-display-settings.ts

@@ -0,0 +1,36 @@
+/**
+ * THE SCENE'S DISPLAY TRANSFORM AS BLENDER HOLDS IT: `scene.view_settings` (view transform, look,
+ * exposure in stops, gamma) read through the RNA door, as `BlenderDisplaySettings`. The Rendered
+ * areas and Play draw through it (`blender-runtime.document.tsx`), and a web export carries it so
+ * the page draws through the same OCIO processor (`blender-export.verbs.ts`).
+ */
+import type { BlenderDisplaySettings } from '@volter/blender-engine/browser/three/blender-display-transform';
+import { blenderRna, blenderRnaContext } from '../host/blender-runtime-host';
+
+/** Null while Blender's session has no scene to read; throws for a display device the browser
+ *  has no processor for. */
+export async function readBlenderDisplaySettings(): Promise<BlenderDisplaySettings | null> {
+  const context = await blenderRnaContext();
+  if (!context) return null;
+  const [settings, displaySettings] = await Promise.all([
+    blenderRna(`${context.scene}.view_settings`),
+    blenderRna(`${context.scene}.display_settings`),
+  ]);
+  if (settings?.kind !== 'struct' || settings.type !== 'ColorManagedViewSettings') return null;
+  if (displaySettings?.kind === 'struct') {
+    const device = displaySettings.groups.flatMap(group => group.rows).find(row => row.identifier === 'display_device')?.value;
+    if (typeof device === 'string' && device !== 'sRGB')
+      throw new Error(`Blender display device ${device} has no browser display processor yet`);
+  }
+  const rows = settings.groups.flatMap(group => group.rows);
+  const transform = rows.find(row => row.identifier === 'view_transform')?.value;
+  const stops = rows.find(row => row.identifier === 'exposure')?.value;
+  const look = rows.find(row => row.identifier === 'look')?.value;
+  const gamma = rows.find(row => row.identifier === 'gamma')?.value;
+  return {
+    transform: typeof transform === 'string' ? transform : 'AgX',
+    look: typeof look === 'string' ? look : 'None',
+    exposure: typeof stops === 'number' ? 2 ** stops : 1,
+    gamma: typeof gamma === 'number' ? gamma : 1,
+  };
+}

package/contributions/blender-export-gltf.ts

@@ -0,0 +1,228 @@
+/**
+ * THE SCENE AS GLTF, ANIMATION INCLUDED (`blender-export-gltf`, `docs/SCENE-ANIMATION.md` step 6): the
+ * clips the editor plays, written so another engine (Godot, Unity, a viewer) plays the same.
+ *
+ * - THE MODEL is the presented scene (`BlenderRuntimeView.root`: meshes with their skins, materials,
+ *   cameras, lights), through three.js's `GLTFExporter`.
+ * - EVERY ARMATURE'S ACTIONS (its assigned action and its NLA strips' actions)
+ *   become one glTF animation each, `<armature>|<action>`: its bones' transforms as Blender sampled
+ *   them (`blenderActionClip`), on node channels.
+ * - THE SCENE'S MOVIE (`blender-playback-movie.ts`) becomes the animation `Scene`: the moving objects and
+ *   cameras on node channels, the shape keys as morph target weights.
+ * - A MATERIAL'S KEYED INPUTS (base colour, alpha, emission) become `KHR_animation_pointer` channels on
+ *   the material in the animation `Materials`; an emission over 1 is carried by
+ *   `KHR_materials_emissive_strength`.
+ *
+ * Constraints are held at the presented frame: a reader receives TRS, never constraints.
+ */
+import * as THREE from 'three';
+import { GLTFExporter } from 'three/addons/exporters/GLTFExporter.js';
+import type { BlenderRuntimeView } from '@volter/blender-engine/browser/three/blender-runtime-view';
+import { mixerClip } from './blender-mixer-pose';
+import { playMovie } from './blender-playback-movie';
+import type { BlenderActionClip, BlenderSceneMovie } from '@volter/blender-engine/browser/rna';
+
+/** A glTF document as JSON, as far as this file writes into it. */
+interface GltfJson {
+  materials?: { name?: string; alphaMode?: string; pbrMetallicRoughness?: { baseColorFactor?: number[] }; emissiveFactor?: number[]; extensions?: Record<string, unknown> }[];
+  animations?: { name?: string; samplers: { input: number; output: number; interpolation: string }[]; channels: unknown[] }[];
+  accessors?: unknown[];
+  bufferViews?: unknown[];
+  buffers?: { byteLength: number; uri?: string }[];
+  extensionsUsed?: string[];
+}
+
+/** What a model's geometry carries into glTF: the standard attributes. Everything else on a drawn
+ *  geometry is the presenter's (the drawn vertex's Blender vertex, its orco, a shading's inputs). */
+const MODEL_ATTRIBUTES = new Set(['position', 'normal', 'tangent', 'uv', 'uv1', 'uv2', 'uv3', 'color', 'skinIndex', 'skinWeight']);
+
+/** One keyed material input, as the movie plays it on a presented mesh. */
+interface Pointer { readonly material: THREE.Material; readonly prop: 'color' | 'emissive' | 'opacity'; readonly track: THREE.KeyframeTrack }
+
+export interface GltfExport {
+  readonly json: GltfJson;
+  readonly animations: readonly string[];
+  readonly pointers: number;
+  readonly skipped: readonly string[];
+  readonly failed: readonly string[];
+}
+
+/** Write the scene and its animation as inline JSON glTF. */
+export async function exportSceneGltf(view: BlenderRuntimeView,
+  read: {
+    clip(armature: string, action: string): Promise<BlenderActionClip | null>;
+    movie(): Promise<BlenderSceneMovie | null>;
+  }): Promise<GltfExport> {
+  const clips: THREE.AnimationClip[] = [];
+  const failed: string[] = [];
+  const skipped = new Set<string>();
+  // EVERY ARMATURE'S ACTIONS: one animation each
+  const facts = view.animationFacts();
+  for (const rig of view.skeletons.rigs()) {
+    const entry = facts.armatures[rig.armature];
+    if (!entry) continue;
+    const names = new Set<string>();
+    if (entry.action) names.add(entry.action);
+    for (const track of entry.animation?.tracks ?? []) for (const strip of track.strips) if (strip.action) names.add(strip.action);
+    for (const action of [...names].sort()) {
+      try {
+        const baked = await read.clip(rig.armature, action);
+        const clip = baked ? mixerClip(baked) : null;
+        if (!clip) continue;
+        const frames = Math.max(1, Math.round(clip.end - clip.start) + 1);
+        const times = Float32Array.from({ length: frames }, (_, i) => i / clip.fps);
+        const column = (values: Float32Array, stride: number): [Float32Array, Float32Array] =>
+          values.length === stride ? [new Float32Array([0]), values] : [times.slice(0, values.length / stride), values];
+        const tracks: THREE.KeyframeTrack[] = [];
+        for (const [name, sampled] of clip.bones) {
+          const bone = rig.bones.get(name);
+          if (!bone) continue;
+          tracks.push(new THREE.VectorKeyframeTrack(`${bone.uuid}.position`, ...column(sampled.position, 3)));
+          tracks.push(new THREE.QuaternionKeyframeTrack(`${bone.uuid}.quaternion`, ...column(sampled.quaternion, 4)));
+          tracks.push(new THREE.VectorKeyframeTrack(`${bone.uuid}.scale`, ...column(sampled.scale, 3)));
+        }
+        if (tracks.length) clips.push(new THREE.AnimationClip(`${rig.armature}|${action}`, (frames - 1) / clip.fps, tracks));
+      } catch (error) {
+        failed.push(`${rig.armature} / ${action}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+  }
+  // THE SCENE'S MOVIE: objects and cameras, shape keys (morph weights), and materials (pointers below),
+  // with the meshes in their own materials whatever the viewport shows
+  const data = await read.movie();
+  return view.withAuthoredMaterials(async () => {
+  const movie = data ? playMovie(view, data, new THREE.AnimationMixer(view.root)) : null;
+  for (const warning of movie?.warnings ?? []) skipped.add(warning);
+  const pointers: Pointer[] = [];
+  const sceneTracks: THREE.KeyframeTrack[] = [];
+  for (const clip of movie?.clips() ?? []) {
+    for (const track of clip.tracks) {
+      const material = /^([^.]+)\.material(?:\[(\d+)\])?\.(color|emissive|opacity)$/.exec(track.name);
+      if (material) {
+        const mesh = view.root.getObjectByProperty('uuid', material[1]!) as THREE.Mesh | undefined;
+        const worn = mesh ? (Array.isArray(mesh.material) ? mesh.material[Number(material[2] ?? 0)] : mesh.material) : undefined;
+        if (worn) pointers.push({ material: worn, prop: material[3] as Pointer['prop'], track });
+        continue;
+      }
+      if (track.name.endsWith('.visible')) { skipped.add('keyed visibility is not written to the glTF export'); continue; }
+      sceneTracks.push(track);
+    }
+  }
+  if (sceneTracks.length) clips.push(new THREE.AnimationClip('Scene', -1, sceneTracks));
+  view.root.updateMatrixWorld(true);
+  // THE PRESENTER'S OWN ATTRIBUTES (the drawn vertex's Blender vertex, its orco, the Solid shading's
+  // hints) are the editor's bookkeeping, not the model's: set aside while it writes
+  const aside: [THREE.BufferGeometry, string, THREE.BufferAttribute | THREE.InterleavedBufferAttribute][] = [];
+  let json!: GltfJson;
+  try {
+  view.root.traverse((object) => {
+    const geometry = (object as THREE.Mesh).geometry as THREE.BufferGeometry | undefined;
+    if (!geometry?.attributes) return;
+    for (const name of Object.keys(geometry.attributes)) {
+      if (MODEL_ATTRIBUTES.has(name)) continue;
+      aside.push([geometry, name, geometry.getAttribute(name)]);
+      geometry.deleteAttribute(name);
+    }
+  });
+    // The presenter carries no mesh tangents. GLTFExporter inverts no-tangent OpenGL normal maps, matching GLTFLoader’s negative normalScale.y and preserving Blender’s orientation; DirectX maps use the opposite sign.
+    const exporter = new GLTFExporter();
+  json = await exporter.parseAsync(view.root, { binary: false, animations: clips, onlyVisible: false }) as GltfJson;
+  writePointers(json, pointers);
+  } finally {
+    for (const [geometry, name, attribute] of aside) geometry.setAttribute(name, attribute);
+    movie?.dispose();
+  }
+  return { json, animations: (json.animations ?? []).map((one) => one.name ?? ''), pointers: pointers.length, skipped: [...skipped], failed };
+  });
+}
+
+/** THE MATERIALS' ANIMATION as `KHR_animation_pointer` channels, with their keys in a buffer of their own. */
+function writePointers(json: GltfJson, pointers: readonly Pointer[]): void {
+  // AN EMISSION OVER 1 (a glow the movie set, an emission strength) is a factor of at most 1 times a strength
+  for (const material of json.materials ?? []) {
+    const factor = material.emissiveFactor;
+    const top = factor ? Math.max(...factor) : 0;
+    if (!factor || top <= 1) continue;
+    material.emissiveFactor = factor.map((one) => one / top);
+    const had = (material.extensions?.['KHR_materials_emissive_strength'] as { emissiveStrength?: number } | undefined)?.emissiveStrength ?? 1;
+    material.extensions = { ...material.extensions, KHR_materials_emissive_strength: { emissiveStrength: had * top } };
+    json.extensionsUsed = [...new Set([...(json.extensionsUsed ?? []), 'KHR_materials_emissive_strength'])];
+  }
+  if (!pointers.length) return;
+  const accessors = (json.accessors ??= []);
+  const views = (json.bufferViews ??= []);
+  const buffers = (json.buffers ??= []);
+  const chunks: Float32Array[] = [];
+  let offset = 0;
+  const buffer = buffers.length;
+  const accessor = (values: Float32Array, type: 'SCALAR' | 'VEC3' | 'VEC4', bounds = false): number => {
+    views.push({ buffer, byteOffset: offset, byteLength: values.byteLength });
+    const size = type === 'SCALAR' ? 1 : type === 'VEC3' ? 3 : 4;
+    accessors.push({
+      bufferView: views.length - 1, componentType: 5126, count: values.length / size, type,
+      ...(bounds ? { min: [Math.min(...values)], max: [Math.max(...values)] } : {}),
+    });
+    chunks.push(values);
+    offset += values.byteLength;
+    return accessors.length - 1;
+  };
+  const samplers: { input: number; output: number; interpolation: string }[] = [];
+  const channels: unknown[] = [];
+  const used = new Set<string>(['KHR_animation_pointer']);
+  const channel = (times: Float32Array, values: Float32Array, type: 'SCALAR' | 'VEC3' | 'VEC4', pointer: string): void => {
+    samplers.push({ input: accessor(times, 'SCALAR', true), output: accessor(values, type), interpolation: 'LINEAR' });
+    channels.push({ sampler: samplers.length - 1, target: { path: 'pointer', extensions: { KHR_animation_pointer: { pointer } } } });
+  };
+  const byMaterial = new Map<THREE.Material, Partial<Record<Pointer['prop'], THREE.KeyframeTrack>>>();
+  for (const one of pointers) byMaterial.set(one.material, { ...byMaterial.get(one.material), [one.prop]: one.track });
+  for (const [material, props] of byMaterial) {
+    const index = (json.materials ?? []).findIndex((one) => one.name === material.name);
+    if (index < 0) continue;
+    const own = material as THREE.MeshStandardMaterial;
+    // BASE COLOUR AND ALPHA are one glTF factor
+    if (props.color || props.opacity) {
+      if (props.opacity?.values.some(value => Number(value) < 1)) json.materials![index]!.alphaMode = 'BLEND';
+      const times = (props.color ?? props.opacity)!.times as Float32Array;
+      const color = props.color?.values as Float32Array | undefined;
+      const alpha = props.opacity?.values as Float32Array | undefined;
+      const values = new Float32Array(times.length * 4);
+      for (let i = 0; i < times.length; i++) {
+        values[i * 4] = color ? color[Math.min(i, color.length / 3 - 1) * 3]! : own.color?.r ?? 1;
+        values[i * 4 + 1] = color ? color[Math.min(i, color.length / 3 - 1) * 3 + 1]! : own.color?.g ?? 1;
+        values[i * 4 + 2] = color ? color[Math.min(i, color.length / 3 - 1) * 3 + 2]! : own.color?.b ?? 1;
+        values[i * 4 + 3] = alpha ? alpha[Math.min(i, alpha.length - 1)]! : own.opacity ?? 1;
+      }
+      channel(times, values, 'VEC4', `/materials/${index}/pbrMetallicRoughness/baseColorFactor`);
+    }
+    // EMISSION: glTF's factor is at most 1; the strength over it goes in KHR_materials_emissive_strength
+    if (props.emissive) {
+      const times = props.emissive.times as Float32Array;
+      const glow = props.emissive.values as Float32Array;
+      const count = Math.min(times.length, glow.length / 3);
+      const factor = new Float32Array(count * 3);
+      const strength = new Float32Array(count);
+      for (let i = 0; i < count; i++) {
+        const top = Math.max(1, glow[i * 3]!, glow[i * 3 + 1]!, glow[i * 3 + 2]!);
+        strength[i] = top;
+        for (let c = 0; c < 3; c++) factor[i * 3 + c] = glow[i * 3 + c]! / top;
+      }
+      channel(times.slice(0, count), factor, 'VEC3', `/materials/${index}/emissiveFactor`);
+      if (strength.some((one) => one > 1)) {
+        const entry = json.materials![index]!;
+        entry.extensions = { ...entry.extensions, KHR_materials_emissive_strength: { emissiveStrength: Math.max(...strength) } };
+        used.add('KHR_materials_emissive_strength');
+        channel(times.slice(0, count), strength, 'SCALAR', `/materials/${index}/extensions/KHR_materials_emissive_strength/emissiveStrength`);
+      }
+    }
+  }
+  if (!channels.length) return;
+  // THE KEYS, in a buffer of their own, inline as the rest of the JSON export is
+  const bytes = new Uint8Array(offset);
+  let at = 0;
+  for (const chunk of chunks) { bytes.set(new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength), at); at += chunk.byteLength; }
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  buffers.push({ byteLength: bytes.byteLength, uri: `data:application/octet-stream;base64,${btoa(binary)}` });
+  (json.animations ??= []).push({ name: 'Materials', samplers, channels });
+  json.extensionsUsed = [...new Set([...(json.extensionsUsed ?? []), ...used])];
+}

package/contributions/blender-export.verbs.ts

@@ -0,0 +1,39 @@
+import { blenderModelView } from '@volter/blender-engine/browser/three/blender-runtime-view';
+import type { EditorCommandResult, VerbHandler } from '@volter/sdk/commands';
+import { editorHost } from '@volter/sdk/host';
+import { blenderActionClip, blenderSceneMovie } from '../host/blender-runtime-host';
+import { modelDocumentSource, servedModelDocument } from '../src/play-mode';
+import { exportSceneGltf } from './blender-export-gltf';
+
+/**
+ * THE SCENE AS GLTF (`blender-export-gltf`, docs/SCENE-ANIMATION.md step 6): the presented model with
+ * every armature's actions, the scene's movie and its keyed materials (`blender-export-gltf.ts`),
+ * written to `out` (project-relative, `.gltf`; default `exports/<name>.gltf`).
+ */
+async function exportGltf(command: Record<string, unknown>): Promise<EditorCommandResult> {
+  const documentId = servedModelDocument();
+  const blend = documentId ? modelDocumentSource(documentId) ?? modelDocumentSource(documentId.replace(/#.*$/, '')) : null;
+  if (!blend) return { ok: false, error: 'No model document is open: open the .blend to export, then export again.' };
+  if (blenderModelView.snapshot() === null)
+    return { ok: false, error: `${blend} has not been presented yet: wait for the model to show, then export again.` };
+  const named = command['out'];
+  if (named !== undefined && (typeof named !== 'string' || !/\.gltf$/i.test(named)))
+    return { ok: false, error: `blender-export-gltf's out is a project-relative .gltf path; it was given ${JSON.stringify(named)}.` };
+  const out = (named as string | undefined) ?? `exports/${blend.replace(/^.*\//, '').replace(/\.blend$/i, '')}.gltf`;
+  const started = performance.now();
+  const written = await exportSceneGltf(blenderModelView, {
+    clip: (armature, action) => blenderActionClip({ object: armature, action, summary: false }),
+    movie: () => blenderSceneMovie(),
+  });
+  const text = JSON.stringify(written.json);
+  await editorHost().files.write(out, text);
+  return {
+    ok: true,
+    data: { out, blend, bytes: text.length, animations: written.animations, pointers: written.pointers, skipped: written.skipped, failed: written.failed, ms: Math.round(performance.now() - started) },
+  };
+}
+
+export const exportVerbs: Readonly<Record<string, VerbHandler>> = {
+  // The model and its animation as glTF: every armature's clips read from Blender.
+  'blender-export-gltf': (command) => exportGltf(command as Record<string, unknown>),
+};