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(avatar): specify the parametric base contract and pin its grouping and VRAM budget

nirholas45c9d74359f8
diff --git a/STRUCTURE.md b/STRUCTURE.md
index 2a5d11d0f..8b9325e1b 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -97,6 +97,7 @@ bottom.
| Portal (any website as a walkable world) | Page [pages/portal.html](pages/portal.html) `→ /portal` + controller [src/portal/main.js](src/portal/main.js), renderer [src/portal/render.js](src/portal/render.js), styles [src/portal/portal.css](src/portal/portal.css); reader [api/_lib/portal/outline.js](api/_lib/portal/outline.js) + guarded fetch [api/_lib/portal/fetch-site.js](api/_lib/portal/fetch-site.js) + robots matcher [api/_lib/portal/robots.js](api/_lib/portal/robots.js); pure layout [packages/portal/src/layout.js](packages/portal/src/layout.js); GLB export [api/_lib/portal/world-glb.js](api/_lib/portal/world-glb.js); endpoint [api/portal.js](api/portal.js) `→ /api/portal` | Live | Paste an address and walk the page: each section becomes a building sized by its word count (log scale), each link a door (same-site doors rebuild the world there and push browser history, outside links open the page), each image a billboard loaded through `/api/img`, each code block a monolith, and the palette comes from the page's own `theme-color` or a hash of its host. The layout is a pure, seeded function so the browser, the GLB exporter, the MCP tools and the npm package all build the identical city from one link. Crawler manners are part of the product: a declared user agent, `robots.txt` honoured per RFC 9309, one fetch per page cached fleet-wide for an hour, and an IP-pinned SSRF guard with size and time ceilings. `format=glb` returns the world as glTF with named nodes. SDK + CLI + MCP server: [packages/portal/](packages/portal). Docs: [docs/portal.md](docs/portal.md). Spec: [specs/PORTAL_WORLD.md](specs/PORTAL_WORLD.md). Tests: [tests/portal-robots.test.js](tests/portal-robots.test.js), [tests/portal-outline.test.js](tests/portal-outline.test.js), [tests/portal-layout.test.js](tests/portal-layout.test.js), [tests/portal-endpoint.test.js](tests/portal-endpoint.test.js), [tests/e2e/portal.spec.js](tests/e2e/portal.spec.js) |
| IRL (agents in the real world) | [pages/irl.html](pages/irl.html) `→ /irl` + [src/irl.js](src/irl.js), WebXR placement [src/ar/webxr.js](src/ar/webxr.js) + pinch [src/ar/pinch-scale.js](src/ar/pinch-scale.js), animated Quick Look bake [src/usdz-animated.js](src/usdz-animated.js) (static fallback [src/usdz-pipeline.js](src/usdz-pipeline.js)), backend [api/irl/](api/irl) | Live | Pin an agent at a real GPS spot; discovery is presence-proof-gated ([docs/irl/THREAT-MODEL.md](docs/irl/THREAT-MODEL.md)). **Place in AR** leads the dock on AR-capable devices: WebXR hit-test anchoring on Android with two-finger pinch resize (25%..400%) persisted to the pin (`anchor_scale`; the pinch lands as a follow-up `PATCH /api/irl/pins {id, scale}` after the placement tap), and ARKit Quick Look on iOS with the idle clip baked into the USDZ so the agent moves instead of standing in a T-pose. Discovered pins are equally alive in the in-page camera view: every mounted humanoid GLB plays the retargeted idle clip via a per-pin mixer ([src/irl/pin-idle.js](src/irl/pin-idle.js), phase-randomized, LOD-bounded), camera-aware gaze composes on top of the running animation, and the scene renders with ACES tone mapping + IBL + soft shadows (e2e: [tests/e2e/irl-pin-idle.spec.js](tests/e2e/irl-pin-idle.spec.js)). Inbound `/irl?avatar=<glb>` is the living-agent handoff from `GET /api/ar?…&kind=avatar` (explicit `?avatar=` wins over a saved session). Money Drops and World Lines: [docs/irl.md](docs/irl.md). SDK: [packages/irl/](packages/irl). **Share** ([src/irl/share-frame.js](src/irl/share-frame.js), [api/irl/share.js](api/irl/share.js), [api/irl/share/[token].js](api/irl/share/%5Btoken%5D.js)) mints a permanent, unfurlable `/irl/s/:token` link from the captured AR photo for the pin you just placed - never a coordinate, owner-gated, falls back to the plain native share sheet with no active pin. **Analytics** ([api/_lib/irl-analytics.js](api/_lib/irl-analytics.js), [api/irl/analytics.js](api/irl/analytics.js)) is the first site-wide usage rollup for the feature - pins placed, nearby reads, placement method, shares, drop claims - aged out by the existing hourly reaper. |
| Verifiable 3D provenance (content credentials) | Spec [specs/PROVENANCE_3D.md](specs/PROVENANCE_3D.md), pure core [api/_lib/provenance-3d.js](api/_lib/provenance-3d.js), Solana anchor [api/_lib/provenance-anchor.js](api/_lib/provenance-anchor.js), MCP tools [api/_mcp3d/tools/provenance.js](api/_mcp3d/tools/provenance.js) (`verify_provenance` free, `anchor_provenance` paid $0.05), free REST verify [api/provenance.js](api/provenance.js) `→ /api/provenance`, viewer badge [public/viewer.html](public/viewer.html), docs [docs/provenance.md](docs/provenance.md). | Live (verify) · anchor gated on issuer key + devnet funds | C2PA-style signed content credentials for AI 3D: creator, prompt, model/provider, lineage, timestamp, and the GLB's sha256, ed25519-signed by the three.ws issuer with the credential hash anchored on Solana. Free public `verify_provenance` / `GET /api/provenance?src=…` recompute the hash and return `verified | tampered | unknown` (a single changed byte → tampered); the verify path and response are coin-clean (both stores). `anchor_provenance` signs + writes the SPL Memo anchor + stores the credential in R2. Tests: [tests/provenance-3d.test.js](tests/provenance-3d.test.js). Evidence: [prompts/store-submissions/_generated/provenance/](prompts/store-submissions/_generated/provenance/). Store-submission prompt 19. |
+| Simulation readiness (a physics grade for 3D assets) | Spec [specs/SIM_READINESS.md](specs/SIM_READINESS.md), pure core [api/_lib/sim-readiness.js](api/_lib/sim-readiness.js), storage [api/_lib/sim-readiness-store.js](api/_lib/sim-readiness-store.js) + migration [20260813180000_sim_readiness_grades.sql](api/_lib/migrations/20260813180000_sim_readiness_grades.sql), free MCP tool [api/_mcp3d/tools/sim-readiness.js](api/_mcp3d/tools/sim-readiness.js) (`grade_sim_readiness`), free REST [api/sim-readiness.js](api/sim-readiness.js) `→ /api/sim-readiness`, shared badge + details panel [public/sim-readiness-panel.js](public/sim-readiness-panel.js) (`<sim-readiness>`, used by [public/viewer.html](public/viewer.html) and [src/model-page.js](src/model-page.js)), write path in [api/_lib/forge-store.js](api/_lib/forge-store.js) `materializeCreation`, docs [docs/sim-readiness.md](docs/sim-readiness.md). | Live | The question a renderer never asks and a rigid-body solver always does: can this mesh be simulated as-is? Four verdicts (`simulation_ready`, `needs_scale`, `needs_repair`, `unusable`, plus `unreadable` for non-glTF bytes) over measurements derived entirely from the geometry: watertightness and winding via welded-position topology, real-world extents read as meters per the glTF unit convention, exact volume/centroid/inertia from the divergence theorem and tetrahedron covariance, and a convex-hull proxy with its convexity ratio. Nothing is guessed: where a value cannot be known from the mesh (true scale, density) the report says so. Grades are keyed by GLB content hash, not URL, so one row serves the forge creation, the Object Library entry, a remix and an arbitrary third-party URL; every finished generation is graded on the write path, so a model page renders its verdict with no extra request. Signed into the content credential as `simReadiness` (provenance v2), which is what makes the physics claim as forge-proof as the authorship claim. Free, no account, no coin surface, both stores. Tests: [tests/sim-readiness.test.js](tests/sim-readiness.test.js), [tests/api/sim-readiness-endpoint.test.js](tests/api/sim-readiness-endpoint.test.js), [tests/provenance-3d.test.js](tests/provenance-3d.test.js). |
| OpenAI Select Partner (partner surface + announcement pack) | [pages/openai/index.html](pages/openai/index.html) `→ /openai`, badge assets [public/partners/openai/](public/partners/openai), announcement [blog/three-ws-openai-select-partner.html](blog/three-ws-openai-select-partner.html) `→ /blog/three-ws-openai-select-partner`, directory card in [pages/partners.html](pages/partners.html) `→ /partners`, press/social pack [marketing/openai-select-partner/](marketing/openai-select-partner/README.md), original OpenAI-supplied badge files + press-release template [OAI Select Tier Assets/](OAI%20Select%20Tier%20Assets/README.md) | Live | three.ws's OpenAI Partner Network Select-tier surface. `/openai` is the partner landing: the supplied badge (used unmodified, on a white plate), the four live OpenAI surfaces (the free keyless [3D Studio MCP connector](docs/mcp-studio.md) `→ /api/mcp-studio`, the custom-GPT Actions twin `→ /api/3d/studio`, [Spatial MCP](specs/SPATIAL_MCP.md), and [AR in ChatGPT](docs/chatgpt-ar.md)), the connect table, and the eleven-tool list. The marketing pack holds badge-usage rules and the press-release draft, which is gated on OpenAI's written approval before publishing (see its README). |
| NVIDIA Inception (membership surface + GPU docs cluster) | Landing page [pages/nvidia/index.html](pages/nvidia/index.html) `→ /nvidia` (vercel route + vite input + dev middleware, same wiring as `/openai`), membership doc [docs/nvidia-inception.md](docs/nvidia-inception.md) `→ /docs/nvidia-inception` + overview deck [docs/nvidia-inception/index.html](docs/nvidia-inception/index.html) `→ /docs/nvidia-inception/index.html`, free hosted-model map [docs/nvidia-models.md](docs/nvidia-models.md) `→ /docs/nvidia-models`, forum write-up [docs/nvidia-nemotron-spotlight.md](docs/nvidia-nemotron-spotlight.md) `→ /docs/nvidia-nemotron-spotlight`, tutorials [docs/tutorials/nvidia-3d-free.md](docs/tutorials/nvidia-3d-free.md) `→ /tutorials/nvidia-3d-free` and [docs/tutorials/nvidia-nim-self-host.md](docs/tutorials/nvidia-nim-self-host.md) `→ /tutorials/nvidia-nim-self-host`, engineering post [blog/image-to-3d-on-nvidia-l4-and-blackwell.html](blog/image-to-3d-on-nvidia-l4-and-blackwell.html) `→ /blog/image-to-3d-on-nvidia-l4-and-blackwell`, member badge [public/marks/nvidia-inception-badge.svg](public/marks/nvidia-inception-badge.svg) in [public/footer.html](public/footer.html), directory card in [pages/partners.html](pages/partners.html) `→ /partners` | Live | Everything NVIDIA on the platform, in two layers. **Free hosted lane:** one `NVIDIA_API_KEY` behind TRELLIS text-to-3D, FLUX.1-schnell, the Llama/Nemotron chat lineup, Nemotron vision, nv-embedqa, the reranker, NemoGuard, and Magpie speech (`nvidia-models`). **Self-hosted GPU fleet:** 12 Cloud Run GPU services, 11 on `nvidia-l4` and one on `nvidia-rtx-pro-6000` (Blackwell), covering text/image-to-3D, texture, remesh, rigging, and motion (see each `workers/model-*/README.md`). Membership was accepted July 2026 and is a startup program, not a partnership or an investment; the badge links to NVIDIA's startup program and must not imply endorsement. |
| Press kit (brand marks + media assets) | [pages/press/index.html](pages/press/index.html) `→ /press`, marks [public/brand/](public/brand), layout source [marketing/brand/](marketing/brand/README.md), renderer [scripts/render-brand-assets.mjs](scripts/render-brand-assets.mjs) `npm run build:brand-assets` | Live | The self-serve press surface: transparent-PNG marks (cube, horizontal and stacked lockups for dark and light grounds), the OpenAI announcement graphics, boilerplate at four lengths (one line, short, long, and a full-length bio) with copy buttons, fast facts, and the mark-usage rules. Everything is rendered from source rather than hand-exported, so a copy change re-renders the whole set; the renderer also builds `/brand/three-ws-press-kit.zip` with a README carrying the usage rules so the files cannot travel without them. Announcement cards come from [marketing/openai-select-partner/cards/social-card.html](marketing/openai-select-partner/cards/social-card.html) via `npm run build:openai-cards`. |
@@ -142,7 +143,7 @@ bottom.
| Auto-rigging worker (Mixamo skeleton + ARKit-52 blendshapes) | [workers/rig/](workers/rig) | Live · Cloud Run GPU `model-rig` (us-central1) | Make-It-Animatable engine (MIT) predicts the 52-bone Mixamo skeleton + weights; [workers/rig/rig_glb.py](workers/rig/rig_glb.py) grafts them into the original GLB (textures untouched); ICT-FaceKit (MIT) ARKit-52 expression transfer for emotions/lipsync. Serves every rig call behind `GCP_UNIRIG_URL` (env name predates the engine swap); it replaced the retired `unirig` service, whose worker directory was deleted 2026-08-11. Canonicalization proof: `rig worker skeleton` cases in [tests/glb-canonicalize.test.js](tests/glb-canonicalize.test.js) |
| Additive wardrobe (dress any avatar from the catalog) | Runtime [src/avatar-garment.js](src/avatar-garment.js) + taxonomy [src/garment-taxonomy.js](src/garment-taxonomy.js) + catalog [src/garment-catalog.js](src/garment-catalog.js) + closet UI [src/garment-closet.js](src/garment-closet.js) (in the `/avatar-edit` Wardrobe tab), bake pass [api/_lib/bake-garments.js](api/_lib/bake-garments.js), contract [specs/GARMENT_MANIFEST.md](specs/GARMENT_MANIFEST.md) | Live in the avatar editor · catalog seeding in progress | The wardrobe's additive half: catalog garments (top/bottom/footwear/outerwear/hair/headwear/glasses/accessory) are skinned onto ANY loaded humanoid at wear-time — skin indices rewritten to the avatar's bone order via [glb-canonicalize](src/glb-canonicalize.js) canonical names, garment inverse-binds kept where skeletons correspond (divergent rest poses reconcile), body culled under declared `occludes` regions so skin never clips through cloth, ≥60% weight-coverage gate refuses unbindable pieces. Saved outfits persist in `appearance.garments` and the server bake re-runs the same rebind on @gltf-transform so exports/embeds are dressed. Catalog: public GCS `three-ws-garments` bucket, sha256-verified per download, licence-gated (CC0/CC-BY/MIT/Apache/BSD only). Docs: [docs/avatar-wardrobe.md](docs/avatar-wardrobe.md). Tests: [tests/avatar-garment.test.js](tests/avatar-garment.test.js), [tests/garment-catalog.test.js](tests/garment-catalog.test.js), [tests/bake-garments.test.js](tests/bake-garments.test.js) |
| Garment Forge (text prompt → catalog garment) | [workers/garment-forge/](workers/garment-forge), public API [api/garment-forge.js](api/garment-forge.js) `→ POST/GET /api/garment-forge`, MCP tools [api/_mcp/tools/garments.js](api/_mcp/tools/garments.js) (`generate_garment`, `garment_status`, `list_garment_catalog`), verify harness [scripts/verify-garment.mjs](scripts/verify-garment.mjs), contract [specs/GARMENT_MANIFEST.md](specs/GARMENT_MANIFEST.md) | Live · Cloud Run CPU (`garment-forge`, us-central1) | Generation lane that feeds the additive wardrobe's catalog: prompt → ghost-mannequin reference photo (Vertex image lane) → PBR mesh on the deployed GPU fleet (`model-hunyuan3d-21-rtx` → `model-hunyuan3d-21` → `model-trellis`) → composed onto the canonical reference body (parametric-base) → rigged by `model-rig` with full-body context → reference body stripped back out (pure glTF repack), bones canonicalized, `occludes` derived from REGION_BONES weight mass, all 6 manifest rules validated in-process (including the ≥60% bind-coverage gate) → `garment.glb` + `manifest.json` + `thumb.webp` published immutably to `gs://three-ws-garments/garments/<slot>/<id>/v<n>/` and appended to the live catalog. Build gate: [workers/garment-forge/test_garment_glb.py](workers/garment-forge/test_garment_glb.py) (33 checks, runs inside `docker build`). Docs: [workers/garment-forge/README.md](workers/garment-forge/README.md) |
-| Parametric avatar base (change-everything sliders) | Baker [scripts/build-parametric-base.mjs](scripts/build-parametric-base.mjs) → [public/avatars/parametric-base.glb](public/avatars), CC0 source data [avatar-sources/anny/](avatar-sources/anny), studio wiring [src/avatar-studio.js](src/avatar-studio.js) (`?base=parametric`) + [src/avatar-sculpt.js](src/avatar-sculpt.js) | Live in Avatar Studio (Base switcher) | One canonical humanoid whose identity is **122 baked morph-target sliders** (nose/ears/mouth/eyes/jaw/cheeks/head shape/neck plus gender, muscle, weight, age, height, torso, hips, limbs), built from the CC0 MakeHuman/MPFB2 body vendored via [naver/anny](https://github.com/naver/anny). 52-bone `mixamorig:*` skeleton, so the full clip library retargets onto every slider combination. Sparse-accessor morphs keep the GLB at ~4 MB. Roadmap to conforming hair/garments + sculpt brush: [prompts/finish/roadmap-avatar-parametric-editor.md](prompts/finish/roadmap-avatar-parametric-editor.md). Tests: [tests/parametric-base.test.js](tests/parametric-base.test.js) |
+| Parametric avatar base (change-everything sliders) | Baker [scripts/build-parametric-base.mjs](scripts/build-parametric-base.mjs) → [public/avatars/parametric-base.glb](public/avatars), CC0 source data [avatar-sources/anny/](avatar-sources/anny), studio wiring [src/avatar-studio.js](src/avatar-studio.js) (`?base=parametric`) + [src/avatar-sculpt.js](src/avatar-sculpt.js) | Live in Avatar Studio (Base switcher) | One canonical humanoid whose identity is **306 baked morph-target sliders** (nose/ears/mouth/eyes/brows/cheeks/jaw/head shape/neck plus gender, ethnicity, muscle, weight, age, height, torso, hips, midsection, arms and legs), built from the CC0 MakeHuman/MPFB2 body vendored via [naver/anny](https://github.com/naver/anny). 52-bone `mixamorig:*` skeleton, so the full clip library retargets onto every slider combination. Sparse-accessor morphs keep the GLB at 6.5 MB; the baker enforces a 96 MB morph-texture VRAM ceiling because three.js allocates one dense texture layer per target. On top of the sliders: skeleton-space **proportions** ([src/avatar-proportions.js](src/avatar-proportions.js), baked server-side by [api/_lib/bake-proportions.js](api/_lib/bake-proportions.js)) and a **free-sculpt brush** ([src/avatar-sculpt-brush.js](src/avatar-sculpt-brush.js), wire format [src/avatar-sculpt-doc.js](src/avatar-sculpt-doc.js), baked by [api/_lib/bake-sculpt.js](api/_lib/bake-sculpt.js)) for the shapes no catalogue has. Contract: [specs/PARAMETRIC_AVATAR.md](specs/PARAMETRIC_AVATAR.md). Tests: [tests/parametric-base.test.js](tests/parametric-base.test.js), [tests/bake-proportions.test.js](tests/bake-proportions.test.js), [tests/avatar-sculpt-brush.test.js](tests/avatar-sculpt-brush.test.js) |
| Animation gallery | [pages/animations.html](pages/animations.html) + [src/animations-gallery.js](src/animations-gallery.js) | Live at `/animations` | 2,100+ clips with poster thumbnails ([scripts/build-animation-thumbnails.mjs](scripts/build-animation-thumbnails.mjs)), derived categories ([src/animation-categories.js](src/animation-categories.js)), shared live-preview engine ([src/animations-live-preview.js](src/animations-live-preview.js)) · see [docs/animations.md](docs/animations.md) |
| Gesture vocabulary | [pages/gestures.html](pages/gestures.html) + [src/gestures-page.js](src/gestures-page.js), slots [src/runtime/animation-slots.js](src/runtime/animation-slots.js) | Live at `/gestures` | The 19 gesture slots an agent plays, each previewed on a live avatar, with the skill hints that trigger it and a builder that saves a per-slot clip override straight onto an agent (`meta.edits.animations`). Hint table is generated from the shipped skill definitions by [scripts/build-agent-hints.mjs](scripts/build-agent-hints.mjs), so attribution cannot go stale · see [docs/animations.md](docs/animations.md) |
| Choreographer | [pages/choreograph.html](pages/choreograph.html) + [src/choreograph-page.js](src/choreograph-page.js), engine [src/runtime/choreography.js](src/runtime/choreography.js) | Live at `/choreograph` | Timeline for composing gesture slots into named, timed routines, previewed on the shared live-preview engine with crossfades and a scrubbable playhead. One dependency-free module defines the routine format, the URL wire format and the timing engine; the studio, `PUT /api/agents/:id/animations` (stored at `meta.choreographies`), the public manifest and `AgentAvatar.playChoreography` all import it, and `<agent-3d>.playRoutine('welcome')` performs one from any embed. Also published as `@three-ws/avatar/runtime/choreography.js` · see [docs/choreography.md](docs/choreography.md) |
diff --git a/docs/ALL.md b/docs/ALL.md
index db3a4daa0..1d0e36cc5 100644
--- a/docs/ALL.md
+++ b/docs/ALL.md
@@ -34184,7 +34184,7 @@ curl 'https://three.ws/api/avatars/<avatarId>' -H 'cookie: <session>'
- **No selfie, no camera.** This is the from-scratch path. To build an avatar from a photo, use the platform's selfie-to-avatar flow under [/create](https://three.ws/create) instead.
- **Two base bodies.** Create mode starts from the Stylized feminine base or the bare Parametric base (which covers masculine, feminine, and everything between via its body sliders). Switching base reloads the studio, so it asks before discarding unsaved changes. The posable primitive with a build toggle lives in [Animation Studio](#sec-094).
-- **The Parametric base ships bare.** No hair or outfit meshes yet, so the hair/outfit color slots and the Layers block do not appear on it; hats, glasses, and earrings attach normally. Conforming hair and garments are the next phase of the parametric roadmap ([prompts/finish/roadmap-avatar-parametric-editor.md](../prompts/finish/roadmap-avatar-parametric-editor.md)).
+- **The Parametric base ships bare.** No hair or outfit meshes yet, so the hair/outfit color slots and the Layers block do not appear on it; hats, glasses, and earrings attach normally. Conforming hair and garments are the next phase (`slots` under Reserved in [specs/PARAMETRIC_AVATAR.md](../specs/PARAMETRIC_AVATAR.md)).
- **Sculpt depends on the base's morphs.** The face/body sliders render against whatever morph targets the base GLB exposes; a slot with no matching morph simply does not appear. Proportions are independent of morphs: they need only a canonical humanoid skeleton, so they work on a rig with no blendshapes at all. Height is the one parameter that needs an armature node above the hips, and is hidden on rigs whose hips sit directly in the scene.
- **Save requires an account.** Export happens client-side, but persisting the avatar to your library needs sign-in. Optimization is best-effort: if compression fails, the original export is saved untouched so the save always completes.
- **What you see is what you save.** Because the save exports the live scene graph, the stored GLB matches the viewport exactly, colors, morphs, accessories, and the chosen idle included.
diff --git a/docs/avatar-studio.md b/docs/avatar-studio.md
index a9ccc82eb..ac8949b33 100644
--- a/docs/avatar-studio.md
+++ b/docs/avatar-studio.md
@@ -13,12 +13,14 @@ The selfie-to-avatar path is great when you want to look like yourself, but it i
The studio mounts a `TalkScene` around a base body and layers a tabbed customization panel over it. A **Base** switcher at the top of the panel picks the starting template (create mode only; a saved avatar always reloads its own model):
- **Stylized** (`/avatars/default.glb`): the dressed feminine stylized body with hair, outfit, and garment layers. The default.
-- **Parametric** (`/avatars/parametric-base.glb`): a bare humanoid built from the CC0 MakeHuman/MPFB2 body, baked with **120+ identity morph sliders** by [scripts/build-parametric-base.mjs](../scripts/build-parametric-base.mjs). On this base the Sculpt tab becomes a full character creator: Nose (width, length, tip, hump, nostrils), Mouth (lip volume, corners, cupid's bow, dimples), Ears (size, pointed, lobes, position: yes, elf ears), Eyes (size, tilt, spacing, bags), Brows, Cheeks, Jaw and chin, Head Shape (round/square/oval, forehead), and Body (feminine/masculine, muscle, weight, age, height, chest, waist, hips, glutes, belly, shoulders, arms, thighs, calves, leg length). It rides the same 52-bone Mixamo-named skeleton conventions as everything else, so the entire animation library retargets onto any slider combination. Source data and license provenance: [avatar-sources/anny/README.md](../avatar-sources/anny/README.md).
+- **Parametric** (`/avatars/parametric-base.glb`): a bare humanoid built from the CC0 MakeHuman/MPFB2 body, baked with **306 identity morph sliders** by [scripts/build-parametric-base.mjs](../scripts/build-parametric-base.mjs). On this base the Sculpt tab becomes a full character creator, grouped into Eyes (42), Nose (36), Mouth (35), Ears (32), Head Shape (27), Torso (22), Legs (22), Cheeks (16), Hips & Midsection (17), Arms (15), Jaw (14), Body (12), Neck (10) and Brows (6). Face regions keep separate left and right sliders because facial asymmetry is part of a face; limbs get one symmetric slider, because a one-armed width edit reads as a defect rather than a look. It rides the same 52-bone Mixamo-named skeleton conventions as everything else, so the entire animation library retargets onto any slider combination. Source data and license provenance: [avatar-sources/anny/README.md](../avatar-sources/anny/README.md); the full contract for the base is [specs/PARAMETRIC_AVATAR.md](../specs/PARAMETRIC_AVATAR.md).
Every edit updates the live scene graph, and a working "appearance" object tracks the whole configuration: chosen colors, morph values, skeleton proportions, accessories, and hidden layers. That record is the avatar's parameter document, specified in [specs/AVATAR_PARAMETERS.md](../specs/AVATAR_PARAMETERS.md).
- **Color.** Material slots (skin, hair, outfit) each offer a curated swatch palette plus a full-spectrum picker (an `iro.js` wheel with hex entry and eyedropper, falling back to the native OS color dialog). Slots the loaded base has no materials for are hidden rather than rendered dead, and "Default" restores the base's authored color. Above them sit **Looks**: one-tap palettes (Noir, Sunset, Arctic, Cyber, Rosé, Forest, Mono, Ember) that theme skin, hair, and outfit together in a single history step, always landing on real, coherent material colors.
-- **Face and body sculpt.** The sculpt panel renders grouped morph sliders against whatever morph targets the base carries, organized into Eyes, Brows, Nose, Mouth, Jaw, Cheeks, Ears, Head Shape, and Body, plus a MetaHuman-style 2-D face-type blend wheel over six archetypes and advanced visemes. Left/right paired morphs collapse into one mirrored slider unless you unlock Mirror L/R for asymmetry. It drives real morph targets, so the change is baked into the saved mesh.
+- **Face and body sculpt.** The sculpt panel renders grouped morph sliders against whatever morph targets the base carries, organized into Eyes, Brows, Nose, Mouth, Jaw, Cheeks, Ears, Head Shape, Neck, Torso, Hips & Midsection, Arms, Legs and Body, plus a MetaHuman-style 2-D face-type blend wheel over six archetypes and advanced visemes. Left/right paired morphs collapse into one mirrored slider unless you unlock Mirror L/R for asymmetry. It drives real morph targets, so the change is baked into the saved mesh.
+- **Finding a slider among hundreds.** Past 80 sliders a filter box appears above the groups. Type `calf`, `cupids bow` or a raw morph name and the panel hides everything else, opening the groups that still have a match; clear it (or press Escape) and every group snaps back to exactly the open/closed state it had. Body-region groups start collapsed and each carries an "N edited" pill on its header, so a group you have already touched is obvious without opening it.
+- **Free sculpt.** Above everything else sits a brush for the shapes no catalogue has: a dent in one temple, a crooked bridge, a brow ridge that is simply yours. Turn **Brush on**, then drag on the avatar to pull the surface out or push it in; dragging the background still orbits the camera, so you never lose the view. Size and Strength are real world measurements (centimetres and millimetres per stroke), the on-screen ring shows the brush's actual footprint at the current zoom, and Symmetry mirrors each stroke across the body's own centre line until you turn it off. Playback pauses while the brush is on so the mesh holds still under your cursor. The edit is recorded as its own morph target, which means it adds to the library sliders instead of fighting them, exports with the mesh, and comes back untouched when you re-open the avatar. **Clear sculpt** returns the body to exactly the catalogue shape.
- **Proportions.** Above the morph sliders sits a bone-level build panel: Height, Leg Length, Torso Length, Neck Length, Arm Length, Shoulder Width, Hip Width, Head Size, Hand Size, Foot Size. Morphs reshape a limb; these re-proportion the skeleton, which is the only way to actually lengthen one (a morph is a fixed set of vertex deltas, so pulling the hand further from the elbow would drag the skin off the bone driving it). Each slider is a ratio around the base body, shown as a signed percentage, and double-clicking resets it. Lengthen the legs and the hips ride up so the feet stay on the floor, and the animation library re-measures itself against the new hip height so the walk does not foot-slide. Only parameters the loaded rig has bones for are offered.
- **Accessories.** Hats, glasses, and earrings load from a preset catalog (`/accessories/presets.json`). Hovering a tile previews it live on the avatar; clicking commits it. Hats and glasses are single-slot; earrings stack. A chip row shows everything applied, each removable.
- **Garment layers.** Outfit, glasses, and hair can be toggled visible/hidden, with bulk "Start minimal" and "Dress fully" actions, so you can strip to the base body and rebuild the look deliberately.
@@ -59,7 +61,8 @@ curl 'https://three.ws/api/avatars/<avatarId>' -H 'cookie: <session>'
- **No selfie, no camera.** This is the from-scratch path. To build an avatar from a photo, use the platform's selfie-to-avatar flow under [/create](https://three.ws/create) instead.
- **Two base bodies.** Create mode starts from the Stylized feminine base or the bare Parametric base (which covers masculine, feminine, and everything between via its body sliders). Switching base reloads the studio, so it asks before discarding unsaved changes. The posable primitive with a build toggle lives in [Animation Studio](./animation-studio.md).
-- **The Parametric base ships bare.** No hair or outfit meshes yet, so the hair/outfit color slots and the Layers block do not appear on it; hats, glasses, and earrings attach normally. Conforming hair and garments are the next phase of the parametric roadmap ([prompts/finish/roadmap-avatar-parametric-editor.md](../prompts/finish/roadmap-avatar-parametric-editor.md)).
+- **The Parametric base ships bare.** No hair or outfit meshes yet, so the hair/outfit color slots and the Layers block do not appear on it; hats, glasses, and earrings attach normally. Conforming hair and garments are the next phase (`slots` under Reserved in [specs/PARAMETRIC_AVATAR.md](../specs/PARAMETRIC_AVATAR.md)).
+- **Free sculpt is tied to the body it was painted on.** Strokes are stored as vertex deltas against a specific topology, so a sculpt made on the Parametric base does not transfer to a differently built mesh; the record notes which mesh it belongs to and is skipped rather than force-fitted anywhere else.
- **Sculpt depends on the base's morphs.** The face/body sliders render against whatever morph targets the base GLB exposes; a slot with no matching morph simply does not appear. Proportions are independent of morphs: they need only a canonical humanoid skeleton, so they work on a rig with no blendshapes at all. Height is the one parameter that needs an armature node above the hips, and is hidden on rigs whose hips sit directly in the scene.
- **Save requires an account.** Export happens client-side, but persisting the avatar to your library needs sign-in. Optimization is best-effort: if compression fails, the original export is saved untouched so the save always completes.
- **What you see is what you save.** Because the save exports the live scene graph, the stored GLB matches the viewport exactly, colors, morphs, accessories, and the chosen idle included.
diff --git a/prompts/finish/production-100-00-INDEX.md b/prompts/finish/production-100-00-INDEX.md
index b5b76d879..5bf7fcfc0 100644
--- a/prompts/finish/production-100-00-INDEX.md
+++ b/prompts/finish/production-100-00-INDEX.md
@@ -92,7 +92,7 @@ run in parallel, H waits on owner gates, I is anytime, J is the parallel swarm.
|---|---|
| [../roadmap/generation-suite.md](roadmap-generation-suite.md) | Partial: tools, smoke cron and gallery shipped; PBR map outputs, job webhooks and the API contract doc open. |
| [../roadmap/creation-consolidation.md](roadmap-creation-consolidation.md) | Partial: redirects and the save fix shipped; Studio wardrobe, the `/embed` retirement and the `/start` decision open. |
-| [../roadmap/avatar-parametric-editor.md](roadmap-avatar-parametric-editor.md) | Partial: 122 sliders and client-side proportions; server bake, free sculpt and the spec open. |
+| Parametric avatar editor | Done 2026-09-03: 306 sliders, server-side proportion bake, free-sculpt brush, `specs/PARAMETRIC_AVATAR.md`. |
| [../roadmap/developer-resources-repos.md](roadmap-developer-resources-repos.md) | Agent side shipped (`export:satellites` stages 70 files offline); blocked on OWNER-ACTIONS row 16, then the cross-links. |
| [../roadmap/native-widgets.md](roadmap-native-widgets.md) | Tasks 1 to 3 built (card endpoint, Android widget, Windows manifest); two commits await the deploy; task 4 needs row 17. |
| [../gcp-credits/05-catalog-animation-seeding.md](gcp-credits-05-catalog-animation-seeding.md) | Partial: the catalog seed runs at scale (56,898 avatars); the generated motion library has 0 clips. |
diff --git a/prompts/finish/roadmap-00-README.md b/prompts/finish/roadmap-00-README.md
index 241944c76..3fbd6c84f 100644
--- a/prompts/finish/roadmap-00-README.md
+++ b/prompts/finish/roadmap-00-README.md
@@ -73,7 +73,6 @@ retired; they remain readable in git history
|---|---|---|
| [generation-suite.md](roadmap-generation-suite.md) | Meshy and Tripo class parity, and production truth for every generation endpoint | Open. Starts by rebuilding the production truth table from live probes. |
| [creation-consolidation.md](roadmap-creation-consolidation.md) | The last three creation-surface merges | Open. Two redirects are blocked behind real capability gaps, and closing those gaps is the work. |
-| [avatar-parametric-editor.md](roadmap-avatar-parametric-editor.md) | Parametric avatar editor, phase 2 onward | Open. Phase 1 (122-slider parametric base) shipped 2026-07-22. |
| [developer-resources-repos.md](roadmap-developer-resources-repos.md) | The public examples satellite repo and its one-way export | Done, retired 2026-09-03. `npm run export:satellites` stages 72 files and passes all four smoke stages; the docs, `llms.txt` and `llms-full.txt` cross-links are live. Only the owner-gated publish remains (create the `three-ws` org, run the printed push), tracked as row 16 of [production-100-OWNER-ACTIONS.md](production-100-OWNER-ACTIONS.md). |
| [native-widgets.md](roadmap-native-widgets.md) | Native widgets on the Android, Windows, macOS and iOS home screens | Open. The signed `ws.three.app` TWA and the server-side render endpoints already exist, so the shell and the image source are not the work. |
diff --git a/prompts/finish/roadmap-avatar-parametric-editor.md b/prompts/finish/roadmap-avatar-parametric-editor.md
deleted file mode 100644
index 5917245bb..000000000
--- a/prompts/finish/roadmap-avatar-parametric-editor.md
+++ /dev/null
@@ -1,160 +0,0 @@
-# RM-PARAM: Parametric avatar editor, phase 2 onward
-
-**How to run this:** paste this whole file into a fresh Claude Code chat opened in
-`/workspaces/three.ws`, or say "execute `prompts/finish/roadmap-avatar-parametric-editor.md`".
-It is complete on its own. Also read `prompts/finish/roadmap-00-README.md` and `CLAUDE.md`.
-
-## Binding operating clause
-
-1. Finish 100%. Never end with a question, a plan you did not execute, or "should I proceed?".
-2. Additive only. `src/glb-canonicalize.js`, `src/animation-retarget.js` and the export bake are
- shared cores: preserve 100% backward compatibility and prove it with tests.
-3. CLAUDE.md hard rules: no mocks, no TODO comments, no em-dash or en-dash characters. Stage
- explicit paths only.
-
-## The architectural decision everything hangs on
-
-**One canonical parametric body. Everything else is a parameter over it.** Shape is morph
-targets, proportions are skeleton parameters, hair and clothes are conforming attachments that
-inherit skinning and morphs, skin is layered textures over fixed UVs, and identity capture
-(selfie, text) is a solver that outputs a parameter vector rather than a mesh. Fixed topology
-is what makes "change everything" tractable.
-
-## Step 0: re-derive current state (trust nothing below)
-
-```bash
-ls public/avatars/parametric-base.glb avatar-sources/anny scripts/build-parametric-base.mjs
-npx vitest run tests/parametric-base.test.js
-node -e "1" && grep -c "" avatar-sources/anny/*/*.target 2>/dev/null | tail -3
-npm run dev # open /create/studio?base=parametric and count the sliders that render
-```
-
-**Phase 1 is shipped (2026-07-22):** `avatar-sources/anny/` (vendored CC0 MakeHuman/MPFB2 data
-with provenance), `scripts/build-parametric-base.mjs` (the baker),
-`public/avatars/parametric-base.glb` (52-bone `mixamorig:*` skeleton, 4 submeshes, 122 sparse
-morph sliders), the Base switcher in Avatar Studio (`?base=parametric`), the Ears and Head Shape
-sculpt groups, and `tests/parametric-base.test.js`. 472 target files are vendored and roughly
-350 remain uncurated, so growing 122 sliders toward 400+ is a MORPHS-table edit plus a rebake,
-not new engineering.
-
-`src/avatar-sculpt.js` renders sliders for whatever morphs the loaded GLB carries, so every
-morph you bake lights up in the UI with zero UI work.
-
-## Task 1: grow the slider set (cheapest large win)
-
-Curate the remaining vendored targets into the MORPHS table (asymmetric variants, per-segment
-scale axes, navel, valgus, hands, feet), rebake, and confirm the studio renders them grouped
-sensibly. Keep the GLB sane: sparse accessors only, and measure the file size before and after.
-Extend `tests/parametric-base.test.js` with the new group assertions.
-
-## Task 2: skeleton-space proportions (phase 2)
-
-**Shipped client-side (2026-08-02).** `src/avatar-proportions.js` holds the 10-parameter table
-(height, leg/torso/neck/arm length, shoulder/hip width, head/hand/foot size) and the maths;
-`src/avatar-sculpt.js` renders the Proportions group above the morph sliders on both the studio
-and the customizer; `AnimationManager.remeasureRigProportions()` re-measures hip height and
-rebuilds every bound action so the walk does not foot-slide; the record serializes as
-`appearance.proportions`, specified in `specs/AVATAR_PARAMETERS.md` and covered by
-`tests/avatar-proportions.test.js`.
-
-Design notes worth keeping: offsets scale a joint's rest offset from its parent and `scale`
-params scale the joint, but rotations are NEVER written, which is what keeps the retargeter's
-captured rest frames (and bind-space morph deltas) valid. Ground contact is measured on the rig
-rather than derived from the ratios, with the left and right deltas averaged so a width edit
-cancels out and only a length edit lifts the hips. The re-measure deliberately does not call
-`attach()`, because attach re-captures rest frames and a mid-animation rig is not at rest.
-
-**Remaining:** the server-side bake. Avatar Studio saves via a client-side `GLTFExporter` of the
-live scene, so proportions bake in there for free, but `/avatars/:id/edit` PATCHes the appearance
-record and lets `api/_lib/bake.js` render the GLB. Until that path applies `proportions`, a build
-edited in the customizer persists and re-applies in the editor but does not reach the baked GLB
-that viewers download. The shared module is written to be consumed from Node (no three.js, no DOM
-imports): a sibling `api/_lib/bake-proportions.js` that resolves canonical bones with
-`canonicalizeBoneName`, feeds `computeProportionTransforms`, and writes `translation`/`scale`
-back, lazy-imported from `bake.js` the way `bake-garments.js` already is.
-
-## Task 3: free sculpt (phase 4, the "change literally anything" guarantee)
-
-A radius and falloff brush edits vertex positions directly on the mesh, recorded as a per-avatar
-custom delta morph so it exports, serializes and composes with the library morphs. Symmetry
-toggle on and off (asymmetry is a feature the competition lacks). Verify the delta survives a
-round trip through the export bake.
-
-## Task 4: the parameter model, as a real spec
-
-One serializable document per avatar is what saves, shares, forks and mints. It is a
-load-bearing wire format (editor, baker, shop and embeds all consume it), so it belongs in
-`specs/`, not in a comment:
-
-```json
-{
- "base": "parametric-v1",
- "morphs": { "noseWidth": 0.3, "earPoint": 0.8 },
- "skeleton": { "height": 1.78, "armLength": 1.02 },
- "sculpt": "r2://sculpt-deltas/<id>.bin",
- "slots": { "hair": "asset:curly-04", "top": "asset:forge-8fa2" },
- "layers": [ { "type": "tattoo", "decal": "...", "uv": [0.4, 0.6] } ],
- "animation": { "idle": "breathing-02", "walk": "confident", "mood": "warm" }
-}
-```
-
-Write `specs/PARAMETRIC_AVATAR.md` with the field-by-field contract, versioning rule, and what
-each consumer is allowed to ignore. Then make the editor read and write exactly that shape.
-
-## Definition of done
-
-- [ ] Slider count grown, grouped and rendering; GLB size recorded before and after.
-- [ ] Proportion parameters apply at load, bake at export, and do not break retargeting
- (`npm run gate` and the retarget suite green, walk verified with no foot sliding).
-- [ ] Free sculpt edits export, reload and compose with library morphs, proven by round trip.
-- [ ] `specs/PARAMETRIC_AVATAR.md` written; the editor reads and writes that document.
-- [ ] Verified in a real browser at 320, 768 and 1440 px with no console errors.
-- [ ] `npm test` green; `data/changelog.json` entry; `STRUCTURE.md` row updated if a surface
- changed.
-- [ ] `npm run check:rules -- --paths <files you touched>` clean.
-
-## Never blocked (pre-answered)
-
-| Blocker | Do this |
-|---|---|
-| Hundreds of morphs look expensive at runtime | three.js handles them through texture-based morph targets and only nonzero influences cost anything. Measure before optimizing. |
-| A target file does not map cleanly onto the topology | Skip it, list it in the report, and keep the curated set clean. A wrong slider is worse than a missing one. |
-| The FLAME selfie lane is tempting | It is licence-blocked (owner signature with MPI) and is phase 5. Nothing in this work order waits on it. |
-| A change would alter shared retarget behavior | Flag-gate it, default to current behavior, and prove backward compatibility with tests before flipping. |
-| Garment fitting comes up | That is phase 3 and the `workers/garment-forge` lane. Out of scope here; note the seam. |
-
-## Appendix: the later phases (context, not this session's scope)
-
-- **Phase 3, conforming assets and the AI catalog flywheel (the moat):** auto-fit binds garment
- vertices to the nearest body surface and transfers skin weights and morph deltas, so a garment
- follows every slider. Slot taxonomy with per-slot body-hide masks prevents clipping. The forge
- text-to-3D lane generates garments and hair against the canonical body, auto-fits them, and
- lands them in the cosmetics shop. The competition has a fixed paid catalog; we get an infinite
- prompted one.
-- **Phase 5, identity lanes resolve into parameters:** selfie via dense fit projected into the
- morph library (least-squares over slider space, residual as a custom morph), text via an LLM
- mapping a prompt to a parameter vector over the named slider set.
-- **Phase 6, skin and texture layers:** base tone, complexion, makeup, tattoos and decals,
- scars, age maps, eye colour, composited to one atlas at export.
-- **Phase 7, animation personality:** per-avatar default idle and walk, gesture intensity,
- mood-blend defaults, saved emote loadouts. Retarget cost is zero because everything sits on
- one canonical skeleton.
-
-## Retire this prompt when it is done (required)
-
-1. Verify every Definition of done line against actual command output in front
- of you. Never claim a line you did not verify.
-2. Record the outcome in this campaign's PROGRESS or INDEX file if it has one.
-3. Commit with explicit paths and a subject that describes the diff (house
- style: type(scope): what changed and why a reader cares), and delete this
- prompt file in that same commit:
-
- git rm prompts/finish/roadmap-avatar-parametric-editor.md
-
- A finished order left on disk reads as open work to the next agent, so the
- shrinking directory is the campaign's progress ledger.
-
-If a line genuinely cannot pass inside this session (an external party must
-respond, or an owner-gated action is the final step), finish everything else,
-leave this file in place, and state exactly which line remains and who owns it.
-Never delete this file on a partial.
diff --git a/specs/AVATAR_PARAMETERS.md b/specs/AVATAR_PARAMETERS.md
index be633b5ac..1f7d057ab 100644
--- a/specs/AVATAR_PARAMETERS.md
+++ b/specs/AVATAR_PARAMETERS.md
@@ -1,6 +1,6 @@
# Avatar Parameter Model v0.1
-**Status:** partial (morphs, colors, layers, garments, accessories and proportions are live; sculpt deltas, texture layers and animation identity are reserved).
+**Status:** partial (morphs, colors, layers, garments, accessories, proportions and free-sculpt deltas are live; texture layers and animation identity are reserved).
The parameter model is the serialized description of a three.ws avatar's body: one JSON document that says what the character *is*, independent of any particular GLB. It is what saves, what re-opens in the editor, what the server bakes, and what a fork or a share link carries.
@@ -20,6 +20,7 @@ Every three.ws avatar keeps its parameters. The GLB is a *render* of the documen
"accessories": ["preset-id", "..."],
"morphs": { "noseWider": 0.3, "earPointedLeft": 0.8 },
"proportions": { "legLength": 1.06, "shoulderWidth": 0.94 },
+ "sculpt": { "version": 1, "meshes": { "Body": { "count": 812, "vertexCount": 14517, "scale": 3.1e-6, "indices": "…", "deltas": "…" } } },
"colors": { "skin": "#c99a70", "hair": "#241a12" },
"hidden": ["hair"],
"garments": [{ "slot": "top", "id": "garment-id" }],
@@ -35,6 +36,7 @@ Every field is optional. An absent field means "default", and a document with no
| `accessories` | preset id[] | Bone-mounted props (hat, glasses, earrings) | `src/agent-accessories.js` |
| `morphs` | name → weight | Shape. Any morph target the loaded GLB exposes, by name | `src/avatar-sculpt.js` |
| `proportions` | id → ratio | Build. Skeleton-space length, width and stature | `src/avatar-proportions.js` |
+| `sculpt` | delta document | Free-brush vertex deltas, sparse and quantised | `specs/PARAMETRIC_AVATAR.md` |
| `colors` | slot → hex | Per-slot material tint | `src/avatar-studio.js` |
| `hidden` | slot[] | Garment layers to drop | `src/avatar-wardrobe.js` |
| `garments` | {slot, id}[] | Additive catalog wearables | `specs/GARMENT_MANIFEST.md` |
@@ -44,7 +46,7 @@ Every field is optional. An absent field means "default", and a document with no
`{ morphTargetName: weight }`, weights clamped to `[-1, 1]` (`[0, 1]` in the UI). Names are matched against whatever the loaded GLB actually carries: an unknown name is skipped, never an error, because the same document may be applied to a rig that exposes fewer shapes.
-There is no fixed slider list. The parametric base (`public/avatars/parametric-base.glb`) ships 122 identity morphs and the panel renders one slider per morph it finds, so growing the base grows the editor with no UI change.
+There is no fixed slider list. The parametric base (`public/avatars/parametric-base.glb`) ships 306 identity morphs and the panel renders one slider per morph it finds, so growing the base grows the editor with no UI change. The morph name `customSculpt` is reserved: it carries the `sculpt` field's deltas and is deliberately not offered as a slider, because its weight is pinned at 1.
## `proportions`: build
@@ -73,6 +75,14 @@ Three invariants any implementation MUST hold:
Values outside a parameter's range are clamped, unknown ids are dropped, and a value within `1e-4` of `1.0` is removed entirely (`normalizeProportions`). A rig missing a parameter's bones simply does not offer that slider (`availableProportionParams`), so the panel never shows a dead control.
+## `sculpt`: free-brush deltas
+
+Everything the morph library and the proportion table cannot reach: a dent in one temple, a crooked bridge, a brow ridge in no catalogue. A radius-and-falloff brush pushes vertices along their own surface normal and records the result as one extra morph target per mesh, named `customSculpt` and pinned at weight 1, so the edit stays additive with every library slider and reversible by clearing that one target.
+
+The document is sparse (only vertices that moved) and quantised to int16 over the recorded peak, which resolves the 0.12 m displacement cap to under 4 micrometres. Its field-by-field contract, the bind-space maths and the symmetry rule are specified in [`PARAMETRIC_AVATAR.md`](./PARAMETRIC_AVATAR.md#3-free-sculpt-everything-else); validation is `sanitizeSculptDoc` in `src/avatar-sculpt-doc.js`, applied on both read and write like every other field.
+
+A sculpt is tied to a topology. `vertexCount` records the mesh it was authored against, and a consumer whose mesh disagrees MUST skip that entry rather than force-fit it: a delta applied to the wrong vertices is a disfigured avatar, which is worse than an un-sculpted one.
+
## `attachments`: custom bone-mounted props
`accessories` names entries in the curated preset catalog, which is what makes a hat portable: the id resolves to a GLB the platform ships. A prop generated on demand (Scene Composer forges one from a text prompt and parents it to a bone) is in no catalog, so it carries its own reference instead:
@@ -92,7 +102,6 @@ Named here so implementations do not claim the keys for anything else:
| Field | For |
|---|---|
-| `sculpt` | Free-brush vertex deltas, stored out of band and referenced by URL |
| `layers` | Texture layers over the canonical UVs (tattoos, makeup, complexion) |
| `animation` | Per-avatar animation identity (default idle/walk, gesture intensity, mood) |
| `base` | Explicit base-body id, once more than one parametric base ships |
@@ -106,6 +115,7 @@ Named here so implementations do not claim the keys for anything else:
## Related
+- [`PARAMETRIC_AVATAR.md`](./PARAMETRIC_AVATAR.md): the base body these parameters describe, its morph inventory, and the free-sculpt wire format.
- [`GARMENT_MANIFEST.md`](./GARMENT_MANIFEST.md): the wearables `garments` references.
- [`EDITOR_SPEC.md`](./EDITOR_SPEC.md): the authoring surface these parameters are edited in.
- [`docs/avatar-studio.md`](../docs/avatar-studio.md): the user-facing guide to the editor.
diff --git a/specs/PARAMETRIC_AVATAR.md b/specs/PARAMETRIC_AVATAR.md
new file mode 100644
index 000000000..44359f6fe
--- /dev/null
+++ b/specs/PARAMETRIC_AVATAR.md
@@ -0,0 +1,167 @@
+# Parametric Avatar v1
+
+**Status:** live. Base body, morph library, skeleton proportions and free sculpt all ship. Conforming assets (phase 3), identity capture into parameters (phase 5), texture layers (phase 6) and animation identity (phase 7) are reserved and named at the bottom.
+
+This spec describes the **base body and the editing pipeline over it**: what `parametric-base-v1` is, what a consumer is allowed to assume about it, and which of its capabilities every downstream surface must honour. The serialized record that describes one avatar built on it is [`AVATAR_PARAMETERS.md`](./AVATAR_PARAMETERS.md); the two are read together.
+
+## The architectural decision
+
+**One canonical parametric body. Everything else is a parameter over it.**
+
+Shape is morph targets. Build is skeleton parameters. Anything neither can express is free-sculpt vertex deltas. Garments and hair are conforming attachments that inherit the same skinning. Identity capture (a selfie, a text prompt) is a solver whose *output* is a parameter vector, not a mesh.
+
+Fixed topology is what makes all of that tractable. Because every avatar on this base has the same vertex ordering, the same UVs and the same 52-bone skeleton, a delta recorded on one body is meaningful on another, a garment fitted once fits every variant, and the whole pre-baked animation library retargets by construction.
+
+## `parametric-base-v1`
+
+| Property | Value | Source of truth |
+|---|---|---|
+| Asset | `public/avatars/parametric-base.glb` | `scripts/build-parametric-base.mjs` |
+| Source data | CC0 MakeHuman / MPFB2 | `avatar-sources/anny/README.md` |
+| Skeleton | 52 joints, `mixamorig:*`, Y-up metres, feet on the floor, facing +Z | `avatar-sources/anny/rigs/rig.mixamo.json` |
+| Submeshes | `Body`, `Eyes`, `Teeth`, `Tongue`, one primitive each | `SUBMESHES` in the baker |
+| Body topology | 14517 vertices, 26756 triangles | the GLB |
+| Morph sliders | 306, all sparse glTF morph targets | `MORPHS` in the baker |
+| Hips rest height | 0.912 m | the GLB |
+
+The bone names canonicalize through `src/glb-canonicalize.js`, which is what makes every clip in `public/animations/clips/` play on this rig with no per-rig authoring. `tests/parametric-base.test.js` asserts that, plus geometry validity, morph localization and the budget below.
+
+### Selecting it
+
+Avatar Studio at `/create/studio?base=parametric`. Any surface that loads the GLB directly gets the same body; there is nothing else to opt into.
+
+### Morph inventory
+
+The sculpt panel renders one slider per morph target the loaded GLB exposes, so **the base defines the editor**. Adding a slider is an entry in the baker's `MORPHS` table plus a rebake; no UI change. Current grouping (`CATEGORIES` in `src/avatar-sculpt.js`):
+
+| Group | Sliders | Group | Sliders |
+|---|---|---|---|
+| Eyes | 42 | Neck | 10 |
+| Nose | 36 | Torso | 22 |
+| Mouth | 35 | Hips & Midsection | 17 |
+| Ears | 32 | Arms | 15 |
+| Head Shape | 27 | Legs | 22 |
+| Cheeks | 16 | Body | 12 |
+| Jaw | 14 | Brows | 6 |
+
+Naming rules, because the group a slider lands in is derived from its name and nothing else:
+
+- Face regions keep **per-side** sliders (`earTriangleLeft` / `earTriangleRight`). Facial asymmetry is an identity feature, and the panel's mirror lock already collapses a pair to one control for users who do not want it.
+- Limbs use **one symmetric slider** driving both sides (`armsUpperWider`). A one-armed width edit reads as a defect, not a look.
+- A `decr` / `incr` source pair becomes two `0..1` sliders, because the panel has no negative range.
+- Every name MUST match one category regex. `tests/parametric-base.test.js` fails the build's test stage if a slider would fall into the "Other" drawer.
+
+### The VRAM budget (the real ceiling on slider count)
+
+three.js uploads morph targets as an RGBA32F `DataArrayTexture` with **one dense layer per target**, allocated whether a slider sits at zero or not (`node_modules/three/src/renderers/webgl/WebGLMorphtargets.js`). The cost is therefore `targets x vertices x 16 bytes`, and it is paid by every viewer of every avatar built on this base, not only by the editor.
+
+Sparse glTF accessors keep the *download* small (306 sliders cost 6.5 MB on disk, up from 4.1 MB at 122) and do nothing at all for VRAM. At 306 targets the base needs **68.0 MB**. The baker enforces a **96 MB** ceiling (`MORPH_VRAM_BUDGET_MB`) and a 12 MB file ceiling, and fails the bake rather than shipping past them. `tests/parametric-base.test.js` asserts the same number independently.
+
+Growing well past 306 sliders therefore needs the identity-morph fold described under **Reserved** below, not a bigger budget.
+
+## Editing pipeline
+
+Three parameter classes, in the order they are applied. Each is independent: changing one never invalidates another.
+
+### 1. Morphs (shape)
+
+`appearance.morphs`, `{ name: weight }`. Applied to `morphTargetInfluences` in the browser and to node weights in the bake. Full contract in [`AVATAR_PARAMETERS.md`](./AVATAR_PARAMETERS.md#morphs-shape).
+
+### 2. Proportions (build)
+
+`appearance.proportions`, `{ id: ratio }` around 1.0. A morph cannot lengthen a limb (its deltas are fixed in bind space, so the skin tears off the bone that drives it), so length, width and stature rewrite the rest `position` / `scale` of canonical bones instead.
+
+The maths lives once, in `src/avatar-proportions.js`, and is dependency-free precisely so all three consumers run the identical solver:
+
+| Consumer | Adapter |
+|---|---|
+| Browser live preview | `applyProportionsToRoot` in `src/avatar-proportions.js` |
+| Server bake | `applyProportions` in `api/_lib/bake-proportions.js` |
+| Tests | `computeProportionTransforms` directly |
+
+`tests/bake-proportions.test.js` asserts the browser and server adapters produce bit-comparable bone locals on the real base. Invariants (rotations never written, feet stay grounded, root motion re-measured) are specified in [`AVATAR_PARAMETERS.md`](./AVATAR_PARAMETERS.md#proportions-build).
+
+### 3. Free sculpt (everything else)
+
+`appearance.sculpt`. A radius-and-falloff brush that pushes vertices along their own surface normal, recorded as **one extra morph target per mesh**, named `customSculpt`, pinned at weight 1.
+
+Recording it as a morph target rather than editing `POSITION` is the load-bearing choice: the edit stays additive with every library slider, survives `GLTFExporter` with no special case, can be re-applied to the pristine base from the serialized document, and is reversible by clearing one target.
+
+**Space.** Morph deltas live in bind space; the user is pointing at a skinned, morphed, proportion-edited body on screen. Every stroke builds the exact per-vertex bind-to-world map (`bindMatrixInverse x blended bone matrices x bindMatrix`, then the mesh world matrix), displaces in world space, and maps the result back through that map's inverse. The map is sampled once per drag, at pointer-down, so the host freezes clip playback and the procedural idle while the brush is on (`TalkScene.setRigPaused`, `IdleAnimation.getChannels`).
+
+**Symmetry** mirrors the *brush*, not the vertices: the stroke is applied a second time at the point reflected across the avatar's own X = 0 plane, with the direction reflected too. Turning it off is what makes asymmetry reachable.
+
+**Wire format** (`src/avatar-sculpt-doc.js`, dependency-free so browser, server and tests share it):
+
+```json
+{
+ "version": 1,
+ "meshes": {
+ "Body": {
+ "count": 812,
+ "vertexCount": 14517,
+ "scale": 3.1e-6,
+ "indices": "<base64 Uint32Array[count], little-endian>",
+ "deltas": "<base64 Int16Array[count * 3], little-endian>"
+ }
+ }
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `version` | Document version. A reader MUST reject a version it does not know rather than guess. |
+| `meshes` | Keyed by the three.js mesh name, which equals the glTF mesh name on this base. |
+| `count` | Recorded vertices for this mesh. Capped at `SCULPT_MAX_VERTS` (20000). |
+| `vertexCount` | The mesh's vertex count when the sculpt was recorded. A mismatch means a different topology and the entry MUST be skipped, never force-fitted. |
+| `scale` | Metres per quantisation step. `delta_metres = int16 * scale`. |
+| `indices` | Vertex indices into the mesh's `POSITION`, ascending. |
+| `deltas` | `[dx, dy, dz]` per index, in bind space, clamped to `SCULPT_MAX_DISPLACEMENT` (0.12 m). |
+
+Quantisation is int16 over the recorded peak, which resolves a 0.12 m range to under 4 micrometres: four orders of magnitude finer than anything a viewer can see, and it turns a megabyte of floats into tens of KB of JSON-safe text.
+
+| Consumer | Adapter |
+|---|---|
+| Browser brush + replay | `src/avatar-sculpt-brush.js` |
+| Server bake | `api/_lib/bake-sculpt.js` |
+| Record validation | `sanitizeSculptDoc` in `src/avatar-sculpt-doc.js` |
+
+## Versioning
+
+`base` in the appearance record names the body a document was authored against. Absent means `parametric-v1` for a document that carries `sculpt` or parametric morph names, and "whatever GLB this avatar points at" otherwise, which is the pre-parametric behaviour and stays supported.
+
+- **Morph names are permanent.** Once a slider ships, its name is a public identifier: it is a key in stored records. Renaming one silently drops a user's edit. Add a new slider instead, and leave the old one baked.
+- **Adding sliders is a minor change.** Consumers ignore names they do not have, so an older viewer loading a newer base is a body with fewer controls, never an error.
+- **Changing topology is a major change** and mints a new base id. Vertex ordering is the contract free sculpt, garment fitting and skin-weight transfer all depend on; a body that renumbers its vertices is a different body. Existing avatars keep their old base.
+- **The document versions are independent.** `sculpt.version` describes the delta encoding, not the body.
+
+## What each consumer may ignore
+
+Every consumer MUST **skip what it cannot apply and still render**, never fail the whole avatar. Beyond that:
+
+| Consumer | MUST honour | MAY ignore |
+|---|---|---|
+| Avatar Studio / avatar editor | everything it offers a control for | nothing; an unrenderable field still round-trips untouched on save |
+| Server bake (`api/_lib/bake.js`) | `morphs`, `proportions`, `sculpt`, `colors`, `hidden`, `outfit`, `accessories`, `garments` | `attachments` (never fetched server-side, applied at runtime) |
+| Embeds / `<agent-3d>` | the baked GLB as served | the whole record; it consumes geometry, not parameters |
+| External engines (Blender, Unreal, model-viewer) | the baked GLB | the record entirely |
+| Identity solvers (phase 5) | the named slider set as their output space | any slider the base does not expose |
+
+The rule behind the table: **the record is authoritative for editors, the baked GLB is authoritative for viewers.** A viewer must never need the parameter document to render correctly, and an editor must never need the baked GLB to reconstruct the parameters.
+
+## Reserved
+
+| Item | For |
+|---|---|
+| Identity-morph fold | Folding applied identity morphs into `POSITION` at bake time, with recomputed normals, so a served avatar carries only the ARKit expression targets. That is what lifts the 96 MB budget and unblocks 400+ sliders. It needs correct normal recomputation on a skinned mesh, which is why it is not in v1. |
+| `slots` | Conforming hair and garments auto-fitted to the canonical body (phase 3, `workers/garment-forge`) |
+| `layers` | Texture layers over the canonical UVs: complexion, makeup, tattoos, decals, age maps (phase 6) |
+| `animation` | Per-avatar animation identity: default idle and walk, gesture intensity, mood blend, emote loadout (phase 7) |
+
+## Related
+
+- [`AVATAR_PARAMETERS.md`](./AVATAR_PARAMETERS.md): the serialized appearance record.
+- [`GARMENT_MANIFEST.md`](./GARMENT_MANIFEST.md): the wearables that conform to this body.
+- [`EDITOR_SPEC.md`](./EDITOR_SPEC.md): the authoring surface.
+- [`../docs/avatar-studio.md`](../docs/avatar-studio.md): the user-facing guide.
+- [`../avatar-sources/anny/README.md`](../avatar-sources/anny/README.md): source data and licence.
diff --git a/src/avatar-sculpt.js b/src/avatar-sculpt.js
index 5ff2db061..b183ca96b 100644
--- a/src/avatar-sculpt.js
+++ b/src/avatar-sculpt.js
@@ -172,6 +172,13 @@ const CATEGORIES = [
},
];
+/**
+ * The category table, exported for the parametric-base test, which asserts that
+ * every slider the baker ships lands in a named group instead of the "Other"
+ * drawer. Read-only: mutate the table above, not this alias.
+ */
+export const CATEGORIES_FOR_TEST = CATEGORIES;
+
const ARKIT52 = new Set([
'eyeBlinkLeft','eyeBlinkRight','eyeLookDownLeft','eyeLookDownRight','eyeLookInLeft','eyeLookInRight','eyeLookOutLeft','eyeLookOutRight','eyeLookUpLeft','eyeLookUpRight','eyeSquintLeft','eyeSquintRight','eyeWideLeft','eyeWideRight','jawForward','jawLeft','jawRight','jawOpen','mouthClose','mouthFunnel','mouthPucker','mouthLeft','mouthRight','mouthSmileLeft','mouthSmileRight','mouthFrownLeft','mouthFrownRight','mouthDimpleLeft','mouthDimpleRight','mouthStretchLeft','mouthStretchRight','mouthRollLower','mouthRollUpper','mouthShrugLower','mouthShrugUpper','mouthPressLeft','mouthPressRight','mouthLowerDownLeft','mouthLowerDownRight','mouthUpperUpLeft','mouthUpperUpRight','browDownLeft','browDownRight','browInnerUp','browOuterUpLeft','browOuterUpRight','cheekPuff','cheekSquintLeft','cheekSquintRight','noseSneerLeft','noseSneerRight','tongueOut',
]);
diff --git a/tests/parametric-base.test.js b/tests/parametric-base.test.js
index 1a593eb4e..1d0b55cbf 100644
--- a/tests/parametric-base.test.js
+++ b/tests/parametric-base.test.js
@@ -3,13 +3,17 @@
// scripts/build-parametric-base.mjs.
//
// This is the backbone of the "change everything" avatar editor: one canonical
-// body whose identity is ~120 morph-target sliders. These tests pin the three
+// body whose identity is 300+ morph-target sliders. These tests pin the four
// contracts the rest of the platform depends on:
// 1. the GLB is valid and carries the curated morph set with targetNames,
// 2. the mixamorig skeleton canonicalizes, so the whole pre-baked clip
// library retargets onto it (walk-ready by construction),
// 3. the morphs load as real geometry deltas in three.js, localized to the
-// region their name claims (a nose slider must not move the feet).
+// region their name claims (a nose slider must not move the feet),
+// 4. every slider lands in a named group in the sculpt panel rather than in
+// the "Other" drawer, and the whole set stays inside the VRAM budget the
+// baker enforces (three.js allocates one dense texture layer per morph
+// target, so slider count is a shipped-product cost, not a free one).
import { describe, it, expect, beforeAll } from 'vitest';
import { readFileSync } from 'node:fs';
@@ -54,7 +58,8 @@ describe('parametric-base.glb: validity and inventory', () => {
expect(root.listSkins()[0].listJoints()).toHaveLength(52);
const bodyNames = meshes.Body.getExtras()?.targetNames;
- expect(bodyNames.length).toBeGreaterThanOrEqual(120);
+ expect(bodyNames.length).toBeGreaterThanOrEqual(300);
+ expect(new Set(bodyNames).size).toBe(bodyNames.length); // no shadowed slider
// One representative slider per region.
for (const name of [
'noseWider', 'mouthUpperLipFuller', 'earPointedLeft', 'earPointedRight',
@@ -62,6 +67,14 @@ describe('parametric-base.glb: validity and inventory', () => {
'neckThicker', 'bodyFeminine', 'bodyMasculine', 'bodyMuscular', 'bodyHeavier',
'heightTaller', 'chestVShape', 'waistNarrower', 'hipsWider', 'gluteusBigger',
'bellyBigger', 'shouldersWider', 'armsMuscular', 'thighsThicker', 'legsLonger',
+ // Curation pass 2: the regions that were thin or missing entirely.
+ 'noseBridgeWider', 'noseNostrilsAngleUp', 'mouthPhiltrumDeeper',
+ 'mouthCupidsBowWider', 'earTriangleLeft', 'earTiltForwardRight',
+ 'eyeEpicanthusInLeft', 'eyeUpperLidUpRight', 'browsForward',
+ 'cheekInnerFullerLeft', 'jawBonesStronger', 'foreheadTemplesWider',
+ 'headDiamond', 'neckDoubleChin', 'torsoLatsWider', 'hipsWaistUp',
+ 'bellyNavelUp', 'armsUpperWider', 'legsKneesIn', 'legsUpperLonger',
+ 'bodyAfrican', 'bodyAsian', 'bodyCaucasian',
]) {
expect(bodyNames, name).toContain(name);
}
@@ -136,7 +149,7 @@ describe('parametric-base.glb: three.js runtime behaviour', () => {
if (n.isSkinnedMesh && n.name === 'Body') body = n;
});
expect(body).not.toBeNull();
- expect(Object.keys(body.morphTargetDictionary).length).toBeGreaterThanOrEqual(120);
+ expect(Object.keys(body.morphTargetDictionary).length).toBeGreaterThanOrEqual(300);
const positions = body.geometry.attributes.position;
const inspect = (morphName) => {
@@ -181,3 +194,30 @@ describe('parametric-base.glb: three.js runtime behaviour', () => {
expect(tall.touched).toBeGreaterThan(5000);
});
});
+
+describe('parametric-base.glb: panel grouping and runtime budget', () => {
+ it('files every slider into a named sculpt group, none into "Other"', async () => {
+ const doc = await new NodeIO().read(GLB_PATH);
+ const names = doc
+ .getRoot()
+ .listMeshes()
+ .flatMap((m) => m.getExtras()?.targetNames || []);
+ const unique = [...new Set(names)].filter((n) => n !== 'tongueOut');
+
+ const { CATEGORIES_FOR_TEST } = await import('../src/avatar-sculpt.js');
+ const orphans = unique.filter((n) => !CATEGORIES_FOR_TEST.some((c) => c.match.test(n)));
+ expect(orphans, `ungrouped sliders: ${orphans.join(', ')}`).toEqual([]);
+ });
+
+ it('stays inside the morph-texture VRAM budget the baker enforces', async () => {
+ const doc = await new NodeIO().read(GLB_PATH);
+ // three.js WebGLMorphtargets allocates an RGBA32F layer per target over
+ // the full vertex count, whether the slider is at zero or not.
+ let bytes = 0;
+ for (const mesh of doc.getRoot().listMeshes()) {
+ const prim = mesh.listPrimitives()[0];
+ bytes += prim.getAttribute('POSITION').getCount() * prim.listTargets().length * 16;
+ }
+ expect(bytes / 1024 / 1024).toBeLessThan(96);
+ });
+});