Skip to content

armgit / kiln

Public Imported from GitHub
0

Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.

22.5 KB
Raw Blame
import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
import sharp from 'sharp';
import { inspectGlb } from './generate-commons.mjs';
import { BRIDGE_CAPTURES, BRIDGE_ID, bridgeCaptureKey, bridgeCapturePath, cameraFromCaptureFile } from './bridge-captures.mjs';
import { pinMirrorFile, readJson, upsertBy, writeJson } from './media-pins.mjs';
import { assetPath, verifyArchive, verifyBytes } from './mirror-core.mjs';
import { RIG_ID, connectRig, fitCamera, orbitDirection, sha256Of } from './rig-render.mjs';
import { applyRigPosters, rigPosterImage, rigPosterKey, rigPosterPath } from './rig-posters-core.mjs';
import { FOUNDRY_FLOOR_ID, FOUNDRY_FLOOR_POSTER, FOUNDRY_FLOOR_SCENE_POSTER } from './foundry-floor-spec.mjs';

/**
 * Re-render the poster of every asset of a pack under the review rig and record the result:
 *
 *   bun scripts/rig-posters.mjs farm   --service http://127.0.0.1:8123 --mirror C:/.../mirror [--only barn,cow] [--out DIR]
 *   bun scripts/rig-posters.mjs bridge --service ... --mirror ... --outputs DIR --cameras DIR [--out DIR]
 *   bun scripts/rig-posters.mjs vehicles --service ... --mirror C:/.../mirror [--only sedan,suv] [--out DIR]
 *   bun scripts/rig-posters.mjs foundry-floor --service ... --mirror C:/.../mirror [--only foup,scene-poster] [--out DIR]
 *   bun scripts/rig-posters.mjs hero --service ... --mirror ... --outputs DIR [--out DIR]
 *   bun scripts/rig-posters.mjs cabin-woods-psx-horror --service ... --mirror ... [--out DIR]
 *   bun scripts/rig-posters.mjs holodeck --service ... --mirror .localdata/holodeck-delivery [--only a,b] [--out DIR]
 *
 * Each GLB is read from its sealed source (a delivery archive in the mirror, or the bridge author's export) and
 * verified against the catalog's SHA-256 before it is sent to the renderer. An image is the engine's own view of
 * that exact GLB, nothing composited or retouched. Farm, vehicle and Foundry Floor posters are pinned in the mirror and
 * planned here (the Foundry Floor scene page's poster is one pack model in a wide frame, recorded in scene-media.json); the
 * bridge views are written into the revision's mirror directory and pinned by the bridge update
 * (`generate-commons.mjs --only-bridge`), which also picks up the record. Nothing is uploaded.
 */

const SITE = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const DATA = join(SITE, 'src/data');
export const FARM_POSTER = { width: 1024, height: 1024, direction: [0.7, 0.5, 0.7], padding: 1.05 };
export const CABIN_WOODS_ID = 'cabin-woods-psx-horror';
export const CABIN_WOODS_POSTER = FARM_POSTER;

