@volter/blender-engine 0.1.94 → 0.1.95

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

@@ -24,6 +24,7 @@ interface Binding {
   ramps: THREE.DataTexture[];
   /** Named UV layer to the channel the current draw's geometry holds it in. */
   channels: Record<string, number>;
+  palette?: {indices: Int32Array; sources: readonly THREE.MeshPhysicalMaterial[]};
 }
 const bindings = new WeakMap<THREE.MeshPhysicalMaterial, Binding>();
 /** Graph structures whose program the GPU refused. A material whose graph is
@@ -35,6 +36,59 @@ export function materialGraph(material: THREE.MeshPhysicalMaterial): CompiledGra
   return bindings.get(material)?.compiled ?? null;
 }
 
+/** Only identical graph programs can share an ordered draw. The originals
+ * keep ownership of textures and ramp tables; their live uniform objects are
+ * borrowed, so value edits do not turn into baked shader constants. */
+function compatiblePaletteGraphs(sources: readonly THREE.MeshPhysicalMaterial[]): CompiledGraph | null {
+  if (sources.length !== 2 || sources.some(source => pendings.has(source))) return null;
+  const graphs = sources.map(source => bindings.get(source)?.compiled);
+  const graph = graphs[0];
+  if (!graph || failed.has(graph.key) || graphs.some(other => !other || other.key !== graph.key ||
+      other.declarations !== graph.declarations || other.library !== graph.library ||
+      JSON.stringify([other.uvs, other.attributes, other.outputs]) !== JSON.stringify([graph.uvs, graph.attributes, graph.outputs]))) return null;
+  // Leave room for the physical material's environment and lighting samplers.
+  if (sources.reduce((n, source) => n + graph.images.reduce((n, image) => n + (image.tiled ? 2 : 1), 0) +
+      graph.ramps.length + [source.map, source.normalMap, source.roughnessMap].filter(Boolean).length, 0) > 8) return null;
+  return graph;
+}
+
+export function paletteGraphReady(source: THREE.MeshPhysicalMaterial): boolean {
+  const graph = bindings.get(source)?.compiled;
+  return !!graph && !pendings.has(source) && !failed.has(graph.key);
+}
+
+export function paletteGraphs(sources: readonly THREE.MeshPhysicalMaterial[]): CompiledGraph | null {
+  const graph = compatiblePaletteGraphs(sources);
+  if (!graph) return null;
+  const rename = (text: string, index: number) => text.replace(/\b(bg\w+|blenderGraph)\b/g, name => `bp${index}_${name}`);
+  const outputs = Object.values(graph.outputs).map(output => `${output.type} ${output.global};`);
+  if (graph.closure) outputs.push('float bgClosureP;', 'vec3 bgClosureE;', 'float bgClosureT;');
+  const names = [...Object.values(graph.outputs).map(output => output.global), ...(graph.closure ? ['bgClosureP', 'bgClosureE', 'bgClosureT'] : [])];
+  const program = [rename(graph.program, 0), rename(graph.program, 1), ...outputs,
+    // Evaluate both graphs before selecting. Derivatives and implicit texture
+    // LOD must never occur inside a potentially divergent fragment branch.
+    `void blenderGraph() { bp0_blenderGraph(); bp1_blenderGraph(); ${names.map(name =>
+      `${name} = vBlenderPaletteIndex == 0 ? bp0_${name} : bp1_${name};`).join(' ')} }`].join('\n');
+  return {...graph, key: `blender-palette-v1:${graph.key}`, program,
+    declarations: `${graph.library}\n${program}`, images: [], ramps: [], uniforms: new Map()};
+}
+
+export function bindPaletteGraph(material: THREE.MeshPhysicalMaterial, compiled: CompiledGraph,
+  sources: readonly THREE.MeshPhysicalMaterial[], indices: Int32Array, geometry: THREE.BufferGeometry): boolean {
+  if (!compatiblePaletteGraphs(sources)) return false;
+  const values: Record<string, THREE.IUniform> = {blenderPaletteIndices: {value: indices}};
+  for (let index = 0; index < sources.length; index++) {
+    const source = sources[index]!;
+    for (const [name, uniform] of Object.entries(bindings.get(source)!.uniforms)) values[`bp${index}_${name}`] = uniform;
+    for (const name of ['map', 'normalMap', 'roughnessMap'] as const) {
+      if (source[name]) values[`bp${index}_${name}`] = {value: source[name]};
+    }
+  }
+  bindings.set(material, {compiled, uniforms: values, ramps: [], channels: channelsFor(compiled, geometry), palette: {indices, sources}});
+  material.needsUpdate = true;
+  return true;
+}
+
 type ImageTexture = THREE.Texture | {tiles: THREE.Texture; map: THREE.Texture} | null;
 
 /**
@@ -395,6 +449,22 @@ ${compiled.attributes.map(n => `${attributeVarying(n)} = ${graphAttributeName(n)
 ${compiled.uvs.map(n => `${uvVarying(n)} = ${attribute(channels[n] ?? 0)};`).join('\n')}
 #include <project_vertex>`,
   );
+  if (binding.palette) {
+    shader.vertexShader = `uniform int blenderPaletteIndices[64];\nflat varying int vBlenderPaletteIndex;\n${shader.vertexShader}`
+      .replace('#include <project_vertex>', 'vBlenderPaletteIndex = blenderPaletteIndices[int(getIndirectIndex(gl_DrawID))];\n#include <project_vertex>');
+    shader.fragmentShader = `flat varying int vBlenderPaletteIndex;\n${shader.fragmentShader}`;
+    for (const [name, uv, clip] of [['map', 'vMapUv', 'blenderMapClip'], ['normalMap', 'vNormalMapUv', 'blenderNormalClip'],
+      ['roughnessMap', 'vRoughnessMapUv', 'blenderRoughnessClip']] as const) {
+      if (!material[name]) continue;
+      shader.fragmentShader = `uniform sampler2D bp0_${name}, bp1_${name};\n${shader.fragmentShader}`
+        .replaceAll(`blenderImageSample(${name}, ${uv}, ${clip})`, `blenderPalette_${name}(${uv}, ${clip})`)
+        .replace('void main() {', `vec4 blenderPalette_${name}(vec2 uv, bool clipImage) {
+          vec4 first = blenderImageSample(bp0_${name}, uv, clipImage);
+          vec4 second = blenderImageSample(bp1_${name}, uv, clipImage);
+          return vBlenderPaletteIndex == 0 ? first : second;
+        }\nvoid main() {`);
+    }
+  }
   const out = (name: string) => compiled.outputs[name]?.global;
   // [chunk, line, whether the line goes BEFORE the chunk]
   const fragment: [string, string, boolean][] = [];

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

@@ -0,0 +1,65 @@
+import * as THREE from 'three';
+import {materialGraph, paletteGraphReady, paletteGraphs} from './blender-graph-material';
+import {physicalPaletteState, samePhysicalPaletteState} from './blender-physical-material';
+import type {OrderedPalette} from './blender-ordered-batches';
+
+type Snapshot = {source: THREE.MeshPhysicalMaterial; state: NonNullable<ReturnType<typeof physicalPaletteState>>;
+  compatible: NonNullable<ReturnType<typeof physicalPaletteState>>};
+
+/** Pair only complete, equal shader/render states. Each frame observes shared
+ * sources once; member meshes keep their authored materials. Any change drops
+ * the disposable packed families before their old identities are released. */
+export class BlenderMaterialPalettes {
+  private snapshots: Snapshot[] = [];
+  private readonly palettes = new Map<THREE.Material, OrderedPalette>();
+  private readonly owned: OrderedPalette[] = [];
+
+  prepare(materials: Iterable<THREE.Material>, releaseDraws: () => void): boolean {
+    const snapshots: Snapshot[] = [];
+    for (const source of new Set(materials)) {
+      if (!(source instanceof THREE.MeshPhysicalMaterial) || !source.visible || !source.transparent ||
+          source.transmission > 0 || (source.side === THREE.DoubleSide && !source.forceSinglePass) ||
+          !paletteGraphReady(source)) continue;
+      const state = physicalPaletteState(source, true);
+      const compatible = physicalPaletteState(source);
+      const graph = materialGraph(source);
+      if (!state || !compatible || !graph) continue;
+      state.push(graph.key, graph.declarations);
+      snapshots.push({source, state, compatible});
+    }
+    snapshots.sort((a, b) => a.source.uuid.localeCompare(b.source.uuid));
+    if (snapshots.length === this.snapshots.length && snapshots.every((snapshot, index) =>
+      snapshot.source === this.snapshots[index]!.source && samePhysicalPaletteState(snapshot.state, this.snapshots[index]!.state))) return false;
+    releaseDraws();
+    this.clear();
+    this.snapshots = snapshots;
+    const paired = new Set<THREE.Material>();
+    for (let first = 0; first < snapshots.length && this.owned.length < 16; first++) {
+      const a = snapshots[first]!;
+      if (paired.has(a.source)) continue;
+      for (let second = first + 1; second < snapshots.length; second++) {
+        const b = snapshots[second]!;
+        if (paired.has(b.source) || !samePhysicalPaletteState(a.compatible, b.compatible)) continue;
+        const sources = [a.source, b.source];
+        const compiled = paletteGraphs(sources);
+        if (!compiled) continue;
+        const palette: OrderedPalette = {identity: new THREE.Material(), sources, compiled};
+        this.owned.push(palette);
+        for (const source of sources) { paired.add(source); this.palettes.set(source, palette); }
+        break;
+      }
+    }
+    return true;
+  }
+
+  get(source: THREE.Material): OrderedPalette | undefined { return this.palettes.get(source); }
+
+  clear(): void {
+    for (const palette of this.owned) palette.identity.dispose();
+    this.owned.length = 0;
+    this.palettes.clear();
+    this.snapshots = [];
+  }
+
+  inspect() { return {pairs: this.owned.length, limit: 16}; }
+}

