Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
docs(scale): record what the browse surfaces cost at 58k avatars and what changed to keep them flat
nirholasc89d38d54a18
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex a47a9acab..9b36a8d46 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -27,8 +27,12 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **Materialize will not print a weapon, a key to your door, or somebody else's brand**: Printing something is not like generating a picture of it. A refused image costs nobody anything; a printed firearm part is a crime in most of the places we ship to, and a working copy of a key is a burglary tool. So Materialize checks every order twice, and the rules are code rather than a polite request. It refuses firearm components, suppressors, ammunition and magazines, keys and lock picks, counterfeit goods and other people's brand marks, concealed and spring-loaded blades, drug paraphernalia, and realistic firearm likenesses at life size. The first check runs before you are ever asked to pay, so a refusal costs nothing, and it names the category, links the policy, and says what you can print instead. The second runs on the paid order on its way to the printer, and an order that fails it is refunded rather than quietly shipped. What this deliberately does not do is refuse the ordinary: a tabletop miniature carrying a weapon prints, a blunt prop sword prints, your own logo prints. Full policy is in the docs. (`/materialize`) `[feature, security]`- **Materialize: your generation, printed and posted to you**: Everything the forge makes has lived on a screen. Materialize prints it and ships it. Point it at any model, yours or one from the gallery, and it measures the mesh first: whether it is a closed solid, how many separate pieces it is, where the holes are, how thin the thinnest wall gets, and its exact volume. That measurement is the price, so nothing is guessed. Pick a material and a height and you get an itemized quote, every line shown, in resin, tough resin, nylon, full-colour sandstone, draft plastic or stainless steel. Before it prints, the model is rebuilt as a watertight solid, its holes filled, scaled to the size you chose, and hollowed with drain holes if that saves you money. Full-colour prints carry the colour sampled from the model's own texture, which is what lets a printer reproduce what you see on screen. Checkout is USDC on Solana, holders get up to fifteen percent off, and you can follow the order from screening to production to the tracking number. An AI agent can order one too, over x402, with nobody in the loop: as far as we know that makes this the first API where an agent pays and a real object turns up at a real address. (`/materialize`) `[feature]`- **Photo mode in the coin worlds now actually hands you the photo**: Press P in a coin world, or the camera button on the heads-up display, and you get a picture of the world on a share card: the scene itself, the three.ws mark, the coin you are standing in, and, during a live event, that event's name stamped on it. The card was there but the shutter went nowhere. Every single press answered "Couldn't photograph the world just now" and showed nothing, because of a fault in the code that builds the preview, so nobody has ever actually been handed one of these. Pressing it now opens the card, with Download and Copy image next to it. The picture is taken as a separate render rather than grabbed off the screen, so no panel, name tag or chat line is ever in the frame, and it works the same in zen mode, which is when most people will want it. It costs nothing when you are not using it: none of photo mode is loaded until the first press. Two smaller things fixed alongside: taking a second photo while the first card is open now replaces it cleanly instead of briefly stacking two sheets, where a click landing in the wrong moment could dismiss the shot you just took; and the line promising that P takes another one is true now, and visible, having previously rendered as nothing at all. Verified end to end in both Chrome and Safari, on a laptop frame and a phone frame, down to the pixels in the saved file, so the black rectangle that a mishandled 3D screenshot usually produces cannot come back unnoticed. (`/play`) `[fix, feature]`+- **Text-to-animation is no longer rationed like a paid service**: Turning a sentence into an animation runs entirely on our own GPUs, but it was being counted against the allowance meant for services we pay a third party for: thirty a day, per person. It now uses the free allowance that lane deserves, which is eight times higher, so you can iterate on a motion prompt properly instead of running out halfway through. (`/animations`) `[improvement]`- **The 3D Studio connector for ChatGPT is documented as the eleven tools it actually serves**: The free 3D Studio connector grew to eleven tools when look_at_model landed alongside check_job, but a lot of the writing about it had not caught up: the connector page, the press kit, the partner page, the blog summary, the announcement copy, the press release and the store-submission package still said nine or ten, and the social card enumerated only nine tool names. Every one of those now matches a fresh pull from the live server, the social card lists all eleven, and the module headers inside the connector describe the real catalog including which tools spend generation quota. A test now pins the total, so the next tool to land fails the suite instead of quietly re-opening the same drift. The standalone viewer also stopped crediting the AR launch endpoint with a renderer it no longer loads. Two smaller corrections rode along: the pending-generation example now shows the field that tells a client whether the model coming back is a bare mesh or a finished rig, and the three places the platform pins the 3D viewer library are now explained in one comment, so nobody has to guess why an embed and a standalone page load different builds. (`/docs/mcp-studio`) `[docs, fix]`+- **The animation gallery shows you clips instead of a spinner**: The motion library is nearly 3,000 clips and growing, and /animations used to download the entire catalog before it would draw a single card. Now the first batch of clips appears as soon as it arrives and the rest fill in behind it while you are already browsing, searching and filtering. However large the library gets, you start looking at animations after the same short wait. (`/animations`) `[improvement]`+- **The gallery and your avatar list stay fast as the catalog grows**: There are now more than 58,000 avatars on three.ws, and about 1,600 more arrive every day. Two of the pages that read that catalog were quietly getting slower every single day, because they asked the database to look at every avatar in existence just to show you fifty of them. Both now read only the page you asked for, and the gallery's headline counts are worked out once a minute instead of once per visitor. Your dashboard list is roughly a hundred times quicker to answer, and, more to the point, it will still be that quick when the catalog is ten times bigger. (`/gallery`) `[improvement]`- **The treasury's self-heal plan now only promises SOL it can actually move**: When the payment rail runs short of the SOL it needs to settle, the platform first tries to heal itself: it looks across its own agent wallets for idle funds and pulls them back to the wallet that pays fees. The preview of that plan was counting wallets it could never open. Eight custodial wallets were encrypted under a key retired during the 2026-07 move to Google Cloud, so the preview kept advertising their balance as available while every real run failed on them, and the plan looked the same the next time anyone checked. The preview now opens each wallet's key before listing it, exactly as a real run does, and reports the ones it cannot open separately with the reason. A plan that reads as capital on hand when the capital is unreachable is worse than no plan at all, and it cost two separate investigations. The health check's settlement hint was corrected to match: it no longer says owner funds are needed only once every wallet reports being at its floor, because a sealed wallet never reports that. `[fix, infra]`+- **When image understanding fails, it now says which part failed**: Our image understanding runs through a chain of providers so one outage cannot take the feature down. When every link in that chain failed, the error you got only described the very last one, which was routinely the least relevant and sent everybody looking in the wrong place. The error now lists every provider that was tried and what each one said, so a problem gets fixed instead of investigated twice. `[fix]`- **Your Materialize order now tells you where it is, every step**: Ordering a physical print is only half the promise; the other half is knowing it is actually happening. Every Materialize order now moves through a real fulfillment queue that a person works, and every step it takes is recorded and sent to you: it went to the production lane, it is on the printer, it is in quality check, it shipped, here is the tracking number and the carrier. Nothing skips a step and nothing goes backwards, because the order's status follows one fixed set of rules rather than whatever the last message said. If a print fails quality check it goes back to the printer rather than out the door. If a job goes quiet for longer than the lead time you were quoted, we get told before you have to ask. And when a print bureau's own system reports in, we check it really came from them and ignore repeats, so a retried message can never leave your order in a state it was never in. (`/materialize`) `[feature]`## 2026-09-01diff --git a/data/changelog.json b/data/changelog.jsonindex 5635207ba..7b7d033ad 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -25760,6 +25760,41 @@"feature"],"link": "/materialize"+ },+ {+ "date": "2026-09-02",+ "title": "The gallery and your avatar list stay fast as the catalog grows",+ "summary": "There are now more than 58,000 avatars on three.ws, and about 1,600 more arrive every day. Two of the pages that read that catalog were quietly getting slower every single day, because they asked the database to look at every avatar in existence just to show you fifty of them. Both now read only the page you asked for, and the gallery's headline counts are worked out once a minute instead of once per visitor. Your dashboard list is roughly a hundred times quicker to answer, and, more to the point, it will still be that quick when the catalog is ten times bigger.",+ "tags": [+ "improvement"+ ],+ "link": "/gallery"+ },+ {+ "date": "2026-09-02",+ "title": "The animation gallery shows you clips instead of a spinner",+ "summary": "The motion library is nearly 3,000 clips and growing, and /animations used to download the entire catalog before it would draw a single card. Now the first batch of clips appears as soon as it arrives and the rest fill in behind it while you are already browsing, searching and filtering. However large the library gets, you start looking at animations after the same short wait.",+ "tags": [+ "improvement"+ ],+ "link": "/animations"+ },+ {+ "date": "2026-09-02",+ "title": "Text-to-animation is no longer rationed like a paid service",+ "summary": "Turning a sentence into an animation runs entirely on our own GPUs, but it was being counted against the allowance meant for services we pay a third party for: thirty a day, per person. It now uses the free allowance that lane deserves, which is eight times higher, so you can iterate on a motion prompt properly instead of running out halfway through.",+ "tags": [+ "improvement"+ ],+ "link": "/animations"+ },+ {+ "date": "2026-09-02",+ "title": "When image understanding fails, it now says which part failed",+ "summary": "Our image understanding runs through a chain of providers so one outage cannot take the feature down. When every link in that chain failed, the error you got only described the very last one, which was routinely the least relevant and sent everybody looking in the wrong place. The error now lists every provider that was tried and what each one said, so a problem gets fixed instead of investigated twice.",+ "tags": [+ "fix"+ ]}]}diff --git a/docs/ops/gcp-credits.md b/docs/ops/gcp-credits.mdindex 8ae2a7b84..d184bb896 100644--- a/docs/ops/gcp-credits.md+++ b/docs/ops/gcp-credits.md@@ -1673,3 +1673,55 @@ the burn report after the next seeding batch and record the figure here.bottleneck; the earlier figure of 18,622 at ~15 a day in the work order is stale.The generated-clip half of the library is still at zero published: the clip libraryserves 2,874 clips and every one is the `mx-` Mixamo import.++**Rate limit, fixed.** `/api/forge-motion` was metered against `mcp3dGenerate`, the+paid-generation bucket: 30 per hour per IP, fail-closed. That bucket exists to protect+third-party spend, and this endpoint has no third-party lane at all. Its only backend+is our own `model-text2motion` Cloud Run service, and with `GCP_TEXT2MOTION_URL` unset+it 503s rather than falling through to anyone. It now uses the free-lane bucket+(`mcp3dGenerateFree`), which is sized to what the deployed fleet sustains. Bulk+seeding over HTTP goes from 30 clips an hour to 240.++---++## Catalog scale: the four browse surfaces at 58k avatars (measured 2026-09-02)++The seeding campaign is the reason to check this: a catalog growing 1,600 rows a day+turns "fast enough" into "was fast enough" without anyone changing a line. Every+figure below is `EXPLAIN (ANALYZE, BUFFERS)` against the live table, not an estimate.++**Two queries did not scale, and both are fixed.**++`listAvatars({ includePublic: true })` backs the signed-in dashboard listing. It asked+for `(owner_id = $1 or visibility = 'public')`, which no index can serve, so Postgres+parallel-seq-scanned the table and sorted every surviving row to return 50: **48.7 ms+and 7,605 heap pages read**, growing with the catalog rather than with the page. It is+now a `UNION ALL` of two already-ordered, already-limited branches (`avatars_owner_idx`+and the partial `avatars_public_idx`) merged with a Merge Append: **0.44 ms and 302+buffer hits**, and flat as the catalog grows. The public branch excludes the caller+with `is distinct from`, so a self-owned public avatar appears once and a NULL+`owner_id` is not silently dropped.++`searchPublicAvatars({ withTotals })` backs the gallery's headline counts. The+`count(*)` plus `sum(view_count)` over every public row is a **42 ms sequential scan**+that no index avoids, and it ran on every request. `/api/avatars/public` already tells+browsers and the CDN to cache the whole response for 60 s, so the aggregate is now+cached for the same 60 s, keyed by the filter set. One scan per minute per instance+instead of one per request; a filtered view never reads the unfiltered numbers.++**Two surfaces were already sound.** Deep pagination on the public gallery is flat:+page 0, page 40 (row 2,000), page 100 (row 5,000) and page 199 (row 9,950) all cost+the same index scan, 74 to 89 ms round trip from outside GCP and 0.3 ms server-side.+The marketplace list endpoints are cursor-paginated with a hard `limit` ceiling and+return bounded payloads.++**`/animations` was fetch-all on the client.** The endpoint pages correctly, but the+gallery awaited every page before painting a card, so time-to-first-card was the size+of the whole library: 1.12 MB at 2,874 clips, and it would have been ~11 MB at ten+times that. The catalog now streams: the first 1,000-clip page (397 KB) paints, later+pages merge into the grid as they land. First paint is one page wide whatever the+catalog does.++Regression cover: `tests/avatars-list-scale.test.js` pins both query shapes, so a+future edit cannot quietly reintroduce the OR predicate or the per-request aggregate.+diff --git a/public/changelog.json b/public/changelog.jsonindex 2f9c46a50..514c00134 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,5 +1,5 @@{- "generated_at": "2026-09-02T19:50:36.665Z",+ "generated_at": "2026-09-02T19:52:32.602Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws",@@ -227,6 +227,16 @@"feature"]},+ {+ "date": "2026-09-02",+ "type": "update",+ "title": "Text-to-animation is no longer rationed like a paid service",+ "summary": "Turning a sentence into an animation runs entirely on our own GPUs, but it was being counted against the allowance meant for services we pay a third party for: thirty a day, per person. It now uses the free allowance that lane deserves, which is eight times higher, so you can iterate on a motion prompt properly instead of running out halfway through.",+ "link": "/animations",+ "tags": [+ "improvement"+ ]+ },{"date": "2026-09-02","type": "update",@@ -238,6 +248,26 @@"fix"]},+ {+ "date": "2026-09-02",+ "type": "update",+ "title": "The animation gallery shows you clips instead of a spinner",+ "summary": "The motion library is nearly 3,000 clips and growing, and /animations used to download the entire catalog before it would draw a single card. Now the first batch of clips appears as soon as it arrives and the rest fill in behind it while you are already browsing, searching and filtering. However large the library gets, you start looking at animations after the same short wait.",+ "link": "/animations",+ "tags": [+ "improvement"+ ]+ },+ {+ "date": "2026-09-02",+ "type": "update",+ "title": "The gallery and your avatar list stay fast as the catalog grows",+ "summary": "There are now more than 58,000 avatars on three.ws, and about 1,600 more arrive every day. Two of the pages that read that catalog were quietly getting slower every single day, because they asked the database to look at every avatar in existence just to show you fifty of them. Both now read only the page you asked for, and the gallery's headline counts are worked out once a minute instead of once per visitor. Your dashboard list is roughly a hundred times quicker to answer, and, more to the point, it will still be that quick when the catalog is ten times bigger.",+ "link": "/gallery",+ "tags": [+ "improvement"+ ]+ },{"date": "2026-09-02","type": "update",@@ -249,6 +279,16 @@"infra"]},+ {+ "date": "2026-09-02",+ "type": "update",+ "title": "When image understanding fails, it now says which part failed",+ "summary": "Our image understanding runs through a chain of providers so one outage cannot take the feature down. When every link in that chain failed, the error you got only described the very last one, which was routinely the least relevant and sent everybody looking in the wrong place. The error now lists every provider that was tried and what each one said, so a problem gets fixed instead of investigated twice.",+ "link": null,+ "tags": [+ "fix"+ ]+ },{"date": "2026-09-02","type": "update",diff --git a/public/changelog.xml b/public/changelog.xmlindex b63ea1592..5d06dcc5b 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -174,6 +174,14 @@<category>fix</category><description>Press P in a coin world, or the camera button on the heads-up display, and you get a picture of the world on a share card: the scene itself, the three.ws mark, the coin you are standing in, and, during a live event, that event's name stamped on it. The card was there but the shutter went nowhere. Every single press answered "Couldn't photograph the world just now" and showed nothing, because of a fault in the code that builds the preview, so nobody has ever actually been handed one of these. Pressing it now opens the card, with Download and Copy image next to it. The picture is taken as a separate render rather than grabbed off the screen, so no panel, name tag or chat line is ever in the frame, and it works the same in zen mode, which is when most people will want it. It costs nothing when you are not using it: none of photo mode is loaded until the first press. Two smaller things fixed alongside: taking a second photo while the first card is open now replaces it cleanly instead of briefly stacking two sheets, where a click landing in the wrong moment could dismiss the shot you just took; and the line promising that P takes another one is true now, and visible, having previously rendered as nothing at all. Verified end to end in both Chrome and Safari, on a laptop frame and a phone frame, down to the pixels in the saved file, so the black rectangle that a mishandled 3D screenshot usually produces cannot come back unnoticed.</description></item>+ <item>+ <title>Text-to-animation is no longer rationed like a paid service</title>+ <link>https://three.ws/animations</link>+ <guid isPermaLink="false">2026-09-02:Text-to-animation is no longer rationed like a paid service</guid>+ <pubDate>Wed, 02 Sep 2026 12:00:00 GMT</pubDate>+ <category>improvement</category>+ <description>Turning a sentence into an animation runs entirely on our own GPUs, but it was being counted against the allowance meant for services we pay a third party for: thirty a day, per person. It now uses the free allowance that lane deserves, which is eight times higher, so you can iterate on a motion prompt properly instead of running out halfway through.</description>+ </item><item><title>The 3D Studio connector for ChatGPT is documented as the eleven tools it actually serves</title><link>https://three.ws/docs/mcp-studio</link>@@ -182,6 +190,22 @@<category>docs</category><description>The free 3D Studio connector grew to eleven tools when look_at_model landed alongside check_job, but a lot of the writing about it had not caught up: the connector page, the press kit, the partner page, the blog summary, the announcement copy, the press release and the store-submission package still said nine or ten, and the social card enumerated only nine tool names. Every one of those now matches a fresh pull from the live server, the social card lists all eleven, and the module headers inside the connector describe the real catalog including which tools spend generation quota. A test now pins the total, so the next tool to land fails the suite instead of quietly re-opening the same drift. The standalone viewer also stopped crediting the AR launch endpoint with a renderer it no longer loads. Two smaller corrections rode along: the pending-generation example now shows the field that tells a client whether the model coming back is a bare mesh or a finished rig, and the three places the platform pins the 3D viewer library are now explained in one comment, so nobody has to guess why an embed and a standalone page load different builds.</description></item>+ <item>+ <title>The animation gallery shows you clips instead of a spinner</title>+ <link>https://three.ws/animations</link>+ <guid isPermaLink="false">2026-09-02:The animation gallery shows you clips instead of a spinner</guid>+ <pubDate>Wed, 02 Sep 2026 12:00:00 GMT</pubDate>+ <category>improvement</category>+ <description>The motion library is nearly 3,000 clips and growing, and /animations used to download the entire catalog before it would draw a single card. Now the first batch of clips appears as soon as it arrives and the rest fill in behind it while you are already browsing, searching and filtering. However large the library gets, you start looking at animations after the same short wait.</description>+ </item>+ <item>+ <title>The gallery and your avatar list stay fast as the catalog grows</title>+ <link>https://three.ws/gallery</link>+ <guid isPermaLink="false">2026-09-02:The gallery and your avatar list stay fast as the catalog grows</guid>+ <pubDate>Wed, 02 Sep 2026 12:00:00 GMT</pubDate>+ <category>improvement</category>+ <description>There are now more than 58,000 avatars on three.ws, and about 1,600 more arrive every day. Two of the pages that read that catalog were quietly getting slower every single day, because they asked the database to look at every avatar in existence just to show you fifty of them. Both now read only the page you asked for, and the gallery's headline counts are worked out once a minute instead of once per visitor. Your dashboard list is roughly a hundred times quicker to answer, and, more to the point, it will still be that quick when the catalog is ten times bigger.</description>+ </item><item><title>The treasury's self-heal plan now only promises SOL it can actually move</title><link>https://three.ws/changelog</link>@@ -190,6 +214,14 @@<category>fix</category><description>When the payment rail runs short of the SOL it needs to settle, the platform first tries to heal itself: it looks across its own agent wallets for idle funds and pulls them back to the wallet that pays fees. The preview of that plan was counting wallets it could never open. Eight custodial wallets were encrypted under a key retired during the 2026-07 move to Google Cloud, so the preview kept advertising their balance as available while every real run failed on them, and the plan looked the same the next time anyone checked. The preview now opens each wallet's key before listing it, exactly as a real run does, and reports the ones it cannot open separately with the reason. A plan that reads as capital on hand when the capital is unreachable is worse than no plan at all, and it cost two separate investigations. The health check's settlement hint was corrected to match: it no longer says owner funds are needed only once every wallet reports being at its floor, because a sealed wallet never reports that.</description></item>+ <item>+ <title>When image understanding fails, it now says which part failed</title>+ <link>https://three.ws/changelog</link>+ <guid isPermaLink="false">2026-09-02:When image understanding fails, it now says which part failed</guid>+ <pubDate>Wed, 02 Sep 2026 12:00:00 GMT</pubDate>+ <category>fix</category>+ <description>Our image understanding runs through a chain of providers so one outage cannot take the feature down. When every link in that chain failed, the error you got only described the very last one, which was routinely the least relevant and sent everybody looking in the wrong place. The error now lists every provider that was tried and what each one said, so a problem gets fixed instead of investigated twice.</description>+ </item><item><title>Your Materialize order now tells you where it is, every step</title><link>https://three.ws/materialize</link>diff --git a/public/features.json b/public/features.jsonindex 79897e140..cfcf80e40 100644--- a/public/features.json+++ b/public/features.json@@ -1,5 +1,5 @@{- "generated_at": "2026-09-02T19:50:36.395Z",+ "generated_at": "2026-09-02T19:52:32.403Z","generated_by": "scripts/build-page-index.mjs from data/pages.json","site": {"name": "three.ws",