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
docs(forge): document target_faces, bbox, and pose options plus /api/forge-batch
nirholasd98218c90679
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 48f8941e1..d17f0bbca 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -17,6 +17,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **Companion presence: sustained mood, emoji-driven expression, an LLM gesture tool, active-listening nods, and real multi-language lip-sync**: Agent avatars carry more of what makes a companion feel present. setMood(valence, arousal) sets a sustained resting bias (a soft smile or a worried brow that drifts in over about a second) on top of the existing per-utterance emotion blend, and a reply that is nothing but emoji (no English sentiment words at all) now drives a real expression change instead of staying neutral, because the built-in sentiment scorer reads emoji as direct valence/arousal signal. The LLM brain gets a general-purpose `gesture` tool covering all 19 body-language slots (nod, shake, shrug, bow, point, think, and the rest), so it can react physically mid-turn instead of only through a skill or an emotion threshold. While a real VAD/STT signal says the user is talking, the avatar nods on a fixed cadence to show it is listening, and stops the moment they stop. ElevenLabs text-to-speech now drives lip-sync from the provider's real per-character timestamps (any language the voice speaks), falling back to the energy-based analyser only if that call fails, so mouth shapes track what is actually being said instead of approximating it from amplitude alone. (`/docs/agent-system`) `[feature, improvement]`- **Engine QA: a free real-time-engine fitness grade, plus real LOD chains**: A new free grade answers the question a game engine's import step asks that neither glTF validation nor simulation readiness does: draw calls, material count, texel density against the mesh's real-world size, a per-level triangle budget for a LOD chain, and whether the mesh is cheap and closed enough to use as its own physics collider. GET/POST /api/3d/engine-qa grades any public GLB (format=stl exports a watertight mesh for printing); the same browser-only checks run with zero network cost in Rig Doctor, and the full grade with a one-click upgrade in the GLB viewer, through a shared <engine-qa> panel component. The underlying LOD builder (packages/glb-tools's buildLodChain, real meshoptimizer decimation tagged with MSFT_lod) is now also available on generation: send { "lods": true } to POST /api/forge and the finished creation gets a combined LOD-chain variant alongside its delivered mesh, the same opt-in, fire-and-forget pattern as the existing web-delivery variant. (`/docs/engine-qa`) `[feature]`- **Every generated and purchased model now ships with a signed provenance credential, free, by default**: Content credentials (specs/PROVENANCE_3D.md) used to be an on-demand, Claude-track action: you had to call anchor_provenance to get one. Now every GLB the Forge produces, across every generation lane (free NIM, Forge Pro, rigged avatars, self-host TRELLIS/Hunyuan, async GCP workers), gets an ed25519-signed content credential the moment it's materialized, and every first download of a paid asset from the x402 asset bazaar gets one too, with the hash and a verify link returned right in the download response. Signing and storage are free and local, no Solana write and no spend, so there's nothing to gate; the separate paid anchor_provenance upgrade, which additionally commits the hash on-chain, is untouched and still available. A credential is keyed by content hash, so it's issued exactly once per file no matter how many times a lane or endpoint touches it. Model pages now show the same verified / tampered / unverified badge the 3D viewer already had, and a third party can check any model for free with GET /api/provenance. The owner can turn automatic issuance off platform-wide with PROVENANCE_AUTO_DISABLE=true; nothing else about verification changes if they do. (`/docs/provenance`) `[feature, security]`+- **Forge generation controls (target faces, bbox fit, rest pose) and a batch endpoint for fanning out N generations**: POST /api/forge and /api/x402/forge take three new, off-by-default controls: target_faces (alias of target_polycount) pins an explicit geometry budget on poly-aware backends; bbox: [x, y, z] uniformly rescales the delivered mesh to fit a box in meters, lane-agnostic since it runs as a post-generation GLB fit; pose: "t" | "a" requests a rest pose on backends without a caller-supplied reference image, with pose_applied echoed back so a photo-conditioned lane never silently ignores it. A new POST /api/forge-batch fans one call out to up to 8 independent /api/forge submissions, concurrency-capped by the caller's $THREE holder tier, and GET /api/forge-batch?batch=<id> polls the group: one item's failure never fails the batch, and group state is best-effort Redis so a job already returned stays pollable at /api/forge?job= even if the group expires. The Workbench's Generate Mesh node now exposes rest pose and width/height/depth bbox fields alongside the existing face budget, and a new Batch drawer (toolbar icon, or press B) queues up to 8 prompts at once against the new endpoint and opens any finished item straight into the viewport. (`/docs/forge`) `[feature, improvement]`- **Real VRM avatars: spring bones, expressions, and .vrma clips via @pixiv/three-vrm**: The hand-rolled VRM loader is gone. vrm-boot.js now registers the real VRMLoaderPlugin (@pixiv/three-vrm) on the three.ws GLTFLoader, so VRM 0.x and 1.0 avatars get genuine MToon materials, spring-bone physics, node constraints, look-at, and all 18 expression presets, driven live by vrm.update(delta) in AnimationManager and mapped onto the ARKit-52 face-capture driver. VRMAnimationLoaderPlugin loads .vrma clips into the same retargeting pipeline that drives non-VRM humanoids, so a single clip plays on either. The Ready Player Me import page (/import-rpm) now accepts .vrm files alongside .glb, and a long-standing bug that 400'd every import at the final save step (it sent an invalid source value) is fixed. docs/avatar-engines.md upgrades three-vrm from interop to live. (`/docs/avatar-engines`) `[feature, fix]`- **Restyle and part edits now prove they kept the rig, not just claim it**: Material Studio's AI restyle and seeded colorway variants, plus Restyle Studio's HoloPart "Regenerate part" tool, are now checked against their own source bytes with @three-ws/glb-diff before anything is persisted: a restyle declares it keeps topology, UVs, skeleton, skin, and clips, a part regenerate declares the narrower skeleton-and-clips promise since the part's own shape is meant to change, and the operation throws instead of returning a URL if the real diff shows otherwise. A successful restyle response now carries preserve: { kinds, verified: true } as evidence. Model Diff's underlying engine (packages/glb-diff) grew three independent mesh sub-hashes, topology, uv, and skinWeights, so a caller can tell which kind of change happened instead of one opaque geometry hash, and every lineage step in Restyle Studio that has a parent now shows a "Diff" link that opens Model Diff pre-loaded with that exact before/after pair. Regenerating a part also now mints its own durable lineage version automatically, closing a gap where part edits were not recorded. (`/restyle`) `[feature, improvement]`- **Scene Studio: an Agent tab that edits your open scene by prompt, plus a TSL node material editor**: Scene Studio's sidebar grows two tabs. Agent is a chat panel that reads the open scene and drives it with the same real editor.execute(Command) calls the toolbar and menus use (free, keyless, rate-limited model via POST /api/scene/agent): add a primitive or a Forge-generated object, move/rotate/scale a named object, recolor a material. Every mutating prompt pushes a numbered version (a scene snapshot plus a viewport screenshot); clicking an earlier version restores it as one more undoable edit, so a bad restore is one Ctrl+Z away like any other mistake. Nodes is a dropdown-wired TSL (Three.js Shading Language) material graph editor for the selected object: build a graph from UV, time, color, texture, and math nodes as a reorderable card list, no canvas or wires to route, and apply it to swap in a real node material through the same undo-able command path. Fixed along the way: restoring a version used to append the snapshot's objects on top of the current scene instead of replacing them (SetSceneCommand, the vendored editor's own scene-import command, only ever adds); and the site-wide corner-stack widget could sit on top of the Agent tab's version-restore buttons and eat the click, now suppressed while the studio is open. (`/scene`) `[feature, fix]`diff --git a/data/changelog.json b/data/changelog.jsonindex 2b4271a60..af0714b4b 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -1,6 +1,16 @@{"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.","entries": [+ {+ "date": "2026-10-12",+ "title": "Forge generation controls (target faces, bbox fit, rest pose) and a batch endpoint for fanning out N generations",+ "link": "/docs/forge",+ "summary": "POST /api/forge and /api/x402/forge take three new, off-by-default controls: target_faces (alias of target_polycount) pins an explicit geometry budget on poly-aware backends; bbox: [x, y, z] uniformly rescales the delivered mesh to fit a box in meters, lane-agnostic since it runs as a post-generation GLB fit; pose: \"t\" | \"a\" requests a rest pose on backends without a caller-supplied reference image, with pose_applied echoed back so a photo-conditioned lane never silently ignores it. A new POST /api/forge-batch fans one call out to up to 8 independent /api/forge submissions, concurrency-capped by the caller's $THREE holder tier, and GET /api/forge-batch?batch=<id> polls the group: one item's failure never fails the batch, and group state is best-effort Redis so a job already returned stays pollable at /api/forge?job= even if the group expires. The Workbench's Generate Mesh node now exposes rest pose and width/height/depth bbox fields alongside the existing face budget, and a new Batch drawer (toolbar icon, or press B) queues up to 8 prompts at once against the new endpoint and opens any finished item straight into the viewport.",+ "tags": [+ "feature",+ "improvement"+ ]+ },{"date": "2026-10-12","title": "Companion presence: sustained mood, emoji-driven expression, an LLM gesture tool, active-listening nods, and real multi-language lip-sync",diff --git a/docs/forge.md b/docs/forge.mdindex 846ca4ad8..c77bd2fab 100644--- a/docs/forge.md+++ b/docs/forge.md@@ -439,6 +439,94 @@ while (job.status !== 'done' && job.status !== 'failed') {console.log(job.glb_url); // downloadable, textured GLB```+## Generation controls++`POST /api/forge` and `POST /api/x402/forge` accept a handful of optional,+additive controls beyond `prompt`/`image_urls`/`tier`/`backend`. Every one is+off by default: a request that omits all of them behaves exactly as it did+before these existed.++| Field | Type | What it does |+|---|---|---|+| `target_polycount` (alias `target_faces`) | integer | Explicit geometry budget on poly-aware backends. Only honored by backends with `polyControl: true` in the engine catalog (`GET /api/forge?catalog=1`); others ignore it and the response says so. |+| `bbox` | `[x, y, z]` meters | The delivered mesh is uniformly rescaled to fit inside this box (aspect ratio preserved), centered on X/Z and floored at Y=0. Lane-agnostic: applied as a post-generation fit to the final GLB, so every backend honors it. |+| `pose` | `"t"` \| `"a"` | Requested rest pose for a humanoid/character subject. Only backends without a caller-supplied reference image can honor this (`poseControl: true`); a photo-conditioned lane reports `pose_applied: false` rather than silently ignoring the field. |+| `output_format` | `"glb"` \| `"glb-meshopt"` \| `"glb-draco"` | Compress the delivered GLB. |+| `texture_size` | integer (px) | Bake textures at a specific resolution instead of the tier default. |+| `seed` | integer | Reproducibility: the same seed, prompt and params reproduce the same mesh on backends that support it. |++```bash+# Target a 20k-triangle mesh, fit it into a 1.8m-tall box, and request a T-pose.+curl -X POST 'https://three.ws/api/forge' \+ -H 'content-type: application/json' \+ -d '{+ "prompt": "a low-poly adventurer",+ "tier": "standard",+ "target_faces": 20000,+ "bbox": [1.0, 1.8, 0.6],+ "pose": "t"+ }'+```++The done response's `options` object echoes what was actually requested+and, for `pose`, whether the chosen backend could honor it:++```json+{ "status": "done", "glb_url": "https://…/model.glb",+ "options": {+ "target_polycount": 20000, "target_faces": 20000,+ "bbox": [1.0, 1.8, 0.6], "pose": "t", "pose_applied": true+ } }+```++An invalid value (e.g. `pose: "sitting"`, or a non-positive `bbox` entry)+answers `400` naming the field rather than silently dropping it.++## Batch generation++**`POST /api/forge-batch`** fans one call out to up to 8 independent+`/api/forge` submissions and tracks them as a group, for building a set of+variations or a small asset pack without a client-side submit loop. Each+item is a full `/api/forge` body (any mix of prompts, images, tiers,+engines or the generation controls above); every item still runs through+`/api/forge`'s own gating and billing unchanged, so a batch never bypasses+the per-item tier rules.++```bash+curl -X POST 'https://three.ws/api/forge-batch' \+ -H 'content-type: application/json' \+ -d '{+ "items": [+ { "prompt": "a wooden crate", "tier": "draft" },+ { "prompt": "a steel crate, battle-damaged", "tier": "draft" },+ { "prompt": "a crystal crate, glowing", "tier": "draft" }+ ]+ }'+# → 200 { "batch_id": "...", "status": "queued",+# "items": [{ "index": 0, "ok": true, "job_id": "...", "status": "queued" }, ...] }+```++Poll the group on the same batch id; each item carries its own status and,+once ready, its own `glb_url`:++```bash+curl 'https://three.ws/api/forge-batch?batch=<BATCH_ID>'+# → 200 { "batch_id": "...", "status": "done"|"partial"|"running"|"queued",+# "items": [{ "index": 0, "ok": true, "status": "done", "glb_url": "..." }, ...] }+```++Group `status` is `"done"` only once every item succeeded; `"partial"` once+every item is terminal but at least one failed. One item's failure never+fails the batch: the response always carries every other item's own result,+with a structured `error`/`message` on the failed one. A batch group lives+for an hour; an expired or unknown `batch_id` answers `404 batch_not_found`+with a reminder that any job id already returned can still be polled+individually at `/api/forge?job=`.++The [Workbench](https://three.ws/workbench) exposes this as the **Batch**+drawer (toolbar icon, or press `B`): one prompt per line, up to 8, queued+with the Generate node's current engine, quality and controls.+## States and limits- **Loading**: a real elapsed counter driven by the catalog ETA for the resolved path, tier, and engine. Cold self-host GPU workers add an honest spin-up estimate rather than a stalled bar.diff --git a/public/changelog-recent.json b/public/changelog-recent.jsonindex a13e000bd..5f7c8fa93 100644--- a/public/changelog-recent.json+++ b/public/changelog-recent.json@@ -1,11 +1,11 @@{- "generated_at": "2026-10-12T20:40:00.148Z",+ "generated_at": "2026-10-12T22:34:26.899Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws","url": "https://three.ws"},- "total": 4046,+ "total": 4047,"complete": false,"full_feed": "/changelog.json","entries": [@@ -92,6 +92,17 @@"security"]},+ {+ "date": "2026-10-12",+ "type": "update",+ "title": "Forge generation controls (target faces, bbox fit, rest pose) and a batch endpoint for fanning out N generations",+ "summary": "POST /api/forge and /api/x402/forge take three new, off-by-default controls: target_faces (alias of target_polycount) pins an explicit geometry budget on poly-aware backends; bbox: [x, y, z] uniformly rescales the delivered mesh to fit a box in meters, lane-agnostic since it runs as a post-generation GLB fit; pose: \"t\" | \"a\" requests a rest pose on backends without a caller-supplied reference image, with pose_applied echoed back so a photo-conditioned lane never silently ignores it. A new POST /api/forge-batch fans one call out to up to 8 independent /api/forge submissions, concurrency-capped by the caller's $THREE holder tier, and GET /api/forge-batch?batch=<id> polls the group: one item's failure never fails the batch, and group state is best-effort Redis so a job already returned stays pollable at /api/forge?job= even if the group expires. The Workbench's Generate Mesh node now exposes rest pose and width/height/depth bbox fields alongside the existing face budget, and a new Batch drawer (toolbar icon, or press B) queues up to 8 prompts at once against the new endpoint and opens any finished item straight into the viewport.",+ "link": "/docs/forge",+ "tags": [+ "feature",+ "improvement"+ ]+ },{"date": "2026-10-12","type": "update",@@ -1539,16 +1550,6 @@"tags": ["launch"]- },- {- "date": "2026-10-09",- "type": "launch",- "title": "Forge Workflows: Chain 3D Tools into One Run",- "summary": "A visual workflow builder for the Forge. Link a prompt or a photo to any live 3D engine, then remesh, rig, segment, restyle or make it game-ready, preview it inline, export the GLB and save it to your library, all in one run. Batch many prompts with ForEach, re-run from a failed step without redoing the rest, or generate on your own GPU with Modly. Starts from four templates.",- "link": "/forge/workflows",- "tags": [- "launch"- ]}]}diff --git a/public/changelog.json b/public/changelog.jsonindex bb0be0fbd..f8492b3d0 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,5 +1,5 @@{- "generated_at": "2026-10-12T20:40:00.126Z",+ "generated_at": "2026-10-12T22:34:26.876Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws",@@ -89,6 +89,17 @@"security"]},+ {+ "date": "2026-10-12",+ "type": "update",+ "title": "Forge generation controls (target faces, bbox fit, rest pose) and a batch endpoint for fanning out N generations",+ "summary": "POST /api/forge and /api/x402/forge take three new, off-by-default controls: target_faces (alias of target_polycount) pins an explicit geometry budget on poly-aware backends; bbox: [x, y, z] uniformly rescales the delivered mesh to fit a box in meters, lane-agnostic since it runs as a post-generation GLB fit; pose: \"t\" | \"a\" requests a rest pose on backends without a caller-supplied reference image, with pose_applied echoed back so a photo-conditioned lane never silently ignores it. A new POST /api/forge-batch fans one call out to up to 8 independent /api/forge submissions, concurrency-capped by the caller's $THREE holder tier, and GET /api/forge-batch?batch=<id> polls the group: one item's failure never fails the batch, and group state is best-effort Redis so a job already returned stays pollable at /api/forge?job= even if the group expires. The Workbench's Generate Mesh node now exposes rest pose and width/height/depth bbox fields alongside the existing face budget, and a new Batch drawer (toolbar icon, or press B) queues up to 8 prompts at once against the new endpoint and opens any finished item straight into the viewport.",+ "link": "/docs/forge",+ "tags": [+ "feature",+ "improvement"+ ]+ },{"date": "2026-10-12","type": "update",diff --git a/public/changelog.xml b/public/changelog.xmlindex b479a04e8..f342c1d02 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -70,6 +70,14 @@<category>feature</category><description>Content credentials (specs/PROVENANCE_3D.md) used to be an on-demand, Claude-track action: you had to call anchor_provenance to get one. Now every GLB the Forge produces, across every generation lane (free NIM, Forge Pro, rigged avatars, self-host TRELLIS/Hunyuan, async GCP workers), gets an ed25519-signed content credential the moment it's materialized, and every first download of a paid asset from the x402 asset bazaar gets one too, with the hash and a verify link returned right in the download response. Signing and storage are free and local, no Solana write and no spend, so there's nothing to gate; the separate paid anchor_provenance upgrade, which additionally commits the hash on-chain, is untouched and still available. A credential is keyed by content hash, so it's issued exactly once per file no matter how many times a lane or endpoint touches it. Model pages now show the same verified / tampered / unverified badge the 3D viewer already had, and a third party can check any model for free with GET /api/provenance. The owner can turn automatic issuance off platform-wide with PROVENANCE_AUTO_DISABLE=true; nothing else about verification changes if they do.</description></item>+ <item>+ <title>Forge generation controls (target faces, bbox fit, rest pose) and a batch endpoint for fanning out N generations</title>+ <link>https://three.ws/docs/forge</link>+ <guid isPermaLink="false">2026-10-12:Forge generation controls (target faces, bbox fit, rest pose) and a batch endpoint for fanning out N generations</guid>+ <pubDate>Mon, 12 Oct 2026 12:00:00 GMT</pubDate>+ <category>feature</category>+ <description>POST /api/forge and /api/x402/forge take three new, off-by-default controls: target_faces (alias of target_polycount) pins an explicit geometry budget on poly-aware backends; bbox: [x, y, z] uniformly rescales the delivered mesh to fit a box in meters, lane-agnostic since it runs as a post-generation GLB fit; pose: "t" | "a" requests a rest pose on backends without a caller-supplied reference image, with pose_applied echoed back so a photo-conditioned lane never silently ignores it. A new POST /api/forge-batch fans one call out to up to 8 independent /api/forge submissions, concurrency-capped by the caller's $THREE holder tier, and GET /api/forge-batch?batch=<id> polls the group: one item's failure never fails the batch, and group state is best-effort Redis so a job already returned stays pollable at /api/forge?job= even if the group expires. The Workbench's Generate Mesh node now exposes rest pose and width/height/depth bbox fields alongside the existing face budget, and a new Batch drawer (toolbar icon, or press B) queues up to 8 prompts at once against the new endpoint and opens any finished item straight into the viewport.</description>+ </item><item><title>Real VRM avatars: spring bones, expressions, and .vrma clips via @pixiv/three-vrm</title><link>https://three.ws/docs/avatar-engines</link>diff --git a/public/features.json b/public/features.jsonindex a4239960c..966bc2cbe 100644--- a/public/features.json+++ b/public/features.json@@ -1,5 +1,5 @@{- "generated_at": "2026-10-12T20:40:00.113Z",+ "generated_at": "2026-10-12T22:34:26.862Z","generated_by": "scripts/build-page-index.mjs from data/pages.json","site": {"name": "three.ws",