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
// One searchable read model over every ready-made asset library three.ws
// publishes: the CC0 object/prop library, the ready-made character library, and
// the motion-clip library. Each of those already has a browse page and a REST
// endpoint of its own, but nothing joined them, so an agent could not ask "what
// does three.ws already have that I can drop in?" without knowing which of three
// manifests to read and how each one names its fields.
//
// The manifests live on R2 and are read here directly (same keys the
// /api/objects/library, /api/avatars/library and /api/animations/library
// handlers use) rather than over HTTP against our own origin: a self-call would
// add a round trip, a TLS handshake, and a second failure mode for data we can
// read from storage in one hop.
//
// Every item is normalized to ONE shape so a caller filters, ranks, and renders
// all three kinds with the same code:
//
// { id, kind, name, title, categories[], tags[], license, url, thumb, bytes, ... }
//
// `id` is `<kind>:<name>` and is the stable handle every consumer quotes back.
import { getPublicObjectBuffer } from './r2.js';
// Each source: the R2 manifest key, the array field inside it, and the kind the
// rows become. The generated animation catalog is a separate object that may not
// exist yet, exactly as api/animations/library.js treats it.
const SOURCES = [
{ kind: 'object', key: 'objects/library/manifest.json', field: 'objects' },
{ kind: 'character', key: 'avatars/library/manifest.json', field: 'avatars' },
{ kind: 'animation', key: 'animations/library/manifest.json', field: 'clips' },
{ kind: 'animation', key: 'animations/library/generated/manifest.json', field: 'clips' },
];
export const KINDS = ['object', 'character', 'animation'];
// Manifests change only when a publish job runs, so a short process-local TTL
// removes almost every storage read while keeping a fresh publish visible within
// minutes. Concurrent misses share one load (INFLIGHT) instead of each firing
// four R2 GETs.
const TTL_MS = 5 * 60 * 1000;
let CACHE = null;
let INFLIGHT = null;
function asArray(parsed, field) {
if (Array.isArray(parsed)) return parsed;
if (parsed && Array.isArray(parsed[field])) return parsed[field];
return [];
}
async function readManifest({ key, field }) {
try {
const buf = await getPublicObjectBuffer(key);
const parsed = JSON.parse(buf.toString('utf8'));
return {
rows: asArray(parsed, field),
generatedAt: parsed?.generated_at || null,
degraded: false,
};
} catch (err) {
// A manifest that was never published is the expected steady state for the
// generated catalog, so it degrades to empty and is NOT flagged. Anything
// else is logged, still degrades to empty (a catalog missing one kind is
// far more useful than a hard failure that hides the other two), and is
// signalled with `degraded: true` so callers can tell "nothing published"
// from "storage is down" and refuse to cache the partial answer.
const code = err?.$metadata?.httpStatusCode;
const degraded = err?.name !== 'NoSuchKey' && code !== 404;
if (degraded) console.error('[asset-catalog]', key, err?.message || err);
return { rows: [], generatedAt: null, degraded };
}
}
function cleanList(value) {
if (!Array.isArray(value)) return [];
const out = [];
for (const entry of value) {
const s = String(entry ?? '').trim();
if (s && !out.includes(s)) out.push(s);
}
return out;
}
// The object manifest folds provenance into `categories` as "collection: x".
// That is browse metadata, not a category a caller would ever filter on, so it
// is lifted out to `collection` and dropped from the facet list.
function splitCategories(raw) {
const categories = [];
let collection = null;
for (const entry of cleanList(raw)) {
const m = /^collection:\s*(.+)$/i.exec(entry);
if (m) {
if (!collection) collection = m[1].trim();
continue;
}
categories.push(entry);
}
return { categories, collection };
}
function normalize(row, kind) {
const name = String(row?.name ?? '').trim();
if (!name) return null;
const title = String(row?.label || row?.name || '').trim() || name;
const { categories, collection } = splitCategories(row?.categories);
const base = {
id: `${kind}:${name}`,
kind,
name,
title,
categories,
tags: cleanList(row?.tags),
license: String(row?.license || '').trim() || null,
url: typeof row?.url === 'string' ? row.url : null,
thumb: typeof row?.thumb === 'string' ? row.thumb : null,
bytes: Number.isFinite(row?.bytes) ? row.bytes : null,
};
if (collection) base.collection = collection;
const attribution = String(row?.attribution || '').trim();
if (attribution) base.attribution = attribution;
if (kind === 'animation') {
base.format = 'three-animation-clip-json';
base.duration_seconds = Number.isFinite(row?.duration) ? row.duration : null;
base.loop = row?.loop !== false;
if (row?.icon) base.icon = row.icon;
} else {
base.format = 'glb';
if (kind === 'character') {
base.rigged = true;
base.skins = Number.isFinite(row?.skins) ? row.skins : null;
base.baked_animations = Number.isFinite(row?.animations) ? row.animations : null;
base.source = row?.source || null;
}
}
return base;
}
/**
* Load and normalize every library, deduped by id (a curated clip wins over a
* generated one of the same name, matching /api/animations/library) and sorted
* by kind then title so paging is stable across calls.
*
* @returns {Promise<{ items: object[], generated_at: object, counts: object, total: number, degraded: boolean }>}
* `degraded` is true when any manifest read failed for a reason other than
* "never published", so the item list may be missing a whole kind.
*/
async function loadCatalog() {
const results = await Promise.all(SOURCES.map((s) => readManifest(s)));
const byId = new Map();
const generatedAt = {};
const degraded = results.some((r) => r.degraded);
for (let i = 0; i < SOURCES.length; i++) {
const { kind } = SOURCES[i];
const { rows, generatedAt: at } = results[i];
if (at && !generatedAt[kind]) generatedAt[kind] = at;
for (const row of rows) {
const item = normalize(row, kind);
if (item && !byId.has(item.id)) byId.set(item.id, item);
}
}
const items = [...byId.values()].sort(
(a, b) => a.kind.localeCompare(b.kind) || a.title.localeCompare(b.title),
);
const counts = {};
for (const kind of KINDS) counts[kind] = items.filter((i) => i.kind === kind).length;
return { items, generated_at: generatedAt, counts, total: items.length, degraded };
}
/** The cached catalog, refreshed at most once per TTL. Concurrent misses share one load. */
export async function getCatalog({ force = false } = {}) {
const fresh = CACHE && !force && Date.now() - CACHE.at < TTL_MS;
if (fresh) return CACHE.value;
if (INFLIGHT) return INFLIGHT;
INFLIGHT = loadCatalog()
.then((value) => {
// A degraded load is served once but never memoized, so the next call
// retries storage instead of repeating a partial catalog for the TTL.
if (!value.degraded) CACHE = { at: Date.now(), value };
return value;
})
.finally(() => {
INFLIGHT = null;
});
return INFLIGHT;
}
/** Drop the memo. Used by tests to re-read a changed manifest without waiting out the TTL. */
export function resetCatalogCache() {
CACHE = null;
INFLIGHT = null;
}
function tokenize(query) {
return String(query || '')
.toLowerCase()
.split(/[^a-z0-9]+/)
.filter((t) => t.length > 1);
}
// Weighted term match. A title hit ranks above a tag hit, which ranks above a
// category hit, and a whole-word match ranks above a substring one, so "wrench"
// puts "Adjustable Wrench" above a chair tagged "wrenched metal". Every term
// must land somewhere or the item is not a result at all (AND across terms),
// which keeps a two-word query from returning everything that matches either.
function scoreItem(item, terms, { requireAll = true } = {}) {
if (!terms.length) return 1;
const title = item.title.toLowerCase();
const name = item.name.toLowerCase();
const tags = item.tags.map((t) => t.toLowerCase());
const cats = item.categories.map((c) => c.toLowerCase());
let total = 0;
let matched = 0;
for (const term of terms) {
let best = 0;
if (title === term) best = 10;
else if (title.split(/\s+/).includes(term)) best = 8;
else if (title.includes(term)) best = 6;
if (best < 5 && (name === term || name.split(/[-_]/).includes(term))) best = 5;
if (best < 4 && tags.includes(term)) best = 4;
if (best < 3 && tags.some((t) => t.includes(term))) best = 3;
if (best < 2 && cats.some((c) => c.includes(term))) best = 2;
if (best < 1 && name.includes(term)) best = 1;
if (!best && requireAll) return 0;
if (best) matched++;
total += best;
}
// Under OR, an item matching more of the terms still outranks one matching
// fewer, so "office lamp" puts a lamp tagged office above a bare lamp.
return requireAll ? total : matched ? total + matched * 4 : 0;
}
/**
* Search the joined catalog.
*
* @param {object} opts
* @param {string} [opts.q] Free text over title, name, tags, categories.
* @param {string} [opts.kind] One of KINDS.
* @param {string} [opts.category] Exact (case-insensitive) category match.
* @param {string} [opts.tag] Exact (case-insensitive) tag match.
* @param {number} [opts.limit] Page size (default 12).
* @param {number} [opts.offset] Page offset (default 0).
* @returns {Promise<{ items, total, matched, relaxed, offset, next_offset, facets, generated_at, degraded }>}
*/
export async function searchCatalog({ q, kind, category, tag, limit = 12, offset = 0 } = {}) {
const catalog = await getCatalog();
const terms = tokenize(q);
const wantKind = kind ? String(kind).toLowerCase() : null;
const wantCategory = category ? String(category).toLowerCase() : null;
const wantTag = tag ? String(tag).toLowerCase() : null;
const candidates = catalog.items.filter((item) => {
if (wantKind && item.kind !== wantKind) return false;
if (wantCategory && !item.categories.some((c) => c.toLowerCase() === wantCategory)) return false;
if (wantTag && !item.tags.some((t) => t.toLowerCase() === wantTag)) return false;
return true;
});
const rank = (requireAll) => {
const out = [];
for (const item of candidates) {
const score = scoreItem(item, terms, { requireAll });
if (score) out.push({ item, score });
}
// Ties break on title so two calls with the same query return the same
// order, which is what makes offset paging safe.
out.sort((a, b) => b.score - a.score || a.item.title.localeCompare(b.item.title));
return out;
};
// Every term must land (AND), because that is what makes a two-word query
// precise. But a caller who types "office lamp" against a library that tags
// neither word together deserves the lamps, not an empty page, so a query
// that finds nothing under AND is retried under OR and the response says so.
let scored = rank(true);
let relaxed = false;
if (!scored.length && terms.length > 1) {
scored = rank(false);
relaxed = scored.length > 0;
}
const start = Math.max(0, offset);
const page = scored.slice(start, start + Math.max(1, limit)).map((s) => s.item);
return {
items: page,
matched: scored.length,
relaxed,
total: catalog.total,
offset: start,
next_offset: start + page.length < scored.length ? start + page.length : null,
facets: facetsFor(scored.map((s) => s.item)),
generated_at: catalog.generated_at,
degraded: catalog.degraded,
};
}
/** Kind counts plus the most common categories and tags across a result set. */
function facetsFor(items) {
const kinds = {};
const categories = new Map();
const tags = new Map();
for (const item of items) {
kinds[item.kind] = (kinds[item.kind] || 0) + 1;
for (const c of item.categories) categories.set(c, (categories.get(c) || 0) + 1);
for (const t of item.tags) tags.set(t, (tags.get(t) || 0) + 1);
}
const top = (map, n) =>
[...map.entries()]
.sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
.slice(0, n)
.map(([value, count]) => ({ value, count }));
return { kinds, categories: top(categories, 12), tags: top(tags, 12) };
}
/** One item by `<kind>:<name>` id, or null. A bare name is accepted and resolved across kinds. */
export async function getCatalogItem(id) {
const catalog = await getCatalog();
const raw = String(id || '').trim();
if (!raw) return null;
const exact = catalog.items.find((i) => i.id === raw);
if (exact) return exact;
return catalog.items.find((i) => i.name === raw) || null;
}
/**
* Up to `limit` other items of the same kind that share the most tags and
* categories with `item`. Used to answer "what else goes with this?" without a
* second search round trip.
*/
export async function relatedItems(item, limit = 6) {
if (!item) return [];
const catalog = await getCatalog();
const tags = new Set(item.tags.map((t) => t.toLowerCase()));
const cats = new Set(item.categories.map((c) => c.toLowerCase()));
const scored = [];
for (const other of catalog.items) {
if (other.id === item.id || other.kind !== item.kind) continue;
let score = 0;
for (const t of other.tags) if (tags.has(t.toLowerCase())) score += 2;
for (const c of other.categories) if (cats.has(c.toLowerCase())) score += 1;
if (score) scored.push({ other, score });
}
scored.sort((a, b) => b.score - a.score || a.other.title.localeCompare(b.other.title));
return scored.slice(0, limit).map((s) => s.other);
}