Skip to content

3D engine that AI agents drive

12.5 KB
Raw Blame
// Heavy pure computations (light bake, cloth solver, material pattern bake, uv_unwrap) can run on a worker while the
// page stays responsive. Scene building is synchronous, so the worker result reaches it through a cache:
//
//   1. `buildWithKernels(build)` runs the synchronous build with a session open.
//   2. A kernel that has no cached result throws `KernelDeferred` instead of computing.
//   3. The session computes that kernel on a worker, caches the result by a hash of its input, and runs the build again.
//
// Without a session `runKernel` computes inline, so every caller that never opted in behaves exactly as before and a
// host without workers (Node) produces the same bytes through the same code. This module is only imported by the
// on-demand scene modules, never by the scene core.

// Held in a constant so the bundler leaves the URL alone: the worker is its own package entry, built beside this file.
const KERNEL_WORKER_FILE = './kernel-worker.js';

const RECONSTRUCTED_ERRORS = { RangeError, TypeError, SyntaxError, ReferenceError };

// More distinct heavy kernels than any real scene holds: past it the build finishes inline.
const MAXIMUM_DEFERRALS = 256;

let activeSession = null;
let workerStartFailure = null;

// What ran where, since the last reset: a kernel served by a worker, a kernel computed inline, and why a kernel that
// should have gone to a worker did not. A silent fallback would otherwise look the same as success.
const MAXIMUM_RECORDED_FALLBACKS = 16;
const statistics = { worker: 0, page: 0, inline: 0, fallbacks: [] };

/** Counts of kernels served by a worker and run inline, with the reason for each fallback. */
export function kernelStats() {
  return { worker: statistics.worker, page: statistics.page, inline: statistics.inline, fallbacks: statistics.fallbacks.map(fallback => ({ ...fallback })) };
}

export function resetKernelStats() {
  statistics.worker = 0;
  statistics.page = 0;
  statistics.inline = 0;
  statistics.fallbacks = [];
}

function recordFallback(kernel, reason) {
  if (statistics.fallbacks.length < MAXIMUM_RECORDED_FALLBACKS) {
    statistics.fallbacks.push({ kernel, reason });
  }
  if (kernelWorkersAvailable()) {
    console.warn(`Crucible kernel fallback: ${kernel} ran inline (${reason}).`);
  }
}

function computeInline(compute, args) {
  statistics.inline++;
  return compute(...args);
}

/** Thrown by `runKernel` inside a session when a kernel's result has to be computed on the worker first. */
export class KernelDeferred {
  constructor(job) {
    this.job = job;
  }
}

function isPlainObject(value) {
  const prototype = Object.getPrototypeOf(value);
  return prototype === Object.prototype || prototype === null;
}

const HASH_PRIMES = [0x01000193, 0x85ebca6b];

function createHasher() {
  return { states: [0x811c9dc5, 0x9747b28c], length: 0 };
}

function mixBytes(hasher, bytes) {
  for (let index = 0; index < bytes.length; index++) {
    for (let lane = 0; lane < 2; lane++) {
      hasher.states[lane] = Math.imul(hasher.states[lane] ^ bytes[index], HASH_PRIMES[lane]) >>> 0;
    }
  }
  hasher.length += bytes.length;
}

const textEncoder = new TextEncoder();

function mixText(hasher, text) {
  mixBytes(hasher, textEncoder.encode(text));
}

function mixNamedValue(hasher, key, value) {
  mixText(hasher, `${key.length}:${key}=`);
  return mixValue(hasher, value);
}

