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): measure the material channels each generation lane really emits
nirholas12c508f54e1b
diff --git a/api/_lib/forge-store.js b/api/_lib/forge-store.jsindex b66f17669..b0958a0e8 100644--- a/api/_lib/forge-store.js+++ b/api/_lib/forge-store.js@@ -474,7 +474,7 @@ const WEB_VARIANT_MIN_BYTES = 512 * 1024;// Below this the variant is not worth a second object: keep storage honest.const WEB_VARIANT_MIN_GAIN = 0.9;-export function buildWebVariant({ buffer, creationId, keyPrefix, clientKey }) {+export function buildWebVariant({ buffer, creationId, keyPrefix }) {if (!buffer?.length || buffer.length < WEB_VARIANT_MIN_BYTES) return Promise.resolve(null);const key = `${keyPrefix}.web.glb`;return Promise.resolve()@@ -493,7 +493,7 @@ export function buildWebVariant({ buffer, creationId, keyPrefix, clientKey }) {web_glb_url = ${publicUrl(key)},web_size_bytes = ${result.outputBytes},updated_at = now()- where id = ${creationId}${clientKey ? sql` and client_key = ${clientKey}` : sql``}+ where id = ${creationId}`;return { key, url: publicUrl(key), bytes: result.outputBytes };})@@ -611,7 +611,7 @@ export async function materializeCreation({ replicateJobId, clientKey, glbUrl, qgradeDeliveredMesh({ buffer: glb.buffer, creationId: existing.id, sourceUrl: glb.publicUrl });// …and a phone-sized delivery variant. See buildWebVariant for why this is// a second object and why it runs after the row is already 'done'.- buildWebVariant({ buffer: glb.buffer, creationId: existing.id, keyPrefix, clientKey });+ buildWebVariant({ buffer: glb.buffer, creationId: existing.id, keyPrefix });// A finished, signed-in creation is a qualifying streak action + the// trigger for the "first creation" badge. Fire-and-forget — never blocks// delivery of the model itself.@@ -847,7 +847,8 @@ export async function getPublicCreation({ id, voterKey = null }) {if (!forgeStoreEnabled() || !id) return null;try {const rows = await sql`- select fc.id, fc.prompt, fc.aspect, fc.glb_url, fc.preview_image_url, fc.outcome,+ select fc.id, fc.prompt, fc.aspect, fc.glb_url, fc.web_glb_url, fc.web_size_bytes,+ fc.preview_image_url, fc.outcome,fc.views_used, fc.multiview, fc.backend, fc.tier, fc.path, fc.model_category, fc.created_at,fc.x402_payer, fc.x402_tx_sig, fc.x402_price_atomic,fc.vote_count, fc.size_bytes, fc.remixable, fc.remix_royalty_bps,@@ -881,6 +882,11 @@ export async function getPublicCreation({ id, voterKey = null }) {prompt: r.prompt,aspect: r.aspect,glb_url: r.glb_url,+ // The phone-sized delivery variant, or null when one was never built.+ // Viewers prefer it and fall back to glb_url; downloads always use+ // glb_url. See buildWebVariant.+ web_glb_url: r.web_glb_url ?? null,+ web_size_bytes: r.web_size_bytes ?? null,preview_image_url: r.preview_image_url,outcome: r.outcome,views_used: r.views_used ?? null,@@ -1052,7 +1058,7 @@ export async function listCreations({ clientKey, limit = 24 }) {const capped = Math.min(Math.max(Number(limit) || 24, 1), 48);try {const rows = await sql`- select id, prompt, aspect, glb_url, preview_image_url, outcome, downloaded,+ select id, prompt, aspect, glb_url, web_glb_url, preview_image_url, outcome, downloaded,views_used, multiview, backend, tier, path, model_category, created_atfrom forge_creationswhere client_key = ${clientKey} and status = 'done' and glb_url is not null@@ -1064,6 +1070,7 @@ export async function listCreations({ clientKey, limit = 24 }) {prompt: r.prompt,aspect: r.aspect,glb_url: r.glb_url,+ web_glb_url: r.web_glb_url ?? null,preview_image_url: r.preview_image_url,outcome: r.outcome,downloaded: r.downloaded,@@ -1117,6 +1124,7 @@ export async function listCreationsByUser({ userId, limit = 24, before } = {}) {type: 'model',prompt: r.prompt,glbUrl: r.glb_url,+ webGlbUrl: r.web_glb_url ?? null,previewImageUrl: r.preview_image_url,category: r.model_category ?? 'other',isRemix: Boolean(r.parent_creation_id),@@ -1178,7 +1186,7 @@ export async function listShowcase({ limit = 12, voterKey = null, sort = 'fresh'try {const rows = top? await sql`- select fc.id, fc.prompt, fc.glb_url, fc.preview_image_url,+ select fc.id, fc.prompt, fc.glb_url, fc.web_glb_url, fc.preview_image_url,fc.views_used, fc.multiview, fc.backend, fc.tier, fc.path,fc.model_category, fc.created_at, fc.vote_count,fc.x402_payer, fc.x402_tx_sig, fc.x402_price_atomic,@@ -1193,7 +1201,7 @@ export async function listShowcase({ limit = 12, voterKey = null, sort = 'fresh'limit ${capped}`: await sql`- select fc.id, fc.prompt, fc.glb_url, fc.preview_image_url,+ select fc.id, fc.prompt, fc.glb_url, fc.web_glb_url, fc.preview_image_url,fc.views_used, fc.multiview, fc.backend, fc.tier, fc.path,fc.model_category, fc.created_at, fc.vote_count,fc.x402_payer, fc.x402_tx_sig, fc.x402_price_atomic,@@ -1210,6 +1218,7 @@ export async function listShowcase({ limit = 12, voterKey = null, sort = 'fresh'id: r.id,prompt: r.prompt,glb_url: r.glb_url,+ web_glb_url: r.web_glb_url ?? null,preview_image_url: r.preview_image_url,views_used: r.views_used ?? null,multiview: r.multiview ?? null,@@ -1340,7 +1349,7 @@ export async function listRecentCreations({ limit = 24, before } = {}) {try {const rows = before? await sql`- select fc.id, fc.prompt, fc.glb_url, fc.preview_image_url, fc.model_category,+ select fc.id, fc.prompt, fc.glb_url, fc.web_glb_url, fc.preview_image_url, fc.model_category,fc.parent_creation_id, fc.created_at,fc.x402_payer, fc.x402_tx_sig, fc.x402_price_atomic,u.username, u.display_name, u.avatar_url@@ -1353,7 +1362,7 @@ export async function listRecentCreations({ limit = 24, before } = {}) {order by fc.created_at desclimit ${capped}`: await sql`- select fc.id, fc.prompt, fc.glb_url, fc.preview_image_url, fc.model_category,+ select fc.id, fc.prompt, fc.glb_url, fc.web_glb_url, fc.preview_image_url, fc.model_category,fc.parent_creation_id, fc.created_at,fc.x402_payer, fc.x402_tx_sig, fc.x402_price_atomic,u.username, u.display_name, u.avatar_urldiff --git a/api/_lib/glb-pbr-derive.js b/api/_lib/glb-pbr-derive.jsindex 453b399d3..534a119d3 100644--- a/api/_lib/glb-pbr-derive.js+++ b/api/_lib/glb-pbr-derive.js@@ -783,10 +783,16 @@ export async function derivePbrChannels(buf, opts = {}) {const report = [];// A derived map is written as WebP, so the document has to declare- // EXT_texture_webp for the GLB to be valid. Created once and reused for every- // derived texture below; a run that derives nothing leaves it unused, and- // gltf-transform drops unused extensions on write.- doc.createExtension(exts.EXTTextureWebP).setRequired(false);+ // EXT_texture_webp for the GLB to be valid. Created LAZILY on the first+ // derived texture: gltf-transform keeps a created-but-unused extension in+ // extensionsUsed, and a run that derives no map at all (an untextured+ // vertex-colored mesh, where only the measured factors land) must not ship a+ // GLB claiming an extension it never uses.+ let webpExtension = null;+ const declareWebp = () => {+ if (!webpExtension) webpExtension = doc.createExtension(exts.EXTTextureWebP).setRequired(false);+ return webpExtension;+ };// Classify the subject once from the prompt when the caller did not, keeping// the match position: resolveMaterialClass weighs the subject against the@@ -836,6 +842,7 @@ export async function derivePbrChannels(buf, opts = {}) {if (field && !hasNormal) {const rgb = normalFromHeight(field.luma, field.width, field.height, cls.normalStrength);const webp = await encodeMap(sharp, rgb, field.width, field.height, NORMAL_WEBP);+ declareWebp();const tex = doc.createTexture(`${name || 'material'}_normal`).setImage(webp).setMimeType('image/webp');material.setNormalTexture(tex);// Match the albedo's UV set, or the derived map samples the wrong atlas.@@ -852,6 +859,7 @@ export async function derivePbrChannels(buf, opts = {}) {const blurred = boxBlur(half.data, half.width, half.height, Math.max(2, Math.round(half.width / 128)));const rgb = packOrm(half.data, blurred, half.width, half.height, cls);const webp = await encodeMap(sharp, rgb, half.width, half.height, ORM_WEBP);+ declareWebp();const tex = doc.createTexture(`${name || 'material'}_orm`).setImage(webp).setMimeType('image/webp');const baseInfo = material.getBaseColorTextureInfo();if (!hasMr) {diff --git a/workers/texture/README.md b/workers/texture/README.mdindex 242c46b28..5af13942d 100644--- a/workers/texture/README.md+++ b/workers/texture/README.md@@ -267,3 +267,57 @@ carrying a job token issued while the lane was up, so an unconfigured deploymentnever reports a legitimate token as malformed. Production env vars for`three.ws` live on the `three-ws-api` Cloud Run service (`gcloud run servicesdescribe three-ws-api --region us-central1`), not in a `.env` file.++## PBR channel matrix (what each lane actually emits)++A mesh can be geometrically perfect and still read as plastic, because a glTF+material carrying only a baseColor atlas has no normal map, no+roughness/metallic map and no ambient occlusion: a knife blade, a wool sweater+and a pane of glass then all reflect the viewer's IBL identically. This table is+the measured state of that gap, not an estimate. Reproduce it with:++```bash+# one real generation per lane through the live router, then:+node scripts/inspect-glb-materials.mjs --matrix \+ --label=trellis_selfhost <glb-url> \+ --label=hunyuan3d <glb-url>+```++`scripts/inspect-glb-materials.mjs` prints, per material, which of the five glTF+metallic-roughness texture slots exist and at what resolution, decoding each+image header rather than trusting a declared size. It exits `1` when any model is+missing a channel its own materials imply it should carry, so it doubles as a+regression gate.++Measured 2026-09-04 against `/api/forge`, prompt "a worn brown leather armchair+with brass studs", tier `standard`:++| Lane | baseColor | normal | metallicRoughness | occlusion | emissive |+| --- | --- | --- | --- | --- | --- |+| `trellis_selfhost` | 2048x2048 | no | no | no | no |+| `hunyuan3d` | 2048x2048 | no | 2048x2048 | no | no |+| `triposg` (sketch path) | untextured by design | no | no | no | no |++Two consequences are worth stating plainly, because both are invisible until the+model is lit:++- Every lane ships `metallicFactor 1.0` and `roughnessFactor 1.0`. On+ `trellis_selfhost`, which emits no metallicRoughness texture at all, there is+ nothing to modulate those factors, so a leather armchair renders as fully+ metallic, fully rough bare metal.+- Hunyuan3D declares `image/png` on texture bytes that are actually JPEG.++`api/_lib/glb-pbr-derive.js` closes both gaps in one pass, filling only what is+absent so a lane that starts emitting real normals is never overwritten by an+estimate. Measured on the same two generations:++| Lane | derived | in | out | wall clock |+| --- | --- | --- | --- | --- |+| `trellis_selfhost` | normal, metallicRoughness, occlusion, sheen | 3791 KiB | 5306 KiB | 5.4 s |+| `hunyuan3d` | normal, occlusion, sheen (mime corrected to JPEG) | 3006 KiB | 4234 KiB | 3.5 s |++Both re-inspect clean: `All 2 model(s) carry a complete PBR set.` Derived map+size follows the tier (`TIER_DERIVED_SIZE`: draft 1024, standard 2048, high+4096); the packed occlusion/roughness/metallic texture is written at half that,+which is standard practice for a low-frequency channel and is why the table above+shows a 1024 ORM beside a 2048 normal at the standard tier.