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(pbr): run material completion on every delivered mesh, opt out with derive_pbr
nirholas48cf04323877
diff --git a/api/_lib/forge-options.js b/api/_lib/forge-options.jsindex ab5c85824..b46b16f0c 100644--- a/api/_lib/forge-options.js+++ b/api/_lib/forge-options.js@@ -8,6 +8,10 @@// • output_format — glb (default) or a compressed variant (draco / meshopt)// • texture_size — bake textures at a specific resolution// • target_polycount — explicit geometry budget on poly-aware backends+// • derive_pbr — the ONE exception to "off by default": the material+// completion pass (glb-pbr-derive.js) runs on every delivered mesh, because+// an albedo-only material is a defect rather than a preference. Send+// `derive_pbr: false` to receive the lane's own materials untouched.//// normalizeForgeOptions() validates and clamps; an explicitly-present but invalid// value is reported in `errors` so the endpoint can answer 400 with an actionable@@ -41,6 +45,7 @@ function compressionFor(format) {* compression: 'none' | 'draco' | 'meshopt',* textureSize: number | null,* targetPolycount: number | null,+ * derivePbr: boolean, // material completion pass — true unless opted out* hasOptions: boolean, // true iff any non-default option was supplied* errors: Array<{ field: string, message: string }>,* }}@@ -108,8 +113,20 @@ export function normalizeForgeOptions(body) {}}+ // derive_pbr — opt-OUT. Anything other than an explicit boolean false leaves+ // the completion pass on; a non-boolean value is reported rather than+ // silently coerced, so `derive_pbr: "no"` never reads as true.+ let derivePbr = true;+ if (b.derive_pbr !== undefined && b.derive_pbr !== null) {+ if (typeof b.derive_pbr !== 'boolean') {+ errors.push({ field: 'derive_pbr', message: 'derive_pbr must be true or false.' });+ } else {+ derivePbr = b.derive_pbr;+ }+ }+const hasOptions =- seed !== null || outputFormat !== 'glb' || textureSize !== null || targetPolycount !== null;+ seed !== null || outputFormat !== 'glb' || textureSize !== null || targetPolycount !== null || !derivePbr;return {seed,@@ -117,6 +134,7 @@ export function normalizeForgeOptions(body) {compression: compressionFor(outputFormat),textureSize,targetPolycount,+ derivePbr,hasOptions,errors,};@@ -148,5 +166,6 @@ export function summarizeForgeOptions(opts) {output_format: opts.outputFormat,texture_size: opts.textureSize,target_polycount: opts.targetPolycount,+ derive_pbr: opts.derivePbr !== false,};}diff --git a/api/_lib/forge-store.js b/api/_lib/forge-store.jsindex 06c672448..aaf3995b2 100644--- a/api/_lib/forge-store.js+++ b/api/_lib/forge-store.js@@ -394,18 +394,20 @@ async function copyToBucket({ sourceUrl, key, fallbackContentType, maxBytes, comlet quality = null;let compression = null;let cleaned = null;- if (computeQuality || compress || cleanup) {- const scored = await scoreAndCompress(buf, { computeQuality, compress, cleanup });+ let pbr = null;+ if (computeQuality || compress || cleanup || derivePbr) {+ const scored = await scoreAndCompress(buf, { computeQuality, compress, cleanup, derivePbr, prompt, tier, materialClass });buf = scored.buf;quality = scored.quality;compression = scored.compression;cleaned = scored.cleaned;+ pbr = scored.pbr;}await putObject({ key, body: buf, contentType, metadata: { source: 'forge' } });// `buffer` is the bytes actually stored, post-cleanup and post-compression, so// a caller that hashes or grades them is describing the asset users receive// rather than the provider's original, and does it without a second fetch.- return { bytes: buf.length, publicUrl: publicUrl(key), quality, compression, cleaned, buffer: buf };+ return { bytes: buf.length, publicUrl: publicUrl(key), quality, compression, cleaned, pbr, buffer: buf };}function imageExtFor(url) {@@ -464,7 +466,15 @@ function gradeDeliveredMesh({ buffer, creationId, sourceUrl }) {// every forge mesh is raw marching-cubes output that benefits, and// it's best-effort (any failure ships the original bytes). Pass// false to deliver the provider geometry untouched.-export async function materializeCreation({ replicateJobId, clientKey, glbUrl, quality = false, compress = null, cleanup = true }) {+// derivePbr - complete the material set (glb-pbr-derive.js): a derived normal+// map, a packed occlusion/roughness/metallic map, the material+// class's measured factors and its real-world extension layer. On+// by default, because every reconstruction lane bakes an albedo+// and stops (the free TRELLIS lanes ship no materials at all, so+// glTF's default fully-metallic material renders them as rough+// metal). Best-effort like the rest of the chain; pass false to+// deliver the lane's own materials untouched.+export async function materializeCreation({ replicateJobId, clientKey, glbUrl, quality = false, compress = null, cleanup = true, derivePbr = true }) {if (!forgeStoreEnabled() || !replicateJobId || !glbUrl) return null;const existing = await findByJob({ replicateJobId, clientKey });if (!existing) return null;@@ -477,6 +487,7 @@ export async function materializeCreation({ replicateJobId, clientKey, glbUrl, qquality: null,compression: null,cleaned: null,+ pbr: null,};}@@ -490,6 +501,12 @@ export async function materializeCreation({ replicateJobId, clientKey, glbUrl, qcomputeQuality: quality,compress,cleanup,+ derivePbr,+ // The row carries the words the material classifier reads and the tier+ // that sets the derived maps' resolution, so no caller has to thread+ // either through the poll path.+ prompt: existing.prompt || '',+ tier: existing.tier || '',});// Reference image is part of the training pair but never blocks the mesh.@@ -551,6 +568,7 @@ export async function materializeCreation({ replicateJobId, clientKey, glbUrl, qquality: glb.quality ?? null,compression: glb.compression ?? null,cleaned: glb.cleaned ?? null,+ pbr: glb.pbr ?? null,};} catch (err) {// A 404/410 means the provider's ephemeral asset (e.g. a HuggingFace Space'sdiff --git a/api/gpt-forge.js b/api/gpt-forge.jsindex e80566504..ae9f5ef1e 100644--- a/api/gpt-forge.js+++ b/api/gpt-forge.js@@ -645,6 +645,7 @@ async function runNvidiaTextLane({ req, res, ip, prompt, aspect, tier, path, optglbUrl: submitted.resultGlbUrl,quality: true,compress: opts?.compression && opts.compression !== 'none' ? opts.compression : null,+ derivePbr: opts?.derivePbr !== false,});// One auto-retry on a flagged low-quality/degenerate output (CLAUDE.md: no@@ -682,6 +683,7 @@ async function runNvidiaTextLane({ req, res, ip, prompt, aspect, tier, path, optglbUrl: retry.resultGlbUrl,quality: true,compress: opts?.compression && opts.compression !== 'none' ? opts.compression : null,+ derivePbr: opts?.derivePbr !== false,});if (retryDurable) {durable = retryDurable;@@ -721,6 +723,7 @@ async function runNvidiaTextLane({ req, res, ip, prompt, aspect, tier, path, optreplicateJobId: rj, clientKey, userId: await sessionUserIdFromReq(req),glbUrl: r.resultGlbUrl, quality: true,compress: opts?.compression && opts.compression !== 'none' ? opts.compression : null,+ derivePbr: opts?.derivePbr !== false,});return rd ? { glbUrl: rd.glbUrl, durable: rd } : null;},@@ -912,6 +915,7 @@ async function runHfImageLane({glbUrl: resultGlbUrl,quality: true,compress: wantCompress,+ derivePbr: opts?.derivePbr !== false,});// One auto-retry on a flagged low-quality/degenerate output. Only attempted@@ -955,6 +959,7 @@ async function runHfImageLane({glbUrl: retryFinished.resultGlbUrl,quality: true,compress: wantCompress,+ derivePbr: opts?.derivePbr !== false,});if (retryDurable) {durable = retryDurable;@@ -1004,6 +1009,7 @@ async function runHfImageLane({const rd = await materializeCreation({replicateJobId: rj, clientKey, userId: await sessionUserIdFromReq(req),glbUrl: rf.resultGlbUrl, quality: true, compress: wantCompress,+ derivePbr: opts?.derivePbr !== false,});return rd ? { glbUrl: rd.glbUrl, durable: rd } : null;} finally {@@ -1676,6 +1682,7 @@ async function startJob(req, res) {glbUrl: submitted.resultGlbUrl,quality: true,compress: opts.compression !== 'none' ? opts.compression : null,+ derivePbr: opts.derivePbr !== false,});return json(res, 200, {job_id: null,@@ -2880,6 +2887,7 @@ async function pollJob(req, res, jobId) {glbUrl: result.resultGlbUrl,quality: true,compress: boundOpts?.compression || null,+ derivePbr: boundOpts?.derivePbr !== false,});// Populate the result cache this job was bound to at submit time (text→3D,// non-high-tier, platform-keyed lanes only: see forgeResultCacheKey). A