/** Feeds a value into the hasher; returns false for anything that is not plain, cloneable data. */
function mixValue(hasher, value) {
  if (value === null || value === undefined || typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string') {
    // String(-0) is "0": spell the sign out so 0 and -0 do not share a key.
    const text = Object.is(value, -0) ? '-0' : String(value);
    mixText(hasher, `${typeof value}:${text.length}:${text};`);
    return true;
  }
  if (ArrayBuffer.isView(value)) {
    mixText(hasher, `${value.constructor.name}:${value.byteLength};`);
    mixBytes(hasher, new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
    return true;
  }
  // Browsers hold pattern textures as ImageData, which a worker clones as it is.
  if (typeof ImageData === 'function' && value instanceof ImageData) {
    mixText(hasher, `ImageData:${value.width}x${value.height}:${value.colorSpace};`);
    return mixValue(hasher, value.data);
  }
  if (Array.isArray(value)) {
    mixText(hasher, `[${value.length}:`);
    // By index, because `every` skips the holes of a sparse array and [, 1] would match [1, ,].
    for (let index = 0; index < value.length; index++) {
      if (!mixValue(hasher, value[index])) {
        return false;
      }
    }
    return true;
  }
  if (typeof value === 'object' && isPlainObject(value)) {
    const keys = Object.keys(value);
    mixText(hasher, `{${keys.length}:`);
    return keys.every(key => mixNamedValue(hasher, key, value[key]));
  }
  return false;
}

// A self-referencing object overflows the stack while hashing; it is not plain data for this purpose, so it runs inline.
function mixesAsPlainData(hasher, args) {
  try {
    return mixValue(hasher, args);
  } catch (error) {
    if (error instanceof RangeError) {
      return false;
    }
    throw error;
  }
}

/** A key that identifies a kernel call by its name and the bytes of its input, or null when the input is not plain data. */
export function kernelKey(name, args) {
  const hasher = createHasher();
  mixText(hasher, `${name}:`);
  if (!mixesAsPlainData(hasher, args)) {
    return null;
  }
  return `${name}:${hasher.length}:${hasher.states.map(state => state.toString(16)).join('')}`;
}

/**
 * Runs `compute(...args)`. Inside a `buildWithKernels` session the call returns the worker's cached result, or throws
 * `KernelDeferred` so the session can fetch it. Everywhere else it computes inline. A call site that catches errors
 * must rethrow `KernelDeferred`.
 */
export function runKernel(name, args, compute) {
  if (!activeSession) {
    return computeInline(compute, args);
  }
  const key = kernelKey(name, args);
  if (key === null) {
    recordFallback(name, 'its input is not plain data');
    return computeInline(compute, args);
  }
  if (activeSession.inlineAll || activeSession.inlineKeys.has(key)) {
    return computeInline(compute, args);
  }
  if (activeSession.results.has(key)) {
    const entry = activeSession.results.get(key);
    if (entry.thrown) {
      throw entry.thrown;
    }
    return entry.value;
  }
  throw new KernelDeferred({ name, args, key });
}

function rebuildError({ name, message }) {
  const ErrorClass = RECONSTRUCTED_ERRORS[name] ?? Error;
  return new ErrorClass(message);
}

function defaultWorkerFactory() {
  return new Worker(new URL(KERNEL_WORKER_FILE, import.meta.url), { type: 'module' });
}

/** Whether this host can start the kernel worker. */
export function kernelWorkersAvailable() {
  return typeof Worker === 'function';
}

function abortError(signal) {
  return signal.reason ?? new DOMException('The build was cancelled.', 'AbortError');
}

// A worker that is gone without an error event never answers; the page can only notice by waiting.
const DEFAULT_KERNEL_TIMEOUT_MILLISECONDS = 60000;
const MAXIMUM_KERNEL_TIMEOUT_MILLISECONDS = 3600000;

function validateKernelTimeout(milliseconds) {
  if (!Number.isFinite(milliseconds) || milliseconds <= 0 || milliseconds > MAXIMUM_KERNEL_TIMEOUT_MILLISECONDS) {
    throw new RangeError(`kernelTimeoutMilliseconds must be a finite number above 0 and at most ${MAXIMUM_KERNEL_TIMEOUT_MILLISECONDS}, got ${milliseconds}. Omit it for ${DEFAULT_KERNEL_TIMEOUT_MILLISECONDS}.`);
  }
}

/** One job on one worker: resolves with the worker's answer, or rejects when the worker fails or stays silent too long. */
function requestKernel(worker, job, signal, timeoutMilliseconds) {
  return new Promise((resolve, reject) => {
    // A signal that fired while a page kernel ran never calls a listener added now.
    if (signal?.aborted) {
      reject(abortError(signal));
      return;
    }
    const timer = setTimeout(() => {
      cleanUp();
      const error = new Error(`Kernel worker gave no answer for ${job.name} within ${timeoutMilliseconds} ms.`);
      error.timedOut = true;
      reject(error);
    }, timeoutMilliseconds);
    const cleanUp = () => {
      clearTimeout(timer);
      signal?.removeEventListener('abort', onAbort);
      worker.onmessage = null;
      worker.onerror = null;
      worker.onmessageerror = null;
    };
    const onAbort = () => {
      cleanUp();
      reject(abortError(signal));
    };
    signal?.addEventListener('abort', onAbort, { once: true });
    worker.onmessage = event => {
      cleanUp();
      resolve(event.data);
    };
    worker.onerror = event => {
      cleanUp();
      reject(new Error(`Kernel worker failed: ${event.message}`));
    };
    worker.onmessageerror = () => {
      cleanUp();
      reject(new Error('Kernel worker answered with data the page could not read.'));
    };
    try {
      worker.postMessage({ name: job.name, args: job.args });
    } catch (error) {
      cleanUp();
      reject(error);
    }
  });
}

/**
 * Runs a synchronous scene build while its heavy kernels compute on a worker. The result is the build's own result,
 * built from identical bytes. `createWorker` replaces the browser Worker (tests, other hosts); `signal` cancels the
 * build and ends the worker. Hosts without workers just run the build.
 */
export async function buildWithKernels(build, { createWorker = defaultWorkerFactory, signal, available = kernelWorkersAvailable(), pageKernels, kernelTimeoutMilliseconds = DEFAULT_KERNEL_TIMEOUT_MILLISECONDS } = {}) {
  validateKernelTimeout(kernelTimeoutMilliseconds);
  if (!available || activeSession) {
    return build();
  }
  const session = { results: new Map(), inlineKeys: new Set(), inlineAll: false, deferrals: 0 };
  let worker = null;
  try {
    for (;;) {
      if (signal?.aborted) {
        throw abortError(signal);
      }
      activeSession = session;
      try {
        return build();
      } catch (error) {
        if (!(error instanceof KernelDeferred)) {
          throw error;
        }
        activeSession = null;
        session.deferrals++;
        // A build whose inputs change on every run would never find its cached result; computing inline ends the loop.
        if (session.deferrals > MAXIMUM_DEFERRALS && !session.inlineAll) {
          session.inlineAll = true;
          recordFallback(error.job.name, 'the build asked for more kernels than any scene holds');
        }
        if (await computeOnPage(session, pageKernels, error.job)) {
          continue;
        }
        worker ??= createWorkerOrNull(createWorker);
        await computeOnWorker(session, worker, error.job, signal, kernelTimeoutMilliseconds);
      } finally {
        activeSession = null;
      }
    }
  } finally {
    worker?.terminate();
  }
}

// A page kernel answers a job on the page itself, where the GPU is, instead of on the worker. It takes a job only when its
// `accepts` says so; if it fails, the worker still does the job on the CPU, so a GPU fault never fails a build.
async function computeOnPage(session, pageKernels, job) {
  const kernel = pageKernels?.[job.name];
  if (!kernel?.accepts(job.args)) {
    return false;
  }
  try {
    session.results.set(job.key, { value: await kernel.compute(job.args) });
    statistics.page++;
    return true;
  } catch (error) {
    recordFallback(job.name, `the page kernel failed: ${error.message}`);
    return false;
  }
}

function createWorkerOrNull(createWorker) {
  try {
    return createWorker();
  } catch (error) {
    workerStartFailure = error.message;
    return null;
  }
}

// A worker that cannot start or dies leaves the job to the inline path, which then does the work and raises its own
// errors, so a failure never depends on the worker.
async function computeOnWorker(session, worker, job, signal, timeoutMilliseconds) {
  if (!worker) {
    session.inlineKeys.add(job.key);
    recordFallback(job.name, `the worker could not start: ${workerStartFailure}`);
    return;
  }
  let answer;
  try {
    answer = await requestKernel(worker, job, signal, timeoutMilliseconds);
  } catch (error) {
    if (signal?.aborted) {
      throw error;
    }
    if (error.timedOut) {
      // A silent worker may be gone for good: end it and finish the build inline instead of waiting once per kernel.
      worker.terminate();
      session.inlineAll = true;
    }
    session.inlineKeys.add(job.key);
    recordFallback(job.name, `the worker failed: ${error.message}`);
    return;
  }
  statistics.worker++;
  session.results.set(job.key, answer.error ? { thrown: rebuildError(answer.error) } : { value: answer.value });
}