Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

forge(delivery): derive full PBR channels and WebP-cap textures before a mesh lands

nirholas2d81f57a2d3c
diff --git a/api/_lib/forge-store.js b/api/_lib/forge-store.js
index 1e4ad1d7a..06c672448 100644
--- a/api/_lib/forge-store.js
+++ b/api/_lib/forge-store.js
@@ -271,17 +271,23 @@ const COPY_MAX_ATTEMPTS = 3;
// body read, so it is sized for the 64 MB ceiling on a slow origin.
const COPY_TIMEOUT_MS = 120_000;
-// Score, clean, and (optionally) compress a freshly-downloaded GLB before it
-// lands in the bucket. Every step is pure, local, and best-effort: a failure
-// never blocks delivery — it just means the response carries no quality signal,
-// or ships the un-cleaned / uncompressed bytes. `compress` is one of
-// COMPRESSION_MODES ('draco' | 'meshopt') or falsy to skip. `cleanup` runs the
-// codec-independent geometry cleanup (glb-cleanup.js) that tames the workers'
-// raw marching-cubes triangle soup; on by default for forge meshes.
-async function scoreAndCompress(buf, { computeQuality, compress, cleanup = false }) {
+// Score, clean, derive PBR channels for, and (optionally) compress a freshly
+// downloaded GLB before it lands in the bucket. Every step is pure, local, and
+// best-effort: a failure never blocks delivery — it just means the response
+// carries no quality signal, or ships the un-cleaned / uncompressed bytes.
+// `compress` is one of COMPRESSION_MODES ('draco' | 'meshopt') or falsy to
+// skip. `cleanup` runs the codec-independent geometry cleanup (glb-cleanup.js)
+// that tames the workers' raw marching-cubes triangle soup; on by default for
+// forge meshes. `derivePbr` runs the material completion pass
+// (glb-pbr-derive.js) that turns an albedo-only lane output into a full PBR set
+// (normal + packed occlusion/roughness/metallic + the class's measured
+// extension layer); on by default, pass false to deliver the lane's own
+// materials untouched.
+async function scoreAndCompress(buf, { computeQuality, compress, cleanup = false, derivePbr = false, prompt = '', tier = '', materialClass = '' }) {
let quality = null;
let compression = null;
let cleaned = null;
+ let pbr = null;
let outBuf = buf;
// Cleanup FIRST: a welded, de-duplicated, decimated mesh both renders better
// and compresses better than the raw soup, so the codec below operates on the
@@ -305,6 +311,29 @@ async function scoreAndCompress(buf, { computeQuality, compress, cleanup = false
console.warn('[forge-store] geometry cleanup failed, delivering as-is:', err?.message);
}
}
+ // Material completion SECOND: it reads the albedo the lane baked and writes
+ // derived maps onto the geometry cleanup just settled, so it has to run after
+ // cleanup and before the codec pass (a Draco/meshopt-encoded buffer would
+ // have to be decoded again to touch its materials) and before quality
+ // scoring, so `no_materials` reflects what users actually receive.
+ if (derivePbr) {
+ try {
+ const r = await derivePbrChannels(outBuf, { prompt, tier, materialClass });
+ if (r.changed) {
+ outBuf = r.buffer;
+ pbr = {
+ input_bytes: r.inputBytes,
+ output_bytes: r.outputBytes,
+ materials_created: r.materialsCreated,
+ normals_filled: r.normalsFilled,
+ mime_types_fixed: r.mimeTypesFixed,
+ materials: r.materials,
+ };
+ }
+ } catch (err) {
+ console.warn('[forge-store] PBR derivation failed, delivering lane materials as-is:', err?.message);
+ }
+ }
if (computeQuality) {
try {
quality = scoreGlbQuality(outBuf);
@@ -331,7 +360,7 @@ async function scoreAndCompress(buf, { computeQuality, compress, cleanup = false
compression = { mode: compress, skipped: true, reason: 'compression_failed' };
}
}
- return { buf: outBuf, quality, compression, cleaned };
+ return { buf: outBuf, quality, compression, cleaned, pbr };
}
// An upstream Content-Type ends up as the object's stored type, which the CDN
@@ -345,7 +374,7 @@ function mediaTypeOr(header, fallback) {
return STORABLE_TYPE_RE.test(type) ? type : fallback;
}
-async function copyToBucket({ sourceUrl, key, fallbackContentType, maxBytes, computeQuality = false, compress = null, cleanup = false, forceContentType = null }) {
+async function copyToBucket({ sourceUrl, key, fallbackContentType, maxBytes, computeQuality = false, compress = null, cleanup = false, derivePbr = false, prompt = '', tier = '', materialClass = '', forceContentType = null }) {
// fetchUpstream retries network errors and 408/425/429/5xx with jittered
// backoff and gives up immediately on 404/410 (the ephemeral asset has
// already expired; no retry can recover it), rejecting with an error that
diff --git a/api/_lib/glb-compress.js b/api/_lib/glb-compress.js
index 2547b3714..014478670 100644
--- a/api/_lib/glb-compress.js
+++ b/api/_lib/glb-compress.js
@@ -7,11 +7,13 @@
// • meshopt — EXT_meshopt_compression: slightly larger, decodes fast on the GPU;
// three.js' GLTFLoader in the three.ws viewer is decoder-equipped.
//
-// Geometry only — textures are left untouched (no sharp dependency, no perceptual
-// re-encode) so the pass is fast and deterministic and never changes how the model
-// looks beyond standard vertex quantization. The heavy codecs (Draco wasm, the
-// meshopt encoder) are imported lazily inside compressGlb() so a plain `glb`
-// request — the default — never pays to load them.
+// Geometry is always handled. Textures are opt-in through `textures`: on a raw
+// generation the embedded PNG skins, not the vertex data, are what push a mesh
+// past 8 MB, so the delivery path (compressGlbForDelivery below) turns them into
+// WebP and caps their resolution while a bare `output_format: glb-draco` request
+// still gets the fast, deterministic geometry-only pass. The heavy codecs (Draco
+// wasm, the meshopt encoder, sharp) are imported lazily inside compressGlb() so a
+// plain `glb` request never pays to load them.
import { Buffer } from 'node:buffer';
@@ -43,13 +45,23 @@ async function ioFor(mode) {
return io;
}
+// Texture ceiling for the delivery pass. A 4096x4096 albedo costs a phone four
+// times the decode time and GPU memory of a 2048 one and is indistinguishable on
+// a 6-inch screen, so the delivery preset caps the long edge here. Raw geometry
+// requests are unaffected (textures default to off).
+export const DELIVERY_TEXTURE_MAX_PX = 2048;
+export const DELIVERY_TEXTURE_QUALITY = 90;
+
/**
- * Compress a GLB's geometry. Returns the compressed buffer plus size stats.
- * Throws on an unparseable buffer or an unknown mode so the caller can fall back
- * to delivering the original, uncompressed mesh.
+ * Compress a GLB. Returns the compressed buffer plus size stats. Throws on an
+ * unparseable buffer or an unknown mode so the caller can fall back to
+ * delivering the original, uncompressed mesh.
*
* @param {Buffer|Uint8Array} buf - source GLB bytes
- * @param {{ mode?: 'draco' | 'meshopt' }} [opts]
+ * @param {{
+ * mode?: 'draco' | 'meshopt',
+ * textures?: false | { quality?: number, maxSize?: number },
+ * }} [opts]
* @returns {Promise<{
* buffer: Buffer,
* mode: 'draco' | 'meshopt',
@@ -58,9 +70,10 @@ async function ioFor(mode) {
* ratio: number, // outputBytes / inputBytes
* grew: boolean, // true if compression didn't shrink (tiny meshes)
* extensionsUsed: string[],
+ * textures: boolean, // whether the texture pass ran
* }>}
*/
-export async function compressGlb(buf, { mode = 'meshopt' } = {}) {
+export async function compressGlb(buf, { mode = 'meshopt', textures = false } = {}) {
if (!COMPRESSION_MODES.includes(mode)) {
throw new Error(`unsupported compression mode: ${mode}`);
}
@@ -78,6 +91,21 @@ export async function compressGlb(buf, { mode = 'meshopt' } = {}) {
// dedup + prune first (drop duplicate/orphaned data), then weld to an indexed
// mesh (both codecs need shared vertices), then the codec-specific encode.
const steps = [dedup(), prune(), weld()];
+ // Textures BEFORE the codec: re-encoding an image is independent of vertex
+ // layout, and running it first means the codec pass writes its buffers once
+ // over already-final image data instead of being re-serialised afterwards.
+ if (textures) {
+ const { textureCompress } = await import('@gltf-transform/functions');
+ const sharpMod = await import('sharp');
+ steps.push(
+ textureCompress({
+ encoder: sharpMod.default ?? sharpMod,
+ targetFormat: 'webp',
+ quality: textures.quality ?? DELIVERY_TEXTURE_QUALITY,
+ resize: [textures.maxSize ?? DELIVERY_TEXTURE_MAX_PX, textures.maxSize ?? DELIVERY_TEXTURE_MAX_PX],
+ }),
+ );
+ }
if (mode === 'draco') {
steps.push(draco());
} else {
@@ -101,5 +129,18 @@ export async function compressGlb(buf, { mode = 'meshopt' } = {}) {
ratio: inputBytes > 0 ? Math.round((outputBytes / inputBytes) * 1000) / 1000 : 1,
grew: outputBytes >= inputBytes,
extensionsUsed,
+ textures: Boolean(textures),
+ };
+}
+
+// The preset the serve path uses. Geometry through meshopt (the viewer's loader
+// is decoder-equipped, and meshopt decodes on the GPU far faster than Draco) plus
+// the texture pass, which is where the bytes actually are on a raw generation.
+// Kept here rather than at the call site so every writer of a served mesh gets
+// the same contract and a future change lands in one place.
+export function deliveryCompressionOptions() {
+ return {
+ mode: 'meshopt',
+ textures: { quality: DELIVERY_TEXTURE_QUALITY, maxSize: DELIVERY_TEXTURE_MAX_PX },
};
}