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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
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.jsindex 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 = falseconsole.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 = falsecompression = { 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 thatdiff --git a/api/_lib/glb-compress.js b/api/_lib/glb-compress.jsindex 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 },};}