Skip to content

3D engine that AI agents drive

8.1 KB
Raw Blame
import { bakeGasSim, GAS_SIM_TEMPERATURE_UNIT } from './gas-sim.js';
import { encodeVolumeGrid, isVolumeGridRegistered, registerVolumeGrid } from './volume-grid.js';

// The gas-sim grids behind add-explosion (#1050). One blast is baked once at a fixed size and resolution, and the volume's own box scales it, so
// a grid depends only on the fuel and the seed. Its file names say so (`explosion-dry-7_0000.67vg`): a recipe that names them can be rebuilt
// in a fresh scene, a render job or another process, because the MCP server bakes the same bytes again from the name (readVolumeGridFile).

export const EXPLOSION_GRID_RESOLUTION = 32;
export const EXPLOSION_GRID_FRAMES = 72;
export const EXPLOSION_GRID_FPS = 24;
/** Side of the baked box in metres: the volume's `size` is this times the blast's scale. */
export const EXPLOSION_GRID_BOX = 8;
/** The `size` in metres of an add-explosion that plays the bake at its own speed and scale. */
export const EXPLOSION_REFERENCE_SIZE = 2.5;
export const EXPLOSION_EMPTY_GRID = 'explosion-empty.67vg';
/** The empty frame of a blast that carries velocity: every frame of a sequence has the same channels, so it needs its own. */
export const EXPLOSION_EMPTY_VELOCITY_GRID = 'explosion-empty-velocity.67vg';
/** Whether add-explosion blurs the fireball along its velocity when the operation does not say (see motionBlur in agent-explosion.js). */
export const EXPLOSION_MOTION_BLUR_DEFAULT = true;
export { GAS_SIM_TEMPERATURE_UNIT };

/**
 * Bump this whenever the output of gas-sim.js changes: the on-disk bake cache (explosion-bake-cache.js) is keyed by it, so a stale file would
 * otherwise be served for the new solver. tests/explosion-bake-cache.test.js fails when the solver's output and this number disagree.
 */
export const EXPLOSION_BAKE_VERSION = 1;

const MAX_CACHED_BAKES = 4;
const BAKE_SECONDS_LIMIT = 90;
// A bake with velocity (for the motion blur of the fireball) says so in its name: `explosion-dry-7-velocity_0000.67vg`.
const NAME_PATTERN = /^explosion-(dry|oily)-(\d{1,10})(-velocity)?_(\d{4})\.67vg$/;
// Oily fuel burns sootier: more smoke at the core and more smoke from every burned unit of fuel.
const FUEL_OPTIONS = Object.freeze({
  dry: Object.freeze({ turbulence: 1, vorticity: 40 }),
  oily: Object.freeze({ burstSmoke: 1.6, smokeYield: 1.1, turbulence: 1, vorticity: 40 }),
});

const bakes = new Map();
let bakeStore = null;

/** Installs a store with `load(descriptor)` and `save(descriptor, frames)` that keeps bakes across processes (the MCP server installs a disk cache); null removes it. */
export function setExplosionBakeStore(store) {
  bakeStore = store;
}
const emptyFrames = new Map();

function gridSize() {
  return [EXPLOSION_GRID_BOX, EXPLOSION_GRID_BOX, EXPLOSION_GRID_BOX];
}

function bakeLabel(fuel, seed, velocity) {
  return `explosion-${fuel}-${seed}${velocity ? '-velocity' : ''}`;
}

/** The names of the frames of one bake, in playing order; with `velocity` the bake carries the velocity channels. */
export function explosionGridNames(fuel, seed, velocity = false) {
  return Array.from({ length: EXPLOSION_GRID_FRAMES }, (_, index) => `${bakeLabel(fuel, seed, velocity)}_${String(index).padStart(4, '0')}.67vg`);
}

function simulateFrames(fuel, seed, velocity) {
  const baked = bakeGasSim({
    resolution: EXPLOSION_GRID_RESOLUTION,
    cellSize: EXPLOSION_GRID_BOX / EXPLOSION_GRID_RESOLUTION,
    frames: EXPLOSION_GRID_FRAMES,
    fps: EXPLOSION_GRID_FPS,
    seed,
    maxSeconds: BAKE_SECONDS_LIMIT,
    velocity,
    ...FUEL_OPTIONS[fuel],
  });
  return baked.frames.map(frame => encodeVolumeGrid({ resolution: baked.resolution, channels: frame, size: gridSize() }));
}

