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(pbr): measure the material channels each generation lane really emits

nirholas12c508f54e1b
diff --git a/api/_lib/forge-store.js b/api/_lib/forge-store.js
index 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, q
gradeDeliveredMesh({ 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_at
from forge_creations
where 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 desc
limit ${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_url
diff --git a/api/_lib/glb-pbr-derive.js b/api/_lib/glb-pbr-derive.js
index 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.md
index 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 deployment
never reports a legitimate token as malformed. Production env vars for
`three.ws` live on the `three-ws-api` Cloud Run service (`gcloud run services
describe 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.