/** Cabin's staged runtime models are sealed separately from its ZIPs and saved review sheets. */
export async function cabinWoodsTargets({ publicDir = join(SITE, 'public'), data = DATA } = {}) {
  const catalog = await readJson(join(data, `${CABIN_WOODS_ID}.json`));
  return Promise.all(catalog.assets.map(async (asset) => {
    const download = asset.runtimeModelDownload;
    const path = assetPath(download.url.replace(/^\//, ''));
    if (!path.startsWith(`asset-demos/${CABIN_WOODS_ID}/models/`)) throw new Error(`Unexpected Cabin model path: ${path}`);
    const glb = await readFile(join(publicDir, path));
    verifyBytes(glb, download, asset.slug);
    return { pack: CABIN_WOODS_ID, release: catalog.release, slug: asset.slug, name: asset.name, revisionId: asset.revisionId, assetId: asset.assetId, alt: asset.description, glb, glbPath: download.url, view: CABIN_WOODS_POSTER };
  }));
}
/** The Holodeck packs' runtime models from the staging mirror, each verified against `holodeck.json`. */
export const HOLODECK_POSTER_PACK = 'holodeck';
/** The sofa opens toward -Z; the usual +Z view hides its cushions and throw. */
export const holodeckPosterView = (slug) => slug === 'winter-wmc-sofa-wool'
  ? { ...FARM_POSTER, direction: [0.7, 0.5, -0.7] }
  : FARM_POSTER;
export async function holodeckTargets({ mirror, data = DATA }) {
  const catalog = await readJson(join(data, 'holodeck.json'));
  return Promise.all(catalog.assets.map(async (asset) => {
    const download = asset.runtimeModelDownload;
    const glb = await readFile(join(mirror, assetPath(download.path)));
    verifyBytes(glb, download, asset.slug);
    return { pack: HOLODECK_POSTER_PACK, release: catalog.release, slug: asset.slug, name: asset.name, revisionId: asset.revisionId, assetId: asset.assetId, alt: asset.description, glb, glbPath: download.path, view: holodeckPosterView(asset.slug) };
  }));
}

/**
 * Every vehicle is seen from the same place so the cards line up: from the front right (the +X, +Z side), 20
 * degrees above the horizon, in a square frame. The GLB is the delivered file; a viewer that ignores MSFT_lod
 * draws its top tier and the wheels, which is what the renderer shows.
 */
export const VEHICLE_POSTER = { width: 1024, height: 1024, direction: orbitDirection(45, 20), padding: 1.05 };

/** The Farm r34 assets with their sealed runtime GLBs, verified against the catalog. */
export async function farmTargets({ mirror, data = DATA }) {
  const farm = await readJson(join(data, 'packs/farm.json'));
  const manifest = await readJson(join(data, 'mirror-manifest.json'));
  const pins = new Map(manifest.files.map((file) => [file.path, file]));
  const archives = new Map();
  const targets = [];
  for (const asset of farm.assets) {
    const download = asset.runtimeDownload;
    if (!archives.has(download.archive)) {
      const pin = pins.get(download.archive);
      if (!pin) throw new Error(`No mirror pin for ${download.archive}`);
      const bytes = await readFile(join(mirror, download.archive));
      verifyBytes(bytes, pin, download.archive);
      archives.set(download.archive, verifyArchive(bytes));
    }
    const glb = archives.get(download.archive).files[download.member];
    if (!glb) throw new Error(`${download.archive} lacks ${download.member}`);
    verifyBytes(glb, download, asset.slug);
    targets.push({ pack: 'farm', release: farm.revision, slug: asset.slug, name: asset.name, revisionId: asset.revisionId, assetId: asset.assetId, alt: asset.description, glb, glbPath: download.member, view: FARM_POSTER });
  }
  return targets;
}

/** The vehicles' delivered GLBs from the mirror, each verified against the catalog record. */
export async function vehicleTargets({ mirror, data = DATA }) {
  const vehicles = await readJson(join(data, 'packs/vehicles.json'));
  const targets = [];
  for (const asset of vehicles.assets) {
    const download = asset.runtimeDownload;
    const glb = await readFile(join(mirror, download.path));
    verifyBytes(glb, download, asset.slug);
    targets.push({ pack: 'vehicles', release: vehicles.release, slug: asset.slug, name: asset.name, revisionId: asset.revisionId, assetId: asset.assetId, alt: asset.description, glb, glbPath: download.path, view: VEHICLE_POSTER });
  }
  return targets;
}

/**
 * The Foundry Floor models' delivered GLBs from the mirror, each verified against the catalog record, and the scene
 * page's poster: one of those GLBs in a wide frame (FOUNDRY_FLOOR_SCENE_POSTER).
 */
export async function foundryFloorTargets({ mirror, data = DATA }) {
  const pack = await readJson(join(data, 'packs/foundry-floor.json'));
  const targets = [];
  for (const asset of pack.assets) {
    const download = asset.runtimeDownload;
    const glb = await readFile(join(mirror, download.path));
    verifyBytes(glb, download, asset.slug);
    targets.push({ pack: FOUNDRY_FLOOR_ID, release: pack.release, slug: asset.slug, name: asset.name, revisionId: asset.revisionId, alt: asset.description, glb, glbPath: download.path, view: FOUNDRY_FLOOR_POSTER });
  }
  const subject = targets.find((target) => target.slug === FOUNDRY_FLOOR_SCENE_POSTER.slug);
  if (!subject) throw new Error(`The scene poster's model ${FOUNDRY_FLOOR_SCENE_POSTER.slug} is not in the pack`);
  targets.push({ ...subject, slug: FOUNDRY_FLOOR_SCENE_POSTER.key, subject: subject.slug, alt: FOUNDRY_FLOOR_SCENE_POSTER.alt, view: FOUNDRY_FLOOR_SCENE_POSTER.view });
  return targets;
}

/**
 * Record the Foundry Floor scene page's poster in scene-media.json: the rig image of one pack model, with what it
 * was rendered from, so the page can say exactly what it shows.
 */
export async function recordFoundryFloorScenePoster({ posters, data = DATA }) {
  const record = posters[rigPosterKey(FOUNDRY_FLOOR_ID, FOUNDRY_FLOOR_SCENE_POSTER.key)];
  if (!record) return null;
  const file = join(data, 'scene-media.json');
  const media = await readJson(file);
  media[FOUNDRY_FLOOR_ID] = {
    ...media[FOUNDRY_FLOOR_ID],
    poster: rigPosterImage(record, FOUNDRY_FLOOR_SCENE_POSTER.alt),
    rig: { subject: FOUNDRY_FLOOR_SCENE_POSTER.slug, revisionId: record.revisionId, glb: record.glb, view: record.view, rendererId: record.rendererId, pngBytes: record.bytes, pngSha256: record.sha256 },
  };
  await writeJson(file, media);
  return media[FOUNDRY_FLOOR_ID];
}

/**
 * The bridge's full-tier views: the author's export of the accepted revision, verified against the accepted
 * pins, seen through the author's own capture cameras (`<cameras>/<name>.json`).
 */
export async function bridgeTargets({ outputs, cameras, tiers }) {
  const full = tiers.tiers.find((tier) => tier.tier === 'full');
  if (!full) throw new Error('The accepted tiers list has no full tier');
  const glb = await readFile(join(outputs, full.glb.file));
  verifyBytes(glb, full.glb, full.glb.file);
  const targets = [];
  for (const capture of BRIDGE_CAPTURES) {
    const file = await readFile(join(cameras, `${capture.name}.json`));
    const { camera, size } = cameraFromCaptureFile(JSON.parse(file.toString('utf8')));
    targets.push({
      pack: 'bridge',
      slug: BRIDGE_ID,
      capture: capture.name,
      key: bridgeCaptureKey(capture),
      revisionId: full.revision,
      assetId: tiers.assetId,
      alt: capture.alt,
      glb,
      glbPath: full.glb.file,
      path: bridgeCapturePath(full.revision, capture.name),
      camera,
      cameraSource: { file: `${capture.name}.json`, sha256: sha256Of(file) },
      view: { width: size, height: size },
    });
  }
  return targets;
}

/** The home page hero's key family in the record and its mirror folder (`media/rig/<rig>/hero/<revision>/`). */
export const HERO_PACK = 'hero';

/**
 * The home page hero: the bridge's web tier (the tier its page loads first) through the author's classic poster
 * camera, as recorded for the bridge poster, at the Farm poster's size, and pinned like the pack posters. The GLB is
 * the author's export, verified against the accepted web-tier pin. `scripts/build-hero.mjs` draws on the result.
 */
export async function heroTargets({ outputs, tiers, recorded }) {
  const web = tiers.tiers.find((tier) => tier.tier === 'web');
  if (!web) throw new Error('The accepted tiers list has no web tier');
  const glb = await readFile(join(outputs, web.glb.file));
  verifyBytes(glb, web.glb, web.glb.file);
  const classic = BRIDGE_CAPTURES.find((capture) => capture.poster);
  const poster = recorded?.posters?.[bridgeCaptureKey(classic)];
  if (!poster?.view?.camera) throw new Error('The bridge poster record has no capture camera: render the bridge views first');
  return [{
    pack: HERO_PACK,
    release: web.revision,
    slug: BRIDGE_ID,
    revisionId: web.revision,
    assetId: tiers.assetId,
    alt: classic.alt,
    glb,
    glbPath: web.glb.file,
    camera: poster.view.camera,
    cameraSource: poster.view.source,
    view: { width: FARM_POSTER.width, height: FARM_POSTER.height },
  }];
}

/** Render one target under the rig; the receipt names everything the image depends on. */
export async function renderTarget(rig, target) {
  const bounds = inspectGlb(target.glb);
  const { width, height } = target.view;
  const camera = target.camera
    ? rig.engine.camera.validateResolvedAssetCamera(target.camera)
    : fitCamera(rig.engine, { min: bounds.boundsMin, max: bounds.boundsMax }, target.view.direction, { aspect: width / height, padding: target.view.padding });
  const { pngs, receipt } = await rig.capture({ glb: target.glb, cameras: [camera], width, height });
  const png = pngs[0];
  const meta = await sharp(png).metadata();
  if (meta.width !== width || meta.height !== height) throw new Error(`${target.slug}: PNG is ${meta.width}x${meta.height}, expected ${width}x${height}`);
  return {
    png,
    record: {
      path: target.path ?? rigPosterPath(target.pack, target.release, target.slug),
      width,
      height,
      bytes: png.length,
      sha256: sha256Of(png),
      assetId: target.assetId,
      revisionId: target.revisionId,
      ...(target.capture ? { capture: target.capture } : {}),
      glb: { member: target.glbPath, bytes: target.glb.length, sha256: sha256Of(target.glb), triangles: bounds.triangles },
      view: target.camera ? { camera, source: target.cameraSource } : { direction: target.view.direction, padding: target.view.padding, projection: camera.projection, halfHeight: camera.halfHeight },
      rendererId: receipt.rendererId,
    },
  };
}

const recordKey = (target) => target.key ?? rigPosterKey(target.pack, target.slug);

/**
 * A poster run's identity: its pack, the day it rendered, and a digest of the engine and render service it used.
 * Re-rendering under the same engine and service on the same day is the same run; anything else is another one, so
 * a later run can never be mistaken for the one that made an earlier image.
 */
export const rigRunId = ({ pack, renderedOn, engine, service }) => `${pack}-${renderedOn}-${sha256Of(Buffer.from(JSON.stringify([engine, service]))).slice(0, 8)}`;
const rigRun = ({ pack, renderedOn, engine, service }) => ({ id: rigRunId({ pack, renderedOn, engine, service }), pack, renderedOn, engine, service });

/**
 * Every run recorded so far, one record each. Earlier files kept a single run per pack, and the one before that a
 * single run for the whole file, so a second run of a pack overwrote the first run's engine, service and date --
 * seven winter posters ended up pointing at the run that rendered a different pack. Those headers are migrated
 * here; the posters they covered keep no run, because which run made them was lost before this record existed.
 */
export function rigRuns(previous) {
  const rig = previous?.rig ?? {};
  if (Array.isArray(rig.runs)) return rig.runs.map((run) => (run.id ? run : rigRun(run)));
  const legacy = rig.runs ?? (rig.engine ? { farm: { renderedOn: rig.renderedOn, engine: rig.engine, service: rig.service } } : {});
  return Object.entries(legacy).map(([pack, run]) => rigRun({ pack, ...run }));
}

/**
 * Write the record, and (Farm) pin the PNGs and extend the image plan. `pin: false` writes the PNGs into the
 * mirror without pinning them: the bridge update pins a revision's whole directory itself and would replace
 * any earlier pin under it. Each poster names the run that rendered it, and each run keeps its own record.
 */
export async function recordPosters({ rig, rendered, mirror, data = DATA, renderedOn = new Date().toISOString().slice(0, 10), pin = true }) {
  const manifestFile = join(data, 'mirror-manifest.json');
  const planFile = join(data, 'commons-build.json');
  const recordFile = join(data, 'rig-posters.json');
  const previous = await readJson(recordFile).catch(() => ({ schemaVersion: 1, rig: {}, posters: {} }));
  const posters = { ...previous.posters };
  // One record per run: the engine and service that image set came from.
  const runs = rigRuns(previous);
  let plan = pin ? await readJson(planFile) : undefined;
  for (const { png, record, target } of rendered) {
    if (pin) await pinMirrorFile({ mirror, manifestFile, path: record.path, bytes: png });
    else {
      await mkdir(dirname(join(mirror, record.path)), { recursive: true });
      await writeFile(join(mirror, record.path), png);
    }
    if (pin) plan = { ...plan, images: upsertBy(plan.images, 'inputPath', rigPosterImage(record, target.alt)) };
    const run = rigRun({
      pack: target.pack,
      renderedOn,
      engine: { commit: rig.engine.provenance.commit, subject: rig.engine.provenance.subject, dirty: rig.engine.provenance.dirty },
      service: rig.service,
    });
    if (!runs.some((prior) => prior.id === run.id)) runs.push(run);
    posters[recordKey(target)] = { ...record, run: run.id };
  }
  if (pin) await writeJson(planFile, plan);
  await writeJson(recordFile, { schemaVersion: 1, rig: { id: RIG_ID, backdrop: 'neutral', runs }, posters });
  return posters;
}

/**
 * Drop image plan entries no catalog file references any more, so a replaced image (an earlier poster) is not
 * built into responsive variants nobody uses. Its mirror pin stays: the earlier file is still a verified record.
 */
export async function pruneImagePlan({ data = DATA } = {}) {
  const catalogs = [];
  const walk = async (dir) => {
    for (const entry of await readdir(dir, { withFileTypes: true })) {
      const path = join(dir, entry.name);
      if (entry.isDirectory()) await walk(path);
      else if (entry.name.endsWith('.json') && !['commons-build.json', 'mirror-manifest.json', 'upload-manifest.json', 'rig-posters.json'].includes(entry.name)) catalogs.push(await readFile(path, 'utf8'));
    }
  };
  await walk(data);
  const text = catalogs.join('\n');
  const plan = await readJson(join(data, 'commons-build.json'));
  const kept = plan.images.filter((image) => text.includes(`"inputPath": ${JSON.stringify(image.inputPath)}`));
  const dropped = plan.images.filter((image) => !kept.includes(image)).map((image) => image.inputPath);
  if (dropped.length) await writeJson(join(data, 'commons-build.json'), { ...plan, images: kept });
  return dropped;
}

/** Rewrite one catalog file so its posters come from the record. */
export async function refreshCatalog({ file, pack, data = DATA }) {
  const recorded = await readJson(join(data, 'rig-posters.json'));
  const catalog = await readJson(file);
  if (Array.isArray(catalog.assets)) {
    const required = [CABIN_WOODS_ID, HOLODECK_POSTER_PACK].includes(pack);
    if (required) catalog.assets = catalog.assets.map((asset) => ({ ...asset, poster: null }));
    catalog.assets = applyRigPosters(catalog.assets, pack, recorded, { required });
  }
  await writeJson(file, catalog);
  return catalog;
}

async function main(argv = process.argv.slice(2), env = process.env) {
  const option = (flag, fallback) => (argv.includes(flag) ? argv[argv.indexOf(flag) + 1] : fallback);
  const pack = argv[0];
  const mirror = option('--mirror', env.KILN_ASSET_MIRROR);
  if (!['farm', 'bridge', 'vehicles', FOUNDRY_FLOOR_ID, HERO_PACK, CABIN_WOODS_ID, HOLODECK_POSTER_PACK].includes(pack) || !mirror) throw new Error('Usage: bun scripts/rig-posters.mjs farm|bridge|vehicles|foundry-floor|hero|cabin-woods-psx-horror|holodeck --mirror DIR [--service URL] [--engine DIR] [--only a,b] [--out DIR] [--dry]  (bridge also needs --outputs DIR --cameras DIR; hero needs --outputs DIR)');
  const only = option('--only')?.split(',');
  const rig = await connectRig({ url: option('--service', env.KILN_RENDER_SERVICE_URL), engineDir: option('--engine') });
  console.log(`Rig ${RIG_ID} on ${rig.service.rendererId}; engine ${rig.engine.provenance.commit.slice(0, 7)} (${rig.engine.provenance.subject})${rig.engine.provenance.dirty ? ' with local changes' : ''}`);
  let targets;
  if (pack === 'bridge') {
    const outputs = option('--outputs');
    const cameras = option('--cameras');
    if (!outputs || !cameras) throw new Error('The bridge views need --outputs (the author export folder) and --cameras (the capture files folder)');
    targets = (await bridgeTargets({ outputs: resolve(outputs), cameras: resolve(cameras), tiers: await readJson(join(DATA, 'standalone/golden-gate-tiers.json')) })).filter((target) => !only || only.includes(target.capture));
  } else if (pack === HERO_PACK) {
    const outputs = option('--outputs');
    if (!outputs) throw new Error('The hero needs --outputs (the bridge author export folder)');
    targets = await heroTargets({ outputs: resolve(outputs), tiers: await readJson(join(DATA, 'standalone/golden-gate-tiers.json')), recorded: await readJson(join(DATA, 'rig-posters.json')) });
  } else if (pack === CABIN_WOODS_ID) {
    targets = (await cabinWoodsTargets()).filter((target) => !only || only.includes(target.slug));
  } else if (pack === HOLODECK_POSTER_PACK) {
    targets = (await holodeckTargets({ mirror })).filter((target) => !only || only.includes(target.slug));
  } else if (pack === 'vehicles') {
    targets = (await vehicleTargets({ mirror })).filter((target) => !only || only.includes(target.slug));
  } else if (pack === FOUNDRY_FLOOR_ID) {
    targets = (await foundryFloorTargets({ mirror })).filter((target) => !only || only.includes(target.slug));
  } else {
    targets = (await farmTargets({ mirror })).filter((target) => !only || only.includes(target.slug));
  }
  if (!targets.length) throw new Error('No poster targets selected');
  const rendered = [];
  for (const target of targets) {
    const { png, record } = await renderTarget(rig, target);
    rendered.push({ png, record, target });
    console.log(`${target.capture ?? target.slug}: ${record.width}x${record.height} ${record.bytes} B sha256 ${record.sha256.slice(0, 12)} from ${record.glb.triangles} triangles`);
  }
  const out = option('--out');
  if (out) {
    await mkdir(resolve(out), { recursive: true });
    for (const { png, target } of rendered) await writeFile(join(resolve(out), `${target.capture ?? target.slug}.png`), png);
  }
  if (argv.includes('--dry')) return console.log(`Dry run: ${rendered.length} images rendered; nothing recorded.`);
  const posters = await recordPosters({ rig, rendered, mirror, pin: pack !== 'bridge' });
  if (pack === HERO_PACK) {
    console.log('Pinned the hero poster; scripts/build-hero.mjs writes the hero data from it.');
  } else if (pack !== 'bridge') {
    await refreshCatalog({ file: join(DATA, [CABIN_WOODS_ID, HOLODECK_POSTER_PACK].includes(pack) ? `${pack}.json` : `packs/${pack}.json`), pack });
    if (pack === FOUNDRY_FLOOR_ID && (await recordFoundryFloorScenePoster({ posters }))) console.log('Recorded the scene page poster in scene-media.json.');
    // Cabin's saved sheets were direct delivery URLs and Holodeck had no earlier posters, so nothing needs pruning.
    if (![CABIN_WOODS_ID, HOLODECK_POSTER_PACK].includes(pack)) {
      const dropped = await pruneImagePlan();
      if (dropped.length) console.log(`Dropped ${dropped.length} replaced images from the build plan (their mirror pins stay).`);
    }
  } else {
    console.log('The bridge update (scripts/generate-commons.mjs --only-bridge) pins these images and applies the record.');
  }
  console.log(`Recorded ${rendered.length} ${pack} images under ${RIG_ID}.`);
}

if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) await main();