package/browser/three/blender-node-graph.ts

@@ -129,6 +129,11 @@ export interface CompiledGraph {
   /** Declarations: the prelude, the library files in dependency order, the
    *  uniforms, the graph function. Goes before `main`. */
   readonly declarations: string;
+  /** Shared library and graph-local declarations, kept separately so an
+   * ordered material palette can namespace graph inputs without copying the
+   * coordinate/library globals. Their join is exactly `declarations`. */
+  readonly library: string;
+  readonly program: string;
   /** Uniform name to value; refreshed on every frame without recompiling. */
   readonly uniforms: ReadonlyMap<string, number | readonly number[]>;
   readonly images: readonly GraphImage[];
@@ -935,10 +940,12 @@ class Compiler {
     };
     for (const file of this.s.files) visit(file);
     const graphBody = `void blenderGraph() {\n  blender_init_globals();\n  ${[...this.lines, ...assignments].join('\n  ')}\n}`;
-    const declarations = [
+    const library = [
       BLENDER_NODE_GLSL_PRELUDE,
       shakeLibrary(EEVEE_GLOBALS + ordered.map(f => BLENDER_NODE_GLSL[f]!.code).join('\n') + '\n' + COORDINATES,
         [...this.s.functions, graphBody].join('\n')),
+    ].join('\n');
+    const program = [
       ...[...this.s.uniformTypes].map(([n, t]) => `uniform ${t} ${n};`),
       ...this.images.map(i => i.tiled
         ? `uniform highp sampler2DArray ${i.uniform};\nuniform highp sampler2D ${i.uniform}Map;`
@@ -951,7 +958,9 @@ class Compiler {
     ].join('\n');
     return {
       key: JSON.stringify([this.graph.surface, this.s.structure, [...this.s.uvs].sort()]),
-      declarations,
+      declarations: `${library}\n${program}`,
+      library,
+      program,
       uniforms: this.uniforms,
       images: this.images,
       ramps: this.ramps,

package/browser/three/blender-ordered-batches.ts

@@ -1,12 +1,19 @@
 import * as THREE from 'three';
+import type {CompiledGraph} from './blender-node-graph';
+import {physicalPaletteMaterial} from './blender-physical-material';
+import {presenterChanged} from './blender-presenter-change';
 
 export const ORDERED_BATCH_CAPACITY = 64;
 const FAMILY_BYTES = 4 * 1024 * 1024;
 const CACHE_BYTES = 32 * 1024 * 1024;
 const MAX_DRAWS = 1024;
 type Shape = {geometry: THREE.BufferGeometry; stamp: string; bytes: number};
+export type OrderedPalette = {identity: THREE.Material; sources: readonly THREE.MeshPhysicalMaterial[]; compiled: CompiledGraph};
+type Compilation = {material: THREE.MeshPhysicalMaterial; ready: boolean; refused: boolean; pending: boolean; program: unknown};
 type Family = {material: THREE.Material; shapes: Map<number, Shape>; template: THREE.BatchedMesh | null;
-  ids: Map<number, number>; draws: THREE.BatchedMesh[]; dirty: boolean; bytes: number; reservedBytes: number; refused: boolean};
+  ids: Map<number, number>; draws: THREE.BatchedMesh[]; dirty: boolean; bytes: number; reservedBytes: number; refused: boolean;
+  palette: OrderedPalette | undefined; compilations: Map<THREE.WebGLRenderer, Compilation>;
+  drawMaterials: Map<THREE.BatchedMesh, {material: THREE.MeshPhysicalMaterial; indices: Int32Array}>};
 
 /** Immutable packed attributes are shared between ordered draw runs. Only the
  * matrix/indirection textures and command lists belong to an individual run.
@@ -18,11 +25,14 @@ export class BlenderOrderedBatches {
   private bytes = 0;
   private drawCount = 0;
   private created = 0;
+  private compiling = 0;
   pending = false;
+  generation = 0;
 
   begin(): void { this.created = 0; this.pending = false; this.registrations.clear(); }
+  beginPaletteFrame(): void { this.compiling = 0; }
 
-  register(geometry: THREE.BufferGeometry, material: THREE.Material, order: number): string | null {
+  register(geometry: THREE.BufferGeometry, material: THREE.Material, order: number, palette?: OrderedPalette): string | null {
     const registration = `${geometry.id}:${material.uuid}:${order}`;
     if (this.registrations.has(registration)) return this.registrations.get(registration)!;
     this.registrations.set(registration, null);
@@ -56,7 +66,7 @@ export class BlenderOrderedBatches {
     let family = this.families.get(key);
     if (!family) {
       family = {material, shapes: new Map(), template: null, ids: new Map(), draws: [], dirty: true,
-        bytes: 0, reservedBytes: 0, refused: false};
+        bytes: 0, reservedBytes: 0, refused: false, palette, compilations: new Map(), drawMaterials: new Map()};
       this.families.set(key, family);
     }
     const stamp = JSON.stringify(versions);
@@ -105,12 +115,67 @@ export class BlenderOrderedBatches {
     }
   }
 
-  available(key: string): boolean { return !!this.families.get(key)?.template; }
+  /** Compile before replacing a single canonical draw, with this renderer's
+   * context and actual scene lighting. Each frame starts at most two programs.
+   * The proxy borrows packed geometry and owns only its matrix textures. */
+  compilePalettes(renderer: THREE.WebGLRenderer, camera: THREE.Camera, scene: THREE.Scene): void {
+    if (renderer.getContext().isContextLost()) return;
+    for (const family of this.families.values()) {
+      const {template, palette} = family;
+      if (!template || !palette) continue;
+      let compilation = family.compilations.get(renderer);
+      if (compilation?.ready && (renderer.properties.get(compilation.material) as {currentProgram?: unknown}).currentProgram !== compilation.program) {
+        compilation.ready = false; // Context restoration clears renderer properties.
+        this.generation++;
+      }
+      if (compilation?.ready || compilation?.pending || compilation?.refused) continue;
+      if (this.compiling >= 2) { this.pending = true; continue; }
+      if (!compilation) {
+        const material = physicalPaletteMaterial(palette.compiled, palette.sources, new Int32Array(ORDERED_BATCH_CAPACITY), template.geometry);
+        if (!material) continue;
+        compilation = {material, ready: false, refused: false, pending: false, program: null};
+        family.compilations.set(renderer, compilation);
+      }
+      const held = compilation;
+      held.pending = true;
+      held.material.needsUpdate = true;
+      const proxy = new THREE.BatchedMesh(1, 0, 0, held.material);
+      proxy.geometry.dispose();
+      proxy.geometry = template.geometry;
+      Object.defineProperty(proxy, 'colorTexture', {value: null});
+      this.compiling++;
+      const settle = (resolved: boolean) => {
+        proxy.geometry = new THREE.BufferGeometry();
+        proxy.dispose();
+        if (family.template !== template || family.compilations.get(renderer) !== held) {
+          held.material.dispose(); return;
+        }
+        held.pending = false;
+        // compileAsync signals completion, including a refused program. Check
+        // the actual link result; never let a failed palette hide originals.
+        const program = (renderer.properties.get(held.material) as {currentProgram?: {program?: WebGLProgram}}).currentProgram;
+        const gl = renderer.getContext();
+        held.ready = resolved && !gl.isContextLost() && !!program?.program && gl.getProgramParameter(program.program, gl.LINK_STATUS) === true;
+        held.program = program;
+        held.refused = !held.ready && !gl.isContextLost();
+        this.generation++;
+        if (held.refused) console.warn('Blender ordered material palette did not link; canonical draws retained.');
+        presenterChanged();
+      };
+      try { renderer.compileAsync(proxy, camera, scene).then(() => settle(true), () => settle(false)); }
+      catch { settle(false); }
+    }
+  }
+
+  available(key: string, renderer?: THREE.WebGLRenderer): boolean {
+    const family = this.families.get(key);
+    return !!family?.template && (!family.palette || (!!renderer && family.compilations.get(renderer)?.ready === true));
+  }
 
-  get(key: string, index: number): THREE.BatchedMesh | null {
+  get(key: string, index: number, renderer?: THREE.WebGLRenderer): THREE.BatchedMesh | null {
     const family = this.families.get(key)!;
     const template = family.template;
-    if (!template) return null;
+    if (!template || !this.available(key, renderer)) return null;
     let draw = family.draws[index];
     if (!draw) {
       if (this.drawCount >= MAX_DRAWS) return null;
@@ -133,6 +198,14 @@ export class BlenderOrderedBatches {
         draw.addInstance(firstId);
         draw.setVisibleAt(i, false);
       }
+      if (family.palette) {
+        const indices = new Int32Array(ORDERED_BATCH_CAPACITY);
+        const material = physicalPaletteMaterial(family.palette.compiled, family.palette.sources, indices, draw.geometry);
+        if (!material) { for (const name of Object.keys(draw.geometry.attributes)) draw.geometry.deleteAttribute(name);
+          draw.geometry.setIndex(null); draw.dispose(); return null; }
+        draw.material = material;
+        family.drawMaterials.set(draw, {material, indices});
+      }
       family.draws.push(draw);
       this.created++;
       this.drawCount++;
@@ -142,10 +215,26 @@ export class BlenderOrderedBatches {
 
   geometryId(key: string, geometry: THREE.BufferGeometry): number { return this.families.get(key)!.ids.get(geometry.id)!; }
 
+  setMaterialAt(key: string, draw: THREE.BatchedMesh, index: number, source: THREE.Material): void {
+    const family = this.families.get(key)!;
+    const held = family.drawMaterials.get(draw);
+    if (held) held.indices[index] = family.palette!.sources.indexOf(source as THREE.MeshPhysicalMaterial);
+  }
+
+  isPalette(key: string): boolean { return !!this.families.get(key)?.palette; }
+
   inspect() { return {bytes: this.bytes, draws: this.drawCount, pending: this.pending,
+    paletteFamilies: [...this.families.values()].filter(f => !!f.palette).length,
+    paletteReady: [...this.families.values()].filter(f => [...f.compilations.values()].some(c => c.ready)).length,
+    paletteRefused: [...this.families.values()].filter(f => [...f.compilations.values()].some(c => c.refused)).length,
     refusedFamilies: [...this.families.values()].filter(f => f.refused).length}; }
 
   private release(family: Family): void {
+    this.generation++;
+    for (const compilation of family.compilations.values()) if (!compilation.pending) compilation.material.dispose();
+    family.compilations.clear();
+    for (const {material} of family.drawMaterials.values()) material.dispose();
+    family.drawMaterials.clear();
     for (const draw of family.draws) {
       draw.removeFromParent();
       // BatchedMesh.dispose owns its geometry. Detach shared buffer attributes

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

@@ -4,7 +4,8 @@
  * that MeshPhysicalMaterial does not expose as properties. */
 import * as THREE from 'three';
 import {z} from 'zod';
-import {applyGraphShader, bindGraphDraw, borrowGraphDrawBinding, graphProgramKey, graphUvChannels, setGraphViewport} from './blender-graph-material';
+import {applyGraphShader, bindGraphDraw, bindPaletteGraph, borrowGraphDrawBinding, graphProgramKey, graphUvChannels, setGraphViewport} from './blender-graph-material';
+import type {CompiledGraph} from './blender-node-graph';
 import {bindNamedUvChannels} from './blender-texture-samplers';
 
 const scalar = z.number().finite();
@@ -66,6 +67,77 @@ function graphShadow(material: THREE.MeshPhysicalMaterial): THREE.MeshPhysicalMa
   return shadow;
 }
 
+type PaletteState = (string | number | boolean | null)[];
+const identities = new WeakMap<object, number>();
+let nextIdentity = 0;
+const ignoredMaterial = new Set(['id', 'uuid', 'name', 'userData', 'version', '_listeners',
+  'onBeforeRender', 'onBeforeCompile', 'customProgramCacheKey']);
+const ignoredTexture = new Set(['id', 'uuid', 'name', 'source', 'mipmaps', 'version', '_listeners', 'userData']);
+const paletteMaps = new Set(['map', 'normalMap', 'roughnessMap']);
+const identity = (object: object): number => {
+  let id = identities.get(object);
+  if (id === undefined) { id = ++nextIdentity; identities.set(object, id); }
+  return id;
+};
+
+/** An exact, small snapshot of shader/render state, including the engine's
+ * private physical uniforms. No toJSON/image readback, lossy hash, or version
+ * assumption: direct property edits must invalidate a palette too. Only the
+ * three sampled image identities may differ, with identical sampler/UV state. */
+export function physicalPaletteState(material: THREE.MeshPhysicalMaterial, imageIdentities = false): PaletteState | null {
+  const held = uniforms.get(material);
+  if (!held || !materialDrawHooksSupported(material)) return null;
+  const state: PaletteState = [];
+  const append = (value: unknown, depth = 0): void => {
+    if (value === null || typeof value === 'number' || typeof value === 'string' || typeof value === 'boolean') state.push(value);
+    else if (value === undefined) state.push('undefined');
+    else if (typeof value === 'object' || typeof value === 'function') {
+      if (depth > 8) { state.push('reference', identity(value)); return; }
+      if (Array.isArray(value)) { state.push('array', value.length); for (const entry of value) append(entry, depth + 1); }
+      else if (Object.getPrototypeOf(value) === Object.prototype || value instanceof THREE.Color ||
+          value instanceof THREE.Vector2 || value instanceof THREE.Vector3 || value instanceof THREE.Vector4 ||
+          value instanceof THREE.Matrix3 || value instanceof THREE.Matrix4 || value instanceof THREE.Plane) {
+        state.push('values');
+        for (const key of Object.keys(value).sort()) { state.push(key); append((value as Record<string, unknown>)[key], depth + 1); }
+      } else state.push('reference', identity(value));
+    }
+  };
+  for (const key of Object.keys(material).sort()) {
+    if (ignoredMaterial.has(key)) continue;
+    state.push(key);
+    const value = (material as unknown as Record<string, unknown>)[key];
+    if (paletteMaps.has(key) && value instanceof THREE.Texture) {
+      // Special sampler kinds require different GLSL declarations/conversions.
+      if (value.constructor !== THREE.Texture) return null;
+      if (value.matrixAutoUpdate) value.updateMatrix();
+      state.push('sampled-image');
+      if (imageIdentities) state.push(value.uuid);
+      for (const name of Object.keys(value).sort()) {
+        if (ignoredTexture.has(name)) continue;
+        state.push(name); append((value as unknown as Record<string, unknown>)[name]);
+      }
+      append(value.userData['blenderUvName'] ?? '');
+    } else append(value);
+  }
+  for (const [name, value] of Object.entries(held)) { state.push(name); append(value.value); }
+  return state;
+}
+
+export function samePhysicalPaletteState(first: PaletteState, second: PaletteState): boolean {
+  return first.length === second.length && first.every((value, index) => value === second[index]);
+}
+
+/** A palette draw owns its material/uniform index array, borrowing all image
+ * and ramp storage. It never substitutes a source material's hooks. */
+export function physicalPaletteMaterial(compiled: CompiledGraph, sources: readonly THREE.MeshPhysicalMaterial[],
+  indices: Int32Array, geometry: THREE.BufferGeometry): THREE.MeshPhysicalMaterial | null {
+  for (const source of sources) bindNamedUvChannels(source, geometry);
+  const copy = graphShadow(sources[0]!);
+  if (bindPaletteGraph(copy, compiled, sources, indices, geometry)) return copy;
+  copy.dispose();
+  return null;
+}
+
 /** Copy physical values into an independently cached draw form. Textures and
  * graph uniform values remain borrowed from the authoritative source material. */
 export function syncPhysicalDrawMaterial(source: THREE.Material, target?: THREE.MeshPhysicalMaterial): THREE.MeshPhysicalMaterial | null {

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

@@ -1253,7 +1253,7 @@ export class BlenderRuntimeView {
 
   /** Before the renderer uploads attributes/builds its queues, for this area's
    * actual camera. Transparent instance runs are camera-order dependent. */
-  prepareDraw(camera: THREE.Camera, options?: {interactive: boolean; height: number; multiDraw?: boolean}): () => void {
+  prepareDraw(camera: THREE.Camera, options?: {interactive: boolean; height: number; multiDraw?: boolean; renderer?: THREE.WebGLRenderer}): () => void {
     try {
       const start = performance.now();
       this.instances.prepareDraw(camera);
@@ -1269,7 +1269,7 @@ export class BlenderRuntimeView {
       const motionDone = performance.now();
       this.materialRanges.prepare();
       const rangesDone = performance.now();
-      this.transparentInstances.prepare(camera, options?.multiDraw === true);
+      this.transparentInstances.prepare(camera, options?.multiDraw === true, options?.renderer);
       const timing = {opaqueMs: opaqueDone - start, motionMs: motionDone - opaqueDone,
         rangesMs: rangesDone - motionDone, transparentMs: performance.now() - rangesDone};
       this.drawPreparation.last = timing;

package/browser/three/blender-transparent-instances.ts

@@ -1,6 +1,7 @@
 import * as THREE from 'three';
 import {BlenderOrderedBatches, ORDERED_BATCH_CAPACITY} from './blender-ordered-batches';
 import {BlenderDrawMaterials} from './blender-draw-materials';
+import {BlenderMaterialPalettes} from './blender-material-palettes';
 import {presenterChanged} from './blender-presenter-change';
 import {graphDrawAttributes} from './blender-graph-material';
 import {materialDrawHooksSupported} from './blender-physical-material';
@@ -8,7 +9,7 @@ import {instanceMatrixSupported, instanceObjectShown, instanceObjectHooksSupport
 
 const CAPACITY = ORDERED_BATCH_CAPACITY;
 type Entry = {mesh: THREE.Mesh; material: THREE.Material | null; key: string | null; batchKey: string | null; groupOrder: number; z: number; centre: THREE.Vector3};
-type Draw = {mesh: THREE.InstancedMesh | THREE.BatchedMesh; members: THREE.Mesh[]};
+type Draw = {mesh: THREE.InstancedMesh | THREE.BatchedMesh; members: THREE.Mesh[]; palette: boolean};
 
 function groupOrder(mesh: THREE.Object3D): number {
   for (let parent = mesh.parent; parent; parent = parent.parent)
@@ -25,6 +26,10 @@ export class BlenderTransparentInstances {
   private objects: THREE.Mesh[] = [];
   private readonly drawMaterials = new BlenderDrawMaterials();
   private readonly ordered = new BlenderOrderedBatches();
+  private readonly palettes = new BlenderMaterialPalettes();
+  private readonly sourceMaterials = new Set<THREE.Material>();
+  private plannedGeneration = -1;
+  private renderer: THREE.WebGLRenderer | undefined;
   private readonly mixedDraws = new Map<THREE.BatchedMesh, Draw>();
   private multiDraw = false;
   private readonly pools = new Map<string, Draw[]>();
@@ -52,23 +57,36 @@ export class BlenderTransparentInstances {
     this.objects = [...objects].filter((object): object is THREE.Mesh => (object as THREE.Mesh).isMesh === true);
   }
 
-  prepare(camera: THREE.Camera, multiDraw = false): void {
+  prepare(camera: THREE.Camera, multiDraw = false, renderer?: THREE.WebGLRenderer): void {
     this.finishDraw();
     this.drawMaterials.begin();
     if (!this.objects.length) return;
     camera.updateMatrixWorld();
     this.projection.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
-    const capabilityChanged = this.multiDraw !== multiDraw;
+    let scene: THREE.Object3D = this.root;
+    while (scene.parent) scene = scene.parent;
+    const targetScene = scene instanceof THREE.Scene ? scene : null;
+    const capabilityChanged = this.multiDraw !== multiDraw || this.renderer !== renderer;
+    this.renderer = renderer;
     this.multiDraw = multiDraw;
     const inputsChanged = this.planChanged(camera);
-    if (!inputsChanged && !capabilityChanged && !this.ordered.pending) {
+    if (inputsChanged) {
+      this.sourceMaterials.clear();
+      for (const mesh of this.objects) for (const material of Array.isArray(mesh.material) ? mesh.material : [mesh.material]) this.sourceMaterials.add(material);
+    }
+    const palettesChanged = this.palettes.prepare(this.sourceMaterials, () => {
+      this.ordered.clear(); this.mixedDraws.clear(); this.planned.length = 0;
+    });
+    this.ordered.beginPaletteFrame();
+    if (renderer && targetScene) this.ordered.compilePalettes(renderer, camera, targetScene);
+    if (!inputsChanged && !capabilityChanged && !palettesChanged && this.plannedGeneration === this.ordered.generation && !this.ordered.pending) {
       // The draw plan is a disposable presentation, not evaluated scene data.
       // Reuse only after exact comparison of every input to culling/ordering;
       // a camera move, drag, visibility or material change rebuilds it below.
       for (const draw of this.planned) {
         draw.mesh.visible = true;
         const source = draw.members[0]!.material;
-        draw.mesh.material = this.drawMaterials.get(Array.isArray(source) ? source[0]! : source, draw.mesh);
+        if (!draw.palette) draw.mesh.material = this.drawMaterials.get(Array.isArray(source) ? source[0]! : source, draw.mesh);
         for (const member of draw.members) {
           member.layers.disable(0);
           this.hidden.push(member);
@@ -147,13 +165,15 @@ export class BlenderTransparentInstances {
           : 'geometryLayersOrTransform';
         this.excluded[reason] = (this.excluded[reason] ?? 0) + 1;
       }
-      const batchKey = multiDraw && key && material ? this.ordered.register(mesh.geometry, material, mesh.renderOrder) : null;
+      const palette = renderer && targetScene && material ? this.palettes.get(material) : undefined;
+      const batchKey = multiDraw && key && material ? this.ordered.register(mesh.geometry, palette?.identity ?? material, mesh.renderOrder, palette) : null;
       entries.push({mesh, material, key, batchKey, groupOrder: order, z, centre});
     }
     this.ordered.pack();
+    if (renderer && targetScene) this.ordered.compilePalettes(renderer, camera, targetScene);
     // A family may exceed the bounded cache. Retain its original instancing
     // key rather than merging incompatible geometries on the fallback path.
-    for (const entry of entries) if (entry.batchKey && this.ordered.available(entry.batchKey)) entry.key = entry.batchKey;
+    for (const entry of entries) if (entry.batchKey && this.ordered.available(entry.batchKey, renderer)) entry.key = entry.batchKey;
     for (const [mesh] of this.mixedDraws) if (!mesh.parent) this.mixedDraws.delete(mesh);
     entries.sort((a, b) => a.groupOrder - b.groupOrder || a.mesh.renderOrder - b.mesh.renderOrder || b.z - a.z || a.mesh.id - b.mesh.id);
     const used = new Map<string, number>();
@@ -181,11 +201,11 @@ export class BlenderTransparentInstances {
           const mixed = first.key.startsWith('multi:');
           let draw: Draw | undefined;
           if (mixed) {
-            const mesh = this.ordered.get(first.key, index);
+            const mesh = this.ordered.get(first.key, index, renderer);
             if (!mesh) continue;
             draw = this.mixedDraws.get(mesh);
             if (!draw) {
-              draw = {mesh, members: []};
+              draw = {mesh, members: [], palette: this.ordered.isPalette(first.key)};
               this.mixedDraws.set(mesh, draw);
               const held = draw;
               mesh.raycast = (raycaster, hits) => {
@@ -208,7 +228,7 @@ export class BlenderTransparentInstances {
             mesh.frustumCulled = false;
             mesh.boundingSphere = new THREE.Sphere();
             mesh.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
-            draw = {mesh, members: []};
+            draw = {mesh, members: [], palette: false};
             const held = draw;
             mesh.raycast = (raycaster, hits) => {
               if (!mesh.visible) return;
@@ -218,7 +238,7 @@ export class BlenderTransparentInstances {
             pool.push(draw);
             this.root.add(mesh);
           }
-          draw.mesh.material = this.drawMaterials.get(first.material!, draw.mesh);
+          if (!draw.palette) draw.mesh.material = this.drawMaterials.get(first.material!, draw.mesh);
           draw.mesh.visible = true;
           draw.mesh.renderOrder = head.mesh.renderOrder;
           draw.mesh.boundingSphere!.center.copy(head.centre).applyMatrix4(this.inverse);
@@ -229,6 +249,7 @@ export class BlenderTransparentInstances {
             draw.mesh.setMatrixAt(i, this.matrix);
             if (draw.mesh instanceof THREE.BatchedMesh) {
               draw.mesh.setGeometryIdAt(i, this.ordered.geometryId(first.key, member.geometry));
+              this.ordered.setMaterialAt(first.key, draw.mesh, i, entries[offset + i]!.material!);
               draw.mesh.setVisibleAt(i, true);
             }
             draw.members.push(member);
@@ -251,9 +272,10 @@ export class BlenderTransparentInstances {
     // A quiet viewport must also finish bounded pool construction. Notify only
     // after this draw's temporary layer/geometry swaps have been restored.
     if (this.ordered.pending) queueMicrotask(presenterChanged);
+    this.plannedGeneration = this.ordered.generation;
   }
 
-  inspect() { return {batches: this.batches, instances: this.instances, excluded: {...this.excluded}, multiDraw: this.ordered.inspect(), materials: this.drawMaterials.inspect()}; }
+  inspect() { return {batches: this.batches, instances: this.instances, excluded: {...this.excluded}, multiDraw: this.ordered.inspect(), materials: this.drawMaterials.inspect(), palettes: this.palettes.inspect()}; }
 
   private observe(value: number | string): void {
     if (this.planState[this.stateIndex] !== value) {
@@ -361,6 +383,10 @@ export class BlenderTransparentInstances {
     }
     this.pools.clear();
     this.ordered.clear();
+    this.palettes.clear();
+    this.sourceMaterials.clear();
+    this.plannedGeneration = -1;
+    this.renderer = undefined;
     this.drawMaterials.clear();
     this.mixedDraws.clear();
     this.planned.length = 0;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@volter/blender-engine",
   "author": "Volter AI, Inc.",
   "license": "GPL-3.0-or-later",
-  "version": "0.1.94",
+  "version": "0.1.95",
   "publishConfig": {
     "access": "public"
   },