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.

docs(forge): document target_faces, bbox, and pose options plus /api/forge-batch

nirholasd98218c90679
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.json
index 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.md
index 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.json
index 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.json
index 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.xml
index 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: &quot;t&quot; | &quot;a&quot; 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=&lt;id&gt; 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.json
index 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",