@volter/blender-engine 0.1.6 → 0.1.8

package/browser/three/blender-physical-material.ts

@@ -4,6 +4,7 @@
  * that MeshPhysicalMaterial does not expose as properties. */
 import * as THREE from 'three';
 import {z} from 'zod';
+import {applyGraphShader, bindGraphDraw, graphProgramKey, graphUvChannels, setGraphViewport} from './blender-graph-material';
 import {bindNamedUvChannels} from './blender-texture-samplers';
 
 const scalar = z.number().finite();
@@ -33,6 +34,28 @@ export function applyWorldExtinction(material: THREE.MeshPhysicalMaterial, extin
   uniforms.get(material)!.blenderWorldExtinction.value.copy(extinction);
 }
 
+/** A copy of `material` with its own hooks and the same physical values:
+ *  the proxy a pending graph program compiles through, whose program key is
+ *  the one `material` asks for once the graph is swapped in. */
+function graphShadow(material: THREE.MeshPhysicalMaterial): THREE.MeshPhysicalMaterial {
+  const shadow = new THREE.MeshPhysicalMaterial();
+  const held = uniforms.get(material);
+  // The hooks, then the values: `applyPhysicalMaterial` sets its defaults,
+  // which `copy` replaces with the material's own (it leaves hooks alone).
+  applyPhysicalMaterial(shadow);
+  shadow.copy(material);
+  const values = uniforms.get(shadow)!;
+  if (held) {
+    values.blenderCoatIor.value = held.blenderCoatIor.value;
+    values.blenderCoatTint.value.copy(held.blenderCoatTint.value);
+    values.blenderMapClip.value = held.blenderMapClip.value;
+    values.blenderRoughnessClip.value = held.blenderRoughnessClip.value;
+    values.blenderNormalClip.value = held.blenderNormalClip.value;
+    values.blenderWorldExtinction.value.copy(held.blenderWorldExtinction.value);
+  }
+  return shadow;
+}
+
 export function applyPhysicalMaterial(material: THREE.MeshPhysicalMaterial, input?: Physical,
   clips: {map?: boolean; roughness?: boolean; normal?: boolean} = {}): void {
   const data = input ?? defaults;
@@ -55,12 +78,23 @@ export function applyPhysicalMaterial(material: THREE.MeshPhysicalMaterial, inpu
       blenderWorldExtinction: {value: new THREE.Vector3()}};
     uniforms.set(material, values);
     const held = values;
-    material.customProgramCacheKey = () => 'blender-principled-physical-v5';
-    material.onBeforeRender = (_renderer, _scene, _camera, geometry) => bindNamedUvChannels(material, geometry);
+    material.customProgramCacheKey = () => `blender-principled-physical-v5${graphProgramKey(material)}`;
+    material.onBeforeRender = (renderer, scene, camera, geometry, object) => {
+      bindNamedUvChannels(material, geometry);
+      bindGraphDraw(material, geometry, renderer, scene, camera, object, graphShadow);
+      setGraphViewport(renderer);
+    };
     material.onBeforeCompile = shader => {
-      // Three declares channels 0..3. Blender has eight named UV maps in
-      // addition to the default channel; only the used attributes survive GLSL.
-      shader.vertexShader = [4, 5, 6, 7, 8, 9].map(i => `attribute vec2 uv${i};`).join('\n') + '\n' + shader.vertexShader;
+      // Three declares channels 1..3 only for its own maps, and none past 3.
+      // Blender has eight named UV maps beside the default channel (9 is the
+      // missing layer's zeros). Declare only the channels this draw reads: a
+      // driver may count every declared attribute against its sixteen, and
+      // six idle ones leave a graph with a few attributes no room.
+      const read = new Set([material.map, material.roughnessMap, material.normalMap]
+        .flatMap(texture => (texture ? [texture.channel] : [])).concat(graphUvChannels(material)));
+      shader.vertexShader = [...read].filter(i => i > 0).sort((a, b) => a - b)
+        .map(i => (i <= 3 ? `#ifndef USE_UV${i}\nattribute vec2 uv${i};\n#endif` : `attribute vec2 uv${i};`))
+        .join('\n') + '\n' + shader.vertexShader;
       Object.assign(shader.uniforms, held);
       shader.fragmentShader = `uniform float blenderCoatIor;
         uniform vec3 blenderWorldExtinction;
@@ -121,6 +155,9 @@ export function applyPhysicalMaterial(material: THREE.MeshPhysicalMaterial, inpu
             blenderCoatIor * blenderCoatIor - (1.0 - dotNVcc * dotNVcc)));
           outgoingLight *= mix(vec3(1.0), pow(max(blenderCoatTint, vec3(0.0)), vec3(coatPath)), material.clearcoat);
           vec3 Fcc = F_Schlick`);
+      // The material's node graph, when the session shipped one, drives the
+      // surface inputs it carries (`blender-graph-material.ts`).
+      applyGraphShader(material, shader);
     };
     material.needsUpdate = true;
   }