function bakeFrames(fuel, seed, velocity) {
  const key = bakeLabel(fuel, seed, velocity);
  const cached = bakes.get(key);
  if (cached) return cached;
  const descriptor = {
    version: EXPLOSION_BAKE_VERSION,
    fuel,
    seed,
    velocity,
    frames: EXPLOSION_GRID_FRAMES,
    parameters: [EXPLOSION_GRID_RESOLUTION, EXPLOSION_GRID_BOX, EXPLOSION_GRID_FRAMES, EXPLOSION_GRID_FPS, FUEL_OPTIONS[fuel]],
  };
  let frames = bakeStore?.load(descriptor) ?? null;
  if (!frames) {
    frames = simulateFrames(fuel, seed, velocity);
    bakeStore?.save(descriptor, frames);
  }
  bakes.set(key, frames);
  if (bakes.size > MAX_CACHED_BAKES) bakes.delete(bakes.keys().next().value);
  return frames;
}

function emptyFrame(velocity) {
  if (!emptyFrames.has(velocity)) {
    const axis = EXPLOSION_GRID_RESOLUTION;
    const cells = axis * axis * axis;
    const channels = { density: new Float32Array(cells), temperature: new Float32Array(cells), flame: new Float32Array(cells) };
    if (velocity) Object.assign(channels, { velocityX: new Float32Array(cells), velocityY: new Float32Array(cells), velocityZ: new Float32Array(cells) });
    emptyFrames.set(velocity, encodeVolumeGrid({ resolution: [axis, axis, axis], channels, size: gridSize() }));
  }
  return emptyFrames.get(velocity);
}

/** The name of the empty frame that goes with a bake: the one with velocity channels when the bake has them. */
export function explosionEmptyGridName(velocity) {
  return velocity ? EXPLOSION_EMPTY_VELOCITY_GRID : EXPLOSION_EMPTY_GRID;
}

/**
 * The grid file names an add-explosion operation will name, for a caller that must send the files before the operation runs (the MCP server
 * sends them to the preview page), or null when the operation's fuel or seed is not valid: the operation itself then fails with its own error.
 */
export function explosionGridNamesFor(operation) {
  const fuel = operation.fuel ?? 'dry';
  const seed = operation.seed ?? 1;
  if (!Object.hasOwn(FUEL_OPTIONS, fuel) || !Number.isInteger(seed) || seed < 0 || seed > 4294967295) return null;
  const velocity = (operation.motionBlur ?? EXPLOSION_MOTION_BLUR_DEFAULT) === true;
  return [...explosionGridNames(fuel, seed, velocity), explosionEmptyGridName(velocity)];
}

/**
 * The length in bytes of an explosion grid file by name, or null when the name is not one add-explosion writes. Nothing is baked: every frame of
 * a bake has the channels of the empty frame at the same resolution, so the empty frame's length is the length of each of them (#1903).
 */
export function explosionGridByteLength(name) {
  if (name === EXPLOSION_EMPTY_GRID) return emptyFrame(false).length;
  if (name === EXPLOSION_EMPTY_VELOCITY_GRID) return emptyFrame(true).length;
  const match = typeof name === 'string' ? NAME_PATTERN.exec(name) : null;
  if (!match || Number(match[2]) > 4294967295 || Number(match[4]) >= EXPLOSION_GRID_FRAMES) return null;
  return emptyFrame(Boolean(match[3])).length;
}

/** The bytes of an explosion grid file by name, baked on first use, or null when the name is not one add-explosion writes. */
export function explosionGridBytes(name) {
  if (name === EXPLOSION_EMPTY_GRID) return emptyFrame(false);
  if (name === EXPLOSION_EMPTY_VELOCITY_GRID) return emptyFrame(true);
  const match = typeof name === 'string' ? NAME_PATTERN.exec(name) : null;
  if (!match) return null;
  const seed = Number(match[2]);
  const index = Number(match[4]);
  if (seed > 4294967295 || index >= EXPLOSION_GRID_FRAMES) return null;
  return bakeFrames(match[1], seed, Boolean(match[3]))[index];
}

/**
 * Bakes the blast of `fuel` and `seed` and registers its frames and the empty frame, so a grid volume that lists them draws in this process.
 * Returns the frame names. Same fuel and seed give the same bytes.
 */
export function registerExplosionGrids(fuel, seed, velocity = false) {
  if (!Object.hasOwn(FUEL_OPTIONS, fuel)) {
    throw new RangeError(`registerExplosionGrids: fuel is ${JSON.stringify(fuel)}; use one of ${Object.keys(FUEL_OPTIONS).join(', ')}`);
  }
  const names = explosionGridNames(fuel, seed, velocity);
  const emptyName = explosionEmptyGridName(velocity);
  // The MCP server sends these grids with the call (explosionGridNamesFor), so the preview page has them already and bakes nothing.
  if (isVolumeGridRegistered(names[0]) && isVolumeGridRegistered(names.at(-1)) && isVolumeGridRegistered(emptyName)) return names;
  const frames = bakeFrames(fuel, seed, velocity);
  names.forEach((name, index) => registerVolumeGrid(name, frames[index]));
  registerVolumeGrid(emptyName, emptyFrame(velocity));
  return names;
}