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(motion): write up the loop seam fix and record it against the credits programme

nirholas24af56f37417
diff --git a/docs/animation-seeding.md b/docs/animation-seeding.md
index b3a9d1307..48604dff1 100644
--- a/docs/animation-seeding.md
+++ b/docs/animation-seeding.md
@@ -83,6 +83,39 @@ motion we asked for, so those rules are correct where they are applied.
Re-run the calibration whenever a threshold changes, and inspect rejected clips before
touching a number. A broken pipeline looks exactly like a strict gate.
+## Loop seams
+
+A motion-diffusion sampler does not produce seamless loops. It samples a window, and
+the last frame has no reason to meet the first. This matters because **41% of the
+prompt library (56 of 137) is tagged `loop`**, concentrated exactly where looping
+matters: locomotion (16 of 20), dance (10 of 12), idle (10 of 14).
+
+Measured on real output, a generated walk ends **0.25 m** per joint from where it
+started (hips-relative), against **0.000** for the authored library's loops. Published
+as-is, every one of those clips would visibly pop once a cycle.
+
+`closeLoopSeam(clip)` fixes it in two steps:
+
+1. **Trim to the cycle.** Search the tail for the frame whose pose is closest to frame
+ 0 and cut there. For a periodic motion the cycle really is in the clip already. A
+ trim is only taken if it beats the untrimmed seam by a clear margin, and never cuts
+ more than 35% of the clip.
+2. **Blend what is left.** Over the final frames, slerp each rotation onto the value it
+ holds at frame 0, so the seam closes exactly. The root's height is matched the same
+ way while its horizontal travel is preserved, so a travelling walk still travels.
+
+It **self-verifies**: closing a seam moves joints, and on a clip that barely needed it
+the correction can cost more than the seam did. If the result is less continuous than
+the gate allows while the original was fine, the original is returned untouched.
+
+Measured on four real clips: seams of 0.029, 0.171, 0.251 and 0.267 m all close to
+**0.000**, and all four pass the gate as loops.
+
+Seam distance is measured in world space, hips-relative, for the same reason the
+continuity test is. Compared on local rotations, a clip whose joints are 2.9 cm apart
+reports a **178 degree** seam, because the twist flips described above land in that
+comparison too. That reading would have condemned a clip that was already fine.
+
## Running a batch
```bash
diff --git a/docs/ops/gcp-credits.md b/docs/ops/gcp-credits.md
index d184bb896..7d65c1b77 100644
--- a/docs/ops/gcp-credits.md
+++ b/docs/ops/gcp-credits.md
@@ -1656,6 +1656,15 @@ kinematics and judges world-space joint positions. Generated clips score 1.3x to
on world-space continuity against the authored library's median of 1.69 and worst case
of 5.79, so the generated motion is as smooth as the curated library.
+**Loop seams: a second 100% rejection, same root cause.** 41% of the prompt library is
+tagged `loop`, and the sampler produces no seamless loops: a generated walk ends 0.25 m
+per joint from where it started, against 0.000 for the authored library. The gate's
+seam rule also compared LOCAL rotations, so it reported a 178 degree seam on a clip
+whose joints were 2.9 cm apart. Both are fixed: the seam is measured in world space,
+and `closeLoopSeam()` trims to the cycle and blends the tail back onto the opening
+pose, taking four real clips from seams of 0.029 to 0.267 m down to 0.000, all passing
+as loops.
+
**Why the sample is only 5.** `/api/forge-motion` is a public endpoint rate limited per
IP. A 40-clip batch generated 2 clips and then took `429 rate_limited` with a
`retry_after` of 2947 seconds on the remaining 38. Bulk seeding must use the