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.

fix(render): retarget server clips through the platform engine so a render matches the browser

nirholas108578687f19
diff --git a/api/_lib/render-cpu.js b/api/_lib/render-cpu.js
index 6a90c238a..9bdc28bb2 100644
--- a/api/_lib/render-cpu.js
+++ b/api/_lib/render-cpu.js
@@ -99,15 +99,34 @@ async function loadCached(glbUrl, { maxBytes, animationUrl }) {
* cache outlives a request, so re-adding the same clip on every call would
* stack duplicates on the mixer.
*
+ * Retargeting runs through the platform's own animation engine
+ * (src/animation-retarget.js, the same one the browser viewer uses), so a
+ * server render and a client render of the same clip land in the same pose:
+ * canonical bone mapping, A-pose/T-pose rest correction, hip-height scaling
+ * and a coverage gate. @three-ws/render carries a simpler name-matching
+ * retargeter of its own for standalone use; it is the fallback here, never
+ * the first choice.
+ *
* Returns the playable clip name, or null when the rig cannot take the clip
- * (a non-humanoid body, or a skeleton with fewer than four matching bones).
- * A null is not an error: the caller renders the model's own pose instead,
- * which is a real render, not a failure page.
+ * (a non-humanoid body, or too few matching bones). A null is not an error:
+ * the caller renders a turntable of the model's own pose instead, which is a
+ * real render, not a failure page.
*/
-function ensureClip(model, clipJson) {
+async function ensureClip(model, clipJson) {
if (!clipJson) return null;
const clip = parseClipJson(clipJson);
if (model.clipNames.includes(clip.name)) return clip.name;
+
+ try {
+ const { retargetClipToObject } = await import('../../src/animation-retarget.js');
+ const result = retargetClipToObject(clip, model.scene);
+ if (result?.clip) {
+ return model.addClips([result.clip], { retarget: false }) > 0 ? result.clip.name : null;
+ }
+ } catch (err) {
+ console.warn('[render] platform retarget unavailable, using the built-in:', err?.message || err);
+ }
+
return model.addClips([clip]) > 0 ? clip.name : null;
}
@@ -148,7 +167,7 @@ export async function renderGlbToPngCpu({
throw Object.assign(new Error('glbUrl required'), { status: 400, code: 'invalid_args' });
}
const model = await loadCached(glbUrl, { maxBytes, animationUrl });
- const posed = clipJson ? ensureClip(model, clipJson) : clip;
+ const posed = clipJson ? await ensureClip(model, clipJson) : clip;
if (posed !== null && posed !== undefined) {
model.play(posed);
model.setTime(time);
@@ -198,7 +217,7 @@ export async function renderGlbToApngCpu({
throw Object.assign(new Error('glbUrl required'), { status: 400, code: 'invalid_args' });
}
const model = await loadCached(glbUrl, { maxBytes, animationUrl });
- const playable = clipJson ? ensureClip(model, clipJson) : clip;
+ const playable = clipJson ? await ensureClip(model, clipJson) : clip;
const rendered = await renderFrames(model, {
width,
height,
diff --git a/packages/render/src/model.js b/packages/render/src/model.js
index 60c63c88f..699113268 100644
--- a/packages/render/src/model.js
+++ b/packages/render/src/model.js
@@ -60,17 +60,24 @@ export class AvatarModel {
}
/**
- * Bind external clips (from an animation-only GLB) onto this skeleton by
- * bone name, so a Mixamo walk drives a Ready Player Me body.
+ * Bind external clips (from an animation-only GLB, or a serialized clip)
+ * onto this skeleton by bone name, so a Mixamo walk drives a Ready Player
+ * Me body.
+ *
+ * @param {THREE.AnimationClip[]} clips
+ * @param {{retarget?: boolean}} [options] Pass `retarget: false` for clips
+ * already bound to this rig's own bone names, which is how a caller
+ * plugs in a stronger retargeting engine of its own.
+ * @returns {number} how many clips were bound
*/
- addClips(clips) {
+ addClips(clips, { retarget = true } = {}) {
const skeleton = this._meshes.find((m) => m.skeleton)?.skeleton;
if (!skeleton) return 0;
let added = 0;
for (const clip of clips) {
- const retargeted = retargetClip(clip, skeleton, this.scene);
- if (retargeted) {
- this.clips.push(retargeted);
+ const bound = retarget ? retargetClip(clip, skeleton, this.scene) : clip;
+ if (bound) {
+ this.clips.push(bound);
added++;
}
}