package/browser/three/blender-presenter-change.ts

@@ -0,0 +1,24 @@
+/**
+ * WORK THAT FINISHES AFTER A FRAME WAS APPLIED, announced.
+ *
+ * A presented frame is not the last change to what the presenter draws: a
+ * PNG decodes after the frame that named it, a clone's sampler uploads after
+ * that decode, a sky is derived on a worker, the area-light tables load on
+ * demand, and a graph's program swaps in once `compileAsync` links it. A
+ * stage that draws only when something changed (`BlenderRuntimeView.onChange`)
+ * needs every one of those to say so, or the viewport holds the picture from
+ * before it -- an untextured mesh, a missing sky -- until something else
+ * happens to move. Each such completion calls {@link presenterChanged}.
+ */
+const listeners = new Set<() => void>();
+
+export function presenterChanged(): void {
+  for (const listener of [...listeners]) listener();
+}
+
+export function onPresenterChange(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}

package/browser/three/blender-runtime-geometry.ts

@@ -41,6 +41,13 @@ export interface DrawArrays {
   uv: Float32Array | null;
   /** All named UV layers; material inputs choose their own layer per draw. */
   uvLayers?: {name: string; data: Float32Array}[] | undefined;
+  /** The mesh's generic attribute layers a material's Attribute or Color
+   *  Attribute node can read, four floats per drawn vertex as EEVEE loads them
+   *  (`graphAttributeLayers`). */
+  attributeLayers?: {name: string; data: Float32Array}[] | undefined;
+  /** Per drawn vertex, a deformed mesh's Generated coordinates (0..1), or
+   *  null when the positions are undeformed and orco derives from them. */
+  orco?: Float32Array | null | undefined;
   indices: Uint32Array;
   groups: { start: number; count: number; materialIndex: number }[];
   /** THE BLENDER VERTEX EACH DRAWN VERTEX CAME FROM, one per drawn vertex.
@@ -61,6 +68,8 @@ interface DrawView {
   vertexCount: number;
   normals: Normal[] | null;
   cornerNormal?: Float32Array | undefined;
+  /** Blender's stored orco (-1..1), 3 per vertex. */
+  orco?: Float32Array | undefined;
   co(i: number): THREE.Vector3;
   /** CSR faces: corner `starts[i]..starts[i+1]` hold vertex indices. */
   starts: Uint32Array;
@@ -73,6 +82,49 @@ interface DrawView {
   /** A corner's UV, or undefined when the mesh has no map. */
   uv: ((corner: number) => [number, number]) | null;
   uvLayers?: {name: string; read: (corner: number) => [number, number]}[];
+  /** A corner's value of each generic attribute layer, by vertex, corner and
+   *  face; `corner` and `face` are undefined for a loose vertex. */
+  attributeLayers?: {name: string; domain: string;
+    read: (vertex: number, corner: number | undefined, face: number | undefined) => ArrayLike<number>}[];
+}
+
+/** EEVEE's float4 of an attribute value: float (f, f, f, 1), float2 (x, y, 0,
+ *  1), float3 (x, y, z, 1), a colour as itself, a byte colour decoded from
+ *  sRGB (`ColorGeometry4b::decode`). */
+const GRAPH_ATTRIBUTE_TYPES = new Set(['FLOAT', 'FLOAT2', 'FLOAT_VECTOR', 'FLOAT_COLOR', 'BYTE_COLOR']);
+function srgbToLinear(byte: number): number {
+  const c = byte / 255;
+  return c < 0.04045 ? (c < 0 ? 0 : c * (1 / 12.92)) : ((c + 0.055) * (1 / 1.055)) ** 2.4;
+}
+function attributeFloat4(type: string, values: ArrayLike<number>, i: number): [number, number, number, number] {
+  switch (type) {
+    case 'FLOAT': { const f = Number(values[i]); return [f, f, f, 1]; }
+    case 'FLOAT2': return [Number(values[i * 2]), Number(values[i * 2 + 1]), 0, 1];
+    case 'FLOAT_VECTOR': return [Number(values[i * 3]), Number(values[i * 3 + 1]), Number(values[i * 3 + 2]), 1];
+    case 'BYTE_COLOR': return [srgbToLinear(Number(values[i * 4])), srgbToLinear(Number(values[i * 4 + 1])),
+      srgbToLinear(Number(values[i * 4 + 2])), Number(values[i * 4 + 3]) / 255];
+    default: return [Number(values[i * 4]), Number(values[i * 4 + 1]), Number(values[i * 4 + 2]), Number(values[i * 4 + 3])];
+  }
+}
+/** The readable layers of `attributes`: every generic layer of a type EEVEE
+ *  loads as a float4, on a domain a drawn vertex has a value on. UV maps stay
+ *  `uvLayers`; names Blender keeps internal (`.select_vert`, the positions,
+ *  the custom normals) are not material inputs. */
+function graphAttributeLayers(
+  attributes: readonly {name: string; domain: string; type: string; data: ArrayLike<unknown>}[],
+  flat: (data: ArrayLike<unknown>, type: string) => ArrayLike<number>,
+): NonNullable<DrawView['attributeLayers']> {
+  return attributes
+    .filter(a => GRAPH_ATTRIBUTE_TYPES.has(a.type) && a.domain !== 'EDGE' && !a.name.startsWith('.')
+      && a.name !== 'position' && a.name !== 'custom_normal' && !(a.type === 'FLOAT2' && a.domain === 'CORNER'))
+    .map(a => {
+      const values = flat(a.data, a.type);
+      const zero = [0, 0, 0, 0];
+      return {name: a.name, domain: a.domain, read: (vertex: number, corner: number | undefined, face: number | undefined) =>
+        a.domain === 'POINT' ? attributeFloat4(a.type, values, vertex)
+        : a.domain === 'CORNER' ? (corner === undefined ? zero : attributeFloat4(a.type, values, corner))
+        : face === undefined ? zero : attributeFloat4(a.type, values, face)};
+    });
 }
 
 function drawCore(view: DrawView): Omit<DrawArrays, 'hash'> {
@@ -152,14 +204,19 @@ function drawCore(view: DrawView): Omit<DrawArrays, 'hash'> {
     texcoords = new Float32Array(capacity * 2);
   const sourceVertex = new Uint32Array(capacity);
   const uvLayers = (view.uvLayers ?? []).map(layer => ({...layer, data: new Float32Array(capacity * 2)}));
+  const attributeLayers = (view.attributeLayers ?? []).map(layer => ({...layer, data: new Float32Array(capacity * 4)}));
+  const orco = view.orco ? new Float32Array(capacity * 3) : null;
   const indices = new Uint32Array(capacity),
     shared = new Map<string, number>();
   const groups: DrawArrays['groups'] = [];
   const normals = view.normals || view.cornerNormal ? new Float32Array(capacity * 3) : null;
   let count = 0,
     indexCount = 0;
-  const emit = (v: number, texture?: [number, number], normal?: Normal, sourceCorner?: number): number => {
+  const emit = (v: number, texture?: [number, number], normal?: Normal, sourceCorner?: number, face?: number): number => {
     const index = count++;
+    for (const layer of attributeLayers) layer.data.set(layer.read(v, sourceCorner, face), index * 4);
+    // attr_load_orco: the stored -1..1 orco, mapped to 0..1.
+    if (orco) for (let k = 0; k < 3; k++) orco[index * 3 + k] = view.orco![v * 3 + k]! * 0.5 + 0.5;
     sourceVertex[index] = v;
     view.co(v).toArray(positions, index * 3);
     if (texture) texcoords.set(texture, index * 2);
@@ -167,16 +224,18 @@ function drawCore(view: DrawView): Omit<DrawArrays, 'hash'> {
     if (sourceCorner !== undefined) for (const layer of uvLayers) layer.data.set(layer.read(sourceCorner), index * 2);
     return index;
   };
-  const corner = (c: number): number => {
+  const corner = (c: number, face: number): number => {
     const texture = uv?.(c);
     const normal: Normal | undefined = view.cornerNormal
       ? [view.cornerNormal[c * 3]!, view.cornerNormal[c * 3 + 1]!, view.cornerNormal[c * 3 + 2]!]
       : view.normals?.[c];
-    if (!mixed) return emit(cornerVerts[c]!, texture, normal, c);
-    const key = `${smooth[c] ? find(c) : c}${texture ? `:${texture[0]}:${texture[1]}` : ''}${normal ? `:n${normal.join(':')}` : ''}${uvLayers.map(layer => ':' + layer.read(c).join(':')).join('')}`;
+    if (!mixed) return emit(cornerVerts[c]!, texture, normal, c, face);
+    // A POINT layer's value is the vertex's, which the smooth fan already
+    // shares; a face or corner layer splits the fan where its values differ.
+    const key = `${smooth[c] ? find(c) : c}${texture ? `:${texture[0]}:${texture[1]}` : ''}${normal ? `:n${normal.join(':')}` : ''}${uvLayers.map(layer => ':' + layer.read(c).join(':')).join('')}${attributeLayers.map(layer => layer.domain === 'POINT' ? '' : ':' + Array.from(layer.read(cornerVerts[c]!, c, face)).join(':')).join('')}`;
     let index = shared.get(key);
     if (index === undefined) {
-      index = emit(cornerVerts[c]!, texture, normal, c);
+      index = emit(cornerVerts[c]!, texture, normal, c, face);
       shared.set(key, index);
     }
     return index;
@@ -188,7 +247,7 @@ function drawCore(view: DrawView): Omit<DrawArrays, 'hash'> {
     const points: THREE.Vector3[] = [];
     for (let j = 0; j < length; j++) points.push(view.co(cornerVerts[faceStart + j]!));
     for (const triangle of triangulatePolygon(points).triangles)
-      for (const c of triangle) indices[indexCount++] = corner(faceStart + c);
+      for (const c of triangle) indices[indexCount++] = corner(faceStart + c, i);
     const materialIndex = view.material(i),
       previous = groups.at(-1);
     if (previous?.materialIndex === materialIndex) previous.count += indexCount - start;
@@ -200,12 +259,21 @@ function drawCore(view: DrawView): Omit<DrawArrays, 'hash'> {
     normals: normals?.slice(0, count * 3) ?? null,
     uv: uv ? texcoords.slice(0, count * 2) : null,
     uvLayers: uvLayers.map(layer => ({name: layer.name, data: layer.data.slice(0, count * 2)})),
+    attributeLayers: attributeLayers.map(layer => ({name: layer.name, data: layer.data.slice(0, count * 4)})),
+    orco: orco ? orco.slice(0, count * 3) : null,
     indices: indices.slice(0, indexCount),
     sourceVertex: sourceVertex.slice(0, count),
     groups,
   };
 }
 
+/** The three attribute a graph reads Blender attribute `name` from: a GLSL
+ *  identifier spelled from the name's UTF-8 bytes, so every name has one and
+ *  no two names share one. */
+export function graphAttributeName(name: string): string {
+  return `blenderA_${Array.from(new TextEncoder().encode(name), b => b.toString(16).padStart(2, '0')).join('')}`;
+}
+
 export function geometryFromDrawArrays(
   arrays: Omit<DrawArrays, 'hash' | 'sourceVertex'> & { sourceVertex?: Uint32Array },
 ): THREE.BufferGeometry {
@@ -225,6 +293,13 @@ export function geometryFromDrawArrays(
     geometry.setAttribute(`uv${index + 1}`, new THREE.BufferAttribute(layer.data, 2));
   }
   geometry.userData['blenderUvChannels'] = channels;
+  for (const layer of arrays.attributeLayers ?? [])
+    geometry.setAttribute(graphAttributeName(layer.name), new THREE.BufferAttribute(layer.data, 4));
+  geometry.userData['blenderAttributes'] = (arrays.attributeLayers ?? []).map(layer => layer.name);
+  if (arrays.orco) {
+    geometry.setAttribute('blenderOrco', new THREE.BufferAttribute(arrays.orco, 3));
+    geometry.userData['blenderOrcoFromDoor'] = true;
+  }
   for (const group of arrays.groups)
     geometry.addGroup(group.start, group.count, group.materialIndex);
   if (arrays.normals) geometry.setAttribute('normal', new THREE.BufferAttribute(arrays.normals, 3));
@@ -288,6 +363,7 @@ export function drawArraysFromColumns(c: MeshColumns, hash: string): DrawArrays
     vertexCount: nv,
     normals: normalMesh ? customCornerNormals(normalMesh, customData) : null,
     cornerNormal: c.cornerNormal,
+    orco: c.orco,
     co: (i) => scratch.set(c.co[i * 3]!, c.co[i * 3 + 1]!, c.co[i * 3 + 2]!).clone(),
     starts: c.faceStart,
     cornerVerts: c.corner,
@@ -298,6 +374,7 @@ export function drawArraysFromColumns(c: MeshColumns, hash: string): DrawArrays
     uv: uvData ? (corner) => [uvData[corner * 2]!, uvData[corner * 2 + 1]!] : null,
     uvLayers: maps.map(layer => ({name: layer.name, read: (corner: number) =>
       [Number(layer.data[corner * 2]), Number(layer.data[corner * 2 + 1])] as [number, number]})),
+    attributeLayers: graphAttributeLayers(c.attributes, data => data as ArrayLike<number>),
   };
   if (map && ATTRIBUTE_LAYOUT.FLOAT2.size !== 2) throw new Error('FLOAT2 layout');
   return { ...drawCore(view), hash };
@@ -360,6 +437,9 @@ export function drawRuntimeGeometry(data: MeshData): THREE.BufferGeometry {
     uv: uv ? (corner) => uv[corner]! : null,
     uvLayers: maps.map(layer => ({name: layer.name, read: (corner: number) =>
       (layer.data as [number, number][])[corner]!})),
+    // The JSON door nests each element's components; the reader wants them flat.
+    attributeLayers: graphAttributeLayers(data.attributes ?? [],
+      values => (Array.from(values) as (number | number[])[]).flat()),
   };
   return geometryFromDrawArrays(drawCore(view));
 }

package/browser/three/blender-runtime-lighting.ts

@@ -35,6 +35,7 @@
  * faked with a substitute light the scene never declared.
  */
 import * as THREE from 'three';
+import {presenterChanged} from './blender-presenter-change';
 import { z } from 'zod';
 import type { GradientType } from './blender-gradient-texture';
 import { hasSkyTexture, primeSkyTexture, type SkyParameters } from './blender-sky';
@@ -76,6 +77,7 @@ function prepareRectArea(): Promise<void> {
   rectAreaPromise ??= import('three/examples/jsm/lights/RectAreaLightUniformsLib.js').then(
     ({ RectAreaLightUniformsLib }) => {
       RectAreaLightUniformsLib.init();
+      presenterChanged();
     },
   );
   return rectAreaPromise;
@@ -765,6 +767,7 @@ export class WorldBackground {
       // composing now would paint a sky nobody asked for over the current one.
       if (this.generation !== generation || this.applied?.scene !== scene) return;
       this.compose(scene, world, expression, camera);
+      presenterChanged();
     })();
     this.pending = pending;
     pendingWorld.add(pending);

package/browser/three/blender-runtime-view.ts

@@ -4,11 +4,13 @@
  */
 import * as THREE from 'three';
 import { z } from 'zod';
+import { onPresenterChange, presenterChanged } from './blender-presenter-change';
 import { bytesFromBase64 } from './blender-base64';
 import { ArmatureOverlay, armatureSchema } from './blender-runtime-armature';
 import { UNKNOWN_GEOMETRY, UNKNOWN_IMAGE } from './blender-runtime-frame';
 import {
   drawArraysFromColumns,
+  graphAttributeName,
   drawRuntimeGeometry,
   geometryFromDrawArrays,
 } from './blender-runtime-geometry';
@@ -25,6 +27,8 @@ import {
 import { fitModelDirectionalShadow, visibleShadowReceivers } from './blender-runtime-shadows';
 import { volumeMesh, volumeSchema } from './blender-runtime-volume';
 import { applyPhysicalMaterial, applyWorldExtinction, physicalMaterialSchema } from './blender-physical-material';
+import { prepareGraphGeometry, setMaterialGraph } from './blender-graph-material';
+import { type CompiledGraph, compileMaterialGraph, graphSeeThrough, materialGraphSchema } from './blender-node-graph';
 import {worldMedium, WorldVolumePass} from './blender-world-volume';
 import { BlenderTextureSamplers } from './blender-texture-samplers';
 import { WeightOverlay, weightsSchema } from './blender-runtime-weights';
@@ -107,6 +111,8 @@ const drawArraysSchema = z
     normals: z.instanceof(Float32Array).nullable(),
     uv: z.instanceof(Float32Array).nullable(),
     uvLayers: z.array(z.object({name: z.string(), data: z.instanceof(Float32Array)}).strict()).optional(),
+    attributeLayers: z.array(z.object({name: z.string(), data: z.instanceof(Float32Array)}).strict()).optional(),
+    orco: z.instanceof(Float32Array).nullable().optional(),
     indices: z.instanceof(Uint32Array),
     groups: z.array(
       z
@@ -163,6 +169,7 @@ const columnsSchema = z
   .object({
     co: z.instanceof(Float64Array),
     cornerNormal: z.instanceof(Float32Array).optional(),
+    orco: z.instanceof(Float32Array).optional(),
     faceStart: z.instanceof(Uint32Array),
     corner: z.instanceof(Uint32Array),
     cornerEdge: z.instanceof(Int32Array),
@@ -256,6 +263,7 @@ function loadPngTexture(png: Uint8Array): { texture: THREE.Texture; ready: Promi
       }
       texture.image = bitmap;
       texture.needsUpdate = true;
+      presenterChanged();
     })
     .finally(() => {
       pendingTextures.delete(decoding);
@@ -294,6 +302,47 @@ function rasterTexture(
   return texture;
 }
 
+/**
+ * A UDIM IMAGE AS A GRAPH SAMPLES IT: every tile a layer of one array texture
+ * (each at its layer's origin, the layer as large as the largest tile), and
+ * the tile map `blender_tile_lookup` reads -- row 0 each tile's layer (-1 for
+ * none), row 1 its offset and scale within the layer, Blender's
+ * `GPU_image_tiled` layout.
+ */
+function udimTextures(
+  name: string,
+  frame: NonNullable<z.infer<typeof rasterImageSchema>['tiles']>,
+  colorspace: 'sRGB' | 'data',
+): {tiles: THREE.DataArrayTexture; map: THREE.DataTexture; frame: typeof frame} {
+  if (frame.length === 0) throw new Error(`Runtime image ${name} is tiled with no tiles`);
+  const width = Math.max(...frame.map(t => t.width));
+  const height = Math.max(...frame.map(t => t.height));
+  const layers = new Uint8Array(width * height * 4 * frame.length);
+  const count = Math.max(...frame.map(t => t.number - 1001)) + 1;
+  const map = new Float32Array(count * 2 * 4);
+  for (let i = 0; i < count; i++) map[i * 4] = -1;
+  frame.forEach((tile, layer) => {
+    const rgba = tile.rgba ?? (tile.rgbaBase64 ? bytesFromBase64(tile.rgbaBase64) : undefined);
+    if (!rgba) throw new Error(`Runtime image ${name} tile ${tile.number} carries no raster`);
+    for (let row = 0; row < tile.height; row++)
+      layers.set(rgba.subarray(row * tile.width * 4, (row + 1) * tile.width * 4),
+        ((layer * height + row) * width) * 4);
+    const index = tile.number - 1001;
+    map[index * 4] = layer;
+    map.set([0, 0, tile.width / width, tile.height / height], (count + index) * 4);
+  });
+  const tiles = new THREE.DataArrayTexture(layers, width, height, frame.length);
+  tiles.colorSpace = colorspace === 'data' ? THREE.NoColorSpace : THREE.SRGBColorSpace;
+  tiles.magFilter = THREE.LinearFilter;
+  tiles.minFilter = THREE.LinearMipmapLinearFilter;
+  tiles.generateMipmaps = true;
+  tiles.needsUpdate = true;
+  const mapTexture = new THREE.DataTexture(map, count, 2, THREE.RGBAFormat, THREE.FloatType);
+  mapTexture.magFilter = mapTexture.minFilter = THREE.NearestFilter;
+  mapTexture.needsUpdate = true;
+  return {tiles, map: mapTexture, frame};
+}
+
 /** One image the frame carries in full, in the only two shapes it comes in.
  *
  * A RASTER states its size, because a `DataTexture` cannot be built without
@@ -312,6 +361,14 @@ const rasterImageSchema = z
     /** Blender's `colorspace_settings.name`, reduced to the two the sampler
      *  tells apart. Absent means sRGB. */
     colorspace: z.enum(['sRGB', 'data']).optional(),
+    /** A UDIM image's tiles, by tile number (the door's `write_image`). */
+    tiles: z.array(z.object({
+      number: z.number().int().min(1001),
+      width: z.number().int().positive(),
+      height: z.number().int().positive(),
+      rgba: z.instanceof(Uint8Array).optional(),
+      rgbaBase64: z.string().optional(),
+    }).strict()).optional(),
   })
   .strict();
 const pngImageSchema = z
@@ -360,6 +417,11 @@ const materialSchema = z
       .object({ color: z.tuple([scalar, scalar, scalar]), strength: scalar })
       .strict()
       .optional(),
+    /** The node graph driving a Principled BSDF's or Emission's linked
+     *  inputs (`session.py`'s `material_graph`), compiled by
+     *  `blender-node-graph.ts`. The constants above still apply to every
+     *  input the graph does not carry. */
+    graph: materialGraphSchema.optional(),
   })
   .strict();
 /** THE FRAME CONTRACT, and the reason it is exported: the C++ export door
@@ -410,6 +472,11 @@ export const frameSchema = z
           render_visible: z.boolean().default(true),
           selected: z.boolean(),
           parent: z.string().nullable(),
+          /** A manual texture space (`[location, size]`), which Generated
+           *  coordinates map through; absent means Blender's automatic one,
+           *  the evaluated bounds (`blender-graph-material.ts`'s orco). */
+          texspace: z.tuple([z.tuple([scalar, scalar, scalar]), z.tuple([scalar, scalar, scalar])]).optional(),
+          default_color: z.string().optional(),
         })
         .strict(),
     ),
@@ -505,6 +572,8 @@ export class BlenderRuntimeView {
       revision: number;
       png?: Uint8Array;
       ready?: Promise<void>;
+      /** A UDIM image's tiles as a graph samples them (`udimTextures`). */
+      udim?: {tiles: THREE.DataArrayTexture; map: THREE.DataTexture; frame: NonNullable<z.infer<typeof rasterImageSchema>['tiles']>};
     }
   >();
   /** Which image each material's `map` is currently pointing at. */
@@ -512,6 +581,24 @@ export class BlenderRuntimeView {
   /** Which runtime image each material's roughness map is, by material id. */
   private readonly roughnessTextureNames = new Map<string, string>();
   private readonly textureSamplers = new BlenderTextureSamplers();
+  /** Each material's graph image samplers, by sampler key. */
+  private readonly graphSamplers = new Map<string, Set<string>>();
+  /** A view built for one photograph: its graph programs compile before its
+   *  one draw rather than off it (`setMaterialGraph`'s `immediate`). */
+  private photograph = false;
+  /** Compiled graphs by their JSON: a frame re-sends every material. */
+  private readonly graphs = new Map<string, CompiledGraph>();
+
+  private compiledGraph(graph: z.infer<typeof materialGraphSchema>): CompiledGraph {
+    const text = JSON.stringify(graph);
+    let compiled = this.graphs.get(text);
+    if (!compiled) {
+      compiled = compileMaterialGraph(graph);
+      if (this.graphs.size > 256) this.graphs.clear();
+      this.graphs.set(text, compiled);
+    }
+    return compiled;
+  }
   private frame: Frame | null = null;
   private readonly retiredSessions = new Set<string>();
   private geometryBuilds = 0;
@@ -550,6 +637,18 @@ export class BlenderRuntimeView {
     };
   }
 
+  /** EVERY CHANGE TO WHAT THIS VIEW DRAWS: each applied frame, and each piece
+   *  of work that finishes after one (`blender-presenter-change.ts`). A stage
+   *  that subscribes may draw only when this fires. */
+  onChange(listener: () => void): () => void {
+    const stopFrames = this.subscribeFrames(listener);
+    const stopWork = onPresenterChange(listener);
+    return () => {
+      stopFrames();
+      stopWork();
+    };
+  }
+
   /** The Blender datablock NAME of a presented object, or null when this
    *  object is not one of the engine's (an editor helper, a light three.js
    *  parents under one). It is a lookup by IDENTITY, never by `object.name`:
@@ -987,6 +1086,12 @@ export class BlenderRuntimeView {
       if ('width' in data) {
         const rgba = data.rgba ?? (data.rgbaBase64 ? bytesFromBase64(data.rgbaBase64) : undefined);
         if (!rgba) throw new Error(`Runtime image ${name} carries no raster`);
+        const udim = data.tiles ? udimTextures(name, data.tiles, data.colorspace ?? 'sRGB') : undefined;
+        if (held?.udim) {
+          held.udim.tiles.dispose();
+          held.udim.map.dispose();
+          delete held.udim;
+        }
         // A REPAINT AT THE SAME SIZE IS AN UPLOAD, not a new texture: the
         // bytes go into the resident image and three re-uploads it, so every
         // material pointing at it keeps pointing at it. Native does exactly
@@ -997,6 +1102,7 @@ export class BlenderRuntimeView {
             image.data.set(rgba);
             held.texture.needsUpdate = true;
             held.revision = data.revision;
+            if (udim) held.udim = udim;
             continue;
           }
         }
@@ -1006,6 +1112,7 @@ export class BlenderRuntimeView {
           width: data.width,
           height: data.height,
           revision: data.revision,
+          ...(udim ? {udim} : {}),
         });
         continue;
       }
@@ -1016,6 +1123,8 @@ export class BlenderRuntimeView {
       const png = data.png ?? (data.pngBase64 ? bytesFromBase64(data.pngBase64) : undefined);
       if (!png) throw new Error(`Runtime image ${name} carries no bytes`);
       held?.texture.dispose();
+      held?.udim?.tiles.dispose();
+      held?.udim?.map.dispose();
       const { texture, ready } = loadPngTexture(png);
       texture.colorSpace = THREE.SRGBColorSpace;
       this.textures.set(name, {
@@ -1063,7 +1172,10 @@ export class BlenderRuntimeView {
       // carries no alpha on a texture, and Blender's Alpha is a separate
       // Principled socket.
       material.opacity = data.color[3];
-      const transparent = material.opacity < 1;
+      // A graph-driven Alpha, or a Transparent BSDF in a shader mix, is per
+      // pixel; the constant cannot say whether the surface is see-through, so
+      // such a graph is.
+      const transparent = material.opacity < 1 || (data.graph !== undefined && graphSeeThrough(data.graph));
       if (material.transparent !== transparent) {
         material.transparent = transparent;
         material.needsUpdate = true;
@@ -1172,6 +1284,37 @@ export class BlenderRuntimeView {
           material.needsUpdate = true;
         }
       }
+      // THE NODE GRAPH, when the session shipped one: compiled once per
+      // distinct graph, its images through the same cache and per-input
+      // sampler ownership as the maps above.
+      const graph = data.graph ? this.compiledGraph(data.graph) : null;
+      const graphSamplers = new Set<string>();
+      setMaterialGraph(material, graph, (image) => {
+        const held = this.textures.get(image.name);
+        if (!held)
+          throw new Error(
+            `${UNKNOWN_IMAGE}: the presenter does not hold runtime image ${image.name} ` +
+              `(revision ${image.revision})`,
+          );
+        if (image.tiled) {
+          if (!held.udim) throw new Error(`${UNKNOWN_IMAGE}: runtime image ${image.name} arrived without its UDIM tiles`);
+          return held.udim;
+        }
+        const key = `${id}:graph:${image.node}`;
+        graphSamplers.add(key);
+        const texture = this.textureSamplers.get(key, held.texture, image.extension, held.ready);
+        const filter = image.closest ? THREE.NearestFilter : THREE.LinearFilter;
+        const minFilter = image.closest ? THREE.NearestFilter
+          : image.mipmap ? THREE.LinearMipmapLinearFilter : THREE.LinearFilter;
+        if (texture.magFilter !== filter || texture.minFilter !== minFilter) {
+          texture.magFilter = filter;
+          texture.minFilter = minFilter;
+          texture.needsUpdate = true;
+        }
+        return texture;
+      }, this.photograph);
+      for (const key of this.graphSamplers.get(id) ?? []) if (!graphSamplers.has(key)) this.textureSamplers.delete(key);
+      this.graphSamplers.set(id, graphSamplers);
       this.materials.set(id, material);
     }
     for (const obj of next.objects) {
@@ -1201,12 +1344,17 @@ export class BlenderRuntimeView {
         object.matrix.premultiply(parent.invert());
       }
       object.matrix.decompose(object.position, object.quaternion, object.scale);
+      if (obj.texspace) object.userData['blenderTexspace'] = obj.texspace;
+      else delete object.userData['blenderTexspace'];
+      if (obj.default_color !== undefined) object.userData['blenderDefaultColor'] = obj.default_color;
+      else delete object.userData['blenderDefaultColor'];
       if (obj.mesh !== null) {
         const mesh = object as THREE.Mesh;
         mesh.geometry = this.meshes.get(obj.mesh)!.geometry;
         mesh.material = obj.materials.length
           ? obj.materials.map((id) => (id === null ? this.fallback : this.materials.get(id)!))
           : this.fallback;
+        prepareGraphGeometry(mesh);
       }
       if (obj.light) {
         // The light hangs on its object's own node, so the object's matrix
@@ -1247,6 +1395,8 @@ export class BlenderRuntimeView {
     for (const [id, material] of this.materials)
       if (!next.materials[id]) {
         for (const slot of ['normal', 'roughness', 'color']) this.textureSamplers.delete(`${id}:${slot}`);
+        for (const key of this.graphSamplers.get(id) ?? []) this.textureSamplers.delete(key);
+        this.graphSamplers.delete(id);
         material.dispose();
         this.materials.delete(id);
       }
@@ -1333,6 +1483,12 @@ export class BlenderRuntimeView {
           if (!data) throw new Error(`Blender capture mesh ${id} is missing UV layer ${name}`);
           return {name, data};
         }),
+        orco: geometry.userData['blenderOrcoFromDoor'] ? attribute('blenderOrco') : null,
+        attributeLayers: (geometry.userData['blenderAttributes'] as string[] | undefined ?? []).map(name => {
+          const data = attribute(graphAttributeName(name));
+          if (!data) throw new Error(`Blender capture mesh ${id} is missing attribute ${name}`);
+          return {name, data};
+        }),
         indices: index
           ? new Uint32Array(index.array)
           : Uint32Array.from({ length: positions.length / 3 }, (_, i) => i),
@@ -1347,9 +1503,15 @@ export class BlenderRuntimeView {
       frame.volumes[id] = volumeSchema.parse(JSON.parse(signature));
     const images = new Set(
       Object.values(frame.materials).flatMap((material) =>
-        [material.texture?.image.name, material.roughness_texture?.image.name, material.normal_texture?.image.name].filter(
-          (name): name is string => name !== undefined,
-        ),
+        [
+          material.texture?.image.name,
+          material.roughness_texture?.image.name,
+          material.normal_texture?.image.name,
+          // The images a material's node graph samples.
+          ...Object.values(material.graph?.nodes ?? {}).map(
+            (node) => (node.props['image'] as { name?: string } | null | undefined)?.name,
+          ),
+        ].filter((name): name is string => name !== undefined),
       ),
     );
     for (const name of images) {
@@ -1367,11 +1529,13 @@ export class BlenderRuntimeView {
           height: held.height,
           rgba: data.slice(),
           colorspace: held.texture.colorSpace === THREE.NoColorSpace ? 'data' : 'sRGB',
+          ...(held.udim ? {tiles: held.udim.frame} : {}),
         };
       }
     }
     const effect = this.createWorldVolumePass();
     const detached = new BlenderRuntimeView();
+    detached.photograph = true;
     let disposed = false;
     const dispose = () => {
       if (disposed) return;
@@ -1461,7 +1625,11 @@ export class BlenderRuntimeView {
     // The pictures go with the session that sent them: the cache OWNS every
     // texture in it (a material only points at one), so this is the one place
     // they are disposed, beside the meshes for the same reason.
-    for (const { texture } of this.textures.values()) texture.dispose();
+    for (const { texture, udim } of this.textures.values()) {
+      texture.dispose();
+      udim?.tiles.dispose();
+      udim?.map.dispose();
+    }
     this.textures.clear();
     this.textureNames.clear();
     this.roughnessTextureNames.clear();