Guide3 min read0 sections

Animation clips and rigid model poses

docs/ANIMATION_CLIPS.mdSource updated 2026-10-24
Markdown
On this page 0 sections

The development branch adds a GLB TRS clip importer and a stateless presentation-time pose evaluator. This work is exercised in the Observatory and is not integrated into the playable world. It is groundwork for milestone 7's skeletal-animation requirement, not completion of that requirement.

glb-animated.1 / artifact format 5 carries named clips, node/property channels, key times, values and rest TRS for targeted nodes. Build identities advance to asset-job.5 / glb-compiler.5. Nonanimated model identities remain unchanged. The importer currently accepts FLOAT translation, rotation and scale outputs with STEP, LINEAR and CUBICSPLINE interpolation. Animated targets must use TRS and belong to the selected scene; morph weights still fail explicitly. Skins are handled by the subsequent skeletal profile. Clip names may repeat; index selects a clip unambiguously.

The glTF animation specification supplies the time and interpolation conventions. Inputs are nonnegative and strictly increasing, channels clamp before/after their key range, and exact key times use their authored values. Linear quaternion sampling takes the shortest spherical path; cubic quaternion results normalize after Hermite interpolation without changing key signs. Cubic tangents scale by segment duration. Limits are 32 clips, 768 total channels, 65,536 total keys, 262,144 total output numbers and 3,600 seconds. Import bounds expansion before copying channel data.

ModelAnimationPlayer.create independently validates and owns a model. sample(index, seconds, loop) starts from rest state on every call, evaluates the hierarchy in parent order, applies unit scale and returns owned ModelObject placements. It does not advance simulation or own a wall clock. Reflected prepared meshes retain their positive presentation matrices. Singular, nonfinite, out-of-budget or differently reflected sampled poses throw before returning a partial result; callers must publish only a complete pose. There is no promise yet that every admitted curve has a renderable pose at every timestamp. Collision remains at the authored rest geometry.

The eight focused tests cover endpoints, step transitions, shortest-path rotations, cubic duration scaling, quaternion normalization/degeneracy, malformed timelines, ownership, duplicate targets, isolated compiler identity, parent/child motion, looping, unit scale, reflection and independently rehashed corruption. All 256 headless tests pass, including reproducible source/reference artifacts and a packaged compiler importing the animated fixture outside the checkout. The original blanket rejection of all animations has been replaced by malformed-animation coverage; the subsequent skeletal stage replaces the earlier blanket skin rejection with validation of its supported subset.

The Observatory samples an animated parent/child model at three times and a reflected model at its midpoint, comparing all color channels against separately authored static GLB references. It also checks looping, current-pose culling, rejection without changing the accepted frame, twelve samples without changing GPU ownership, actual device destruction/reconstruction at the same clip time and disposal. The full 26-scenario browser run passes with zero maximum reference error in the animation comparisons. This original rigid-pose acceptance uses existing model presentation; the subsequent skeletal stage adds joint palettes and skinning shaders.

The subsequent skeletal stage adds joints, weights, inverse binds, bounded skinning resources and animated bounds. Next integration work includes animation state in actor presentation and saved/recovered state. Blend trees, attachments, playable character art and the broader performance/device gates remain open. No roadmap milestone is closed by this increment.

The authored-model worker probe now reports its last operation if its fixed twenty-second deadline expires. Stage messages do not renew the deadline, resolve a request or retain ownership after cancellation. Two timer-controlled regressions cover these invariants. This is diagnostic instrumentation for the prior CI failures, not a claim that their cause is fixed.

Acceptance evidence records the full browser run before diagnostic instrumentation and the three affected scenarios passing after it. The source/artifact fixtures can be regenerated with node --import tsx tools/cli/animation-model-fixture.ts.

End of Animation clips