3D engine that AI agents drive
Chip fab: engineers face their path, swing their arms and keep walking in a looping clip (Part of #927)
Nguyen Xuan Anc7f09a44289b
diff --git a/changes/927.md b/changes/927.mdnew file mode 100644index 00000000..56a76f9b--- /dev/null+++ b/changes/927.md@@ -0,0 +1 @@+- The chip fab engineers on the home page now face the way they walk, swing their arms and keep walking for as long as the world stays on screen, where before they glided sideways and froze after 12 s (#927)diff --git a/docs/hero-loading.md b/docs/hero-loading.mdindex e8d44baf..3151f52d 100644--- a/docs/hero-loading.md+++ b/docs/hero-loading.md@@ -26,6 +26,10 @@ A full world that fails to arrive or to build is asked for again after 4, 10 andThe options (`--near-pixels`, `--far-pixels` and others) are read by `parseArguments` in the script. The geometry the first view lacks lies outside the first 5 s of the flight, so `src/hero-lab/loop/hold.js` slows the flight from 2.5 s while the full world is pending and stops it at 5 s, until the full world is in (or has been given up on). The cost is that on a very slow link the frame is almost still for most of the wait (at 1.6 Mbit/s the first view appears at about 14 s and the swap lands at about 64 s); the alternative is holes at the edges of the picture, and the page before this change showed nothing at all for that time.+## An animated world++The chip fab is the one world with an animation clip: engineers walk, hoist vehicles and pods ride the rails. `src/hero-lab/loop/world.js` plays the clip from the first frame the world draws, with its time modulo the clip length (`loopedClipTime`), so a world that stays on screen longer than the clip, because the next one is still building, keeps moving instead of stopping on the last pose. That only works for a clip whose last pose is its first. `node scripts/hero-clip-loop.mjs <in.glb> <out.glb> --walk-source <UAL1_Standard.glb> --walk-clip Walk_Loop --engineer-speed 0.83` turns the one-way clip into a 24 s patrol that goes out and back with a rounded turn, faces each engineer along its path and plays the Quaternius Walk_Loop (CC0) at the speed that keeps the planted foot still. `tests/hero-chipfab-animation.test.js` checks the loop seam, the facing, the step and the slide on the committed GLB.+## Measuring```shdiff --git a/public/showcase/chipfab/scene.glb b/public/showcase/chipfab/scene.glbindex 38e3101b..5b84cd04 100644Binary files a/public/showcase/chipfab/scene.glb and b/public/showcase/chipfab/scene.glb differdiff --git a/scripts/hero-clip-loop.mjs b/scripts/hero-clip-loop.mjsnew file mode 100644index 00000000..85cb01e0--- /dev/null+++ b/scripts/hero-clip-loop.mjs@@ -0,0 +1,383 @@+// Turns the one-way animation clip of a hero world into a clip that loops without a seam, so a world that stays on screen longer than+// the clip still moves (a clip played once stops on its last pose).+//+// node scripts/hero-clip-loop.mjs <in.glb> <out.glb> [--leg-seconds 12] [--corner-seconds 0.5] [--start-seconds 0.6] [--rate 15] [--engineer-speed 0.9]+// [--walk-source <UAL1_Standard.glb> --walk-clip Walk_Loop] [--cycle-seconds 1.3333]+//+// The input clip is one leg: every mover (an engineer, a hoist vehicle, a pod, a cable) goes from its start to its end in+// --leg-seconds. The output clip lasts twice that. The movers go there and back with a rounded turn, and each engineer turns around+// while it slows. The walk cycle of an engineer's bones always plays forward and repeats every --cycle-seconds, from the input+// clip or from the --walk-clip of a Quaternius Universal Animation Library GLB (CC0) when one is given. The clip starts+// --start-seconds into the first leg, so the first turn comes at the end of the time a world is normally on screen.+// The last key equals the first, so playing the clip with its time modulo its duration has no jump.+// The geometry bytes are copied unchanged; only the animation data is replaced. Nothing is read from the network.+import { readFileSync, writeFileSync } from 'node:fs';+import { createHash } from 'node:crypto';+import { resolve } from 'node:path';+import { pathToFileURL } from 'node:url';++const GLB_MAGIC = 0x46546c67;+const JSON_CHUNK = 0x4e4f534a;+const BINARY_CHUNK = 0x004e4942;+const FLOAT = 5126;+const TYPE_WIDTH = { SCALAR: 1, VEC3: 3, VEC4: 4 };+const WIDTH_TYPE = { 1: 'SCALAR', 3: 'VEC3', 4: 'VEC4' };+const PATH_WIDTH = { translation: 3, rotation: 4, scale: 3 };+const ENGINEER_NAME = /^engineer_\d+$/;+const CONSTANT_TOLERANCE = 1e-6;++export const LOOP_DEFAULTS = { legSeconds: 12, cornerSeconds: 0.5, startSeconds: 0.6, rate: 15, cycleSeconds: 4 / 3, walkClip: 'Walk_Loop' };++export function readGlb(buffer) {+ if (buffer.readUInt32LE(0) !== GLB_MAGIC) throw new Error('Not a GLB file.');+ const jsonLength = buffer.readUInt32LE(12);+ const json = JSON.parse(buffer.subarray(20, 20 + jsonLength).toString('utf8'));+ const binaryStart = 20 + jsonLength;+ if (buffer.readUInt32LE(binaryStart + 4) !== BINARY_CHUNK) throw new Error('The GLB has no binary chunk.');+ const binary = buffer.subarray(binaryStart + 8, binaryStart + 8 + buffer.readUInt32LE(binaryStart));+ return { json, binary };+}++export function writeGlb(json, binary) {+ const jsonBytes = Buffer.from(JSON.stringify(json), 'utf8');+ const jsonPadded = Buffer.concat([jsonBytes, Buffer.alloc((4 - (jsonBytes.length % 4)) % 4, 0x20)]);+ const binaryPadded = Buffer.concat([binary, Buffer.alloc((4 - (binary.length % 4)) % 4)]);+ const header = Buffer.alloc(12);+ header.writeUInt32LE(GLB_MAGIC, 0);+ header.writeUInt32LE(2, 4);+ header.writeUInt32LE(12 + 8 + jsonPadded.length + 8 + binaryPadded.length, 8);+ const jsonHeader = Buffer.alloc(8);+ jsonHeader.writeUInt32LE(jsonPadded.length, 0);+ jsonHeader.writeUInt32LE(JSON_CHUNK, 4);+ const binaryHeader = Buffer.alloc(8);+ binaryHeader.writeUInt32LE(binaryPadded.length, 0);+ binaryHeader.writeUInt32LE(BINARY_CHUNK, 4);+ return Buffer.concat([header, jsonHeader, jsonPadded, binaryHeader, binaryPadded]);+}++function readAccessor(json, binary, index) {+ const accessor = json.accessors[index];+ const view = json.bufferViews[accessor.bufferView];+ if (accessor.componentType !== FLOAT || view.buffer !== 0 || view.extensions) throw new Error(`Accessor ${index} is not plain float data in the first buffer.`);+ const width = TYPE_WIDTH[accessor.type];+ const start = binary.byteOffset + (view.byteOffset ?? 0) + (accessor.byteOffset ?? 0);+ return new Float32Array(binary.buffer.slice(start, start + accessor.count * width * 4));+}++// Every channel of a clip as plain arrays, with the name of the node it moves.+export function readClipChannels(json, binary, clip) {+ return clip.channels.map(channel => {+ const sampler = clip.samplers[channel.sampler];+ const interpolation = sampler.interpolation ?? 'LINEAR';+ if (interpolation === 'CUBICSPLINE') throw new Error('CUBICSPLINE animation samplers cannot be looped.');+ return {+ node: channel.target.node,+ nodeName: json.nodes[channel.target.node].name,+ path: channel.target.path,+ interpolation,+ times: readAccessor(json, binary, sampler.input),+ values: readAccessor(json, binary, sampler.output),+ };+ });+}++function smoothstep(value) {+ const clamped = Math.min(1, Math.max(0, value));+ return clamped * clamped * (3 - 2 * clamped);+}++// The position along one leg, in seconds of the one-way clip, at a time of the looped clip: out and back, with the turn at each end+// rounded (a parabola over cornerSeconds either side) so a mover slows to a stop instead of reversing at full speed.+export function patrolLegTime(phase, legSeconds, cornerSeconds) {+ const period = 2 * legSeconds;+ const wrapped = ((phase % period) + period) % period;+ const distanceToEnd = Math.abs(wrapped - legSeconds);+ if (distanceToEnd < cornerSeconds) return legSeconds - cornerSeconds / 2 - (distanceToEnd * distanceToEnd) / (2 * cornerSeconds);+ const distanceToStart = Math.min(wrapped, period - wrapped);+ if (distanceToStart < cornerSeconds) return (distanceToStart * distanceToStart) / (2 * cornerSeconds) + cornerSeconds / 2;+ return legSeconds - distanceToEnd;+}++// 0 while an engineer faces the way of the first leg, 1 on the way back, eased across the turn at each end.+export function patrolTurnAmount(phase, legSeconds, cornerSeconds) {+ const period = 2 * legSeconds;+ const wrapped = ((phase % period) + period) % period;+ const unwrapped = wrapped < cornerSeconds ? wrapped + period : wrapped;+ const turnAt = center => smoothstep((unwrapped - (center - cornerSeconds)) / (2 * cornerSeconds));+ return unwrapped < legSeconds + cornerSeconds ? turnAt(legSeconds) : 1 - turnAt(period);+}++function findKeyPair(times, time) {+ if (time <= times[0]) return { lower: 0, upper: 0, blend: 0 };+ const last = times.length - 1;+ if (time >= times[last]) return { lower: last, upper: last, blend: 0 };+ let low = 0;+ let high = last;+ while (high - low > 1) {+ const middle = (low + high) >> 1;+ if (times[middle] <= time) low = middle;+ else high = middle;+ }+ return { lower: low, upper: high, blend: (time - times[low]) / (times[high] - times[low]) };+}++export function sampleChannel(channel, time) {+ const width = PATH_WIDTH[channel.path];+ const { lower, upper, blend } = findKeyPair(channel.times, time);+ const from = channel.values.subarray(lower * width, lower * width + width);+ const to = channel.values.subarray(upper * width, upper * width + width);+ const result = new Float32Array(width);+ const sign = channel.path === 'rotation' && from.reduce((sum, value, index) => sum + value * to[index], 0) < 0 ? -1 : 1;+ for (let index = 0; index < width; index++) result[index] = from[index] + (sign * to[index] - from[index]) * blend;+ if (channel.path === 'rotation') {+ const length = Math.hypot(...result) || 1;+ for (let index = 0; index < width; index++) result[index] /= length;+ }+ return result;+}++function multiplyQuaternions(a, b) {+ return new Float32Array([+ a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1],+ a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0],+ a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3],+ a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2],+ ]);+}++function isConstant(channel) {+ // A STEP sampler of two equal keys is how an export writes a pose that never changes.+ const width = PATH_WIDTH[channel.path];+ for (let key = 1; key < channel.times.length; key++) {+ for (let component = 0; component < width; component++) {+ if (Math.abs(channel.values[key * width + component] - channel.values[component]) > CONSTANT_TOLERANCE) return false;+ }+ }+ return true;+}++function descendantsOf(json, rootIndex) {+ const found = new Set();+ const stack = [...(json.nodes[rootIndex].children ?? [])];+ while (stack.length) {+ const index = stack.pop();+ found.add(index);+ stack.push(...(json.nodes[index].children ?? []));+ }+ return found;+}++// The yaw about Y that turns a model facing +Z (the glTF front) toward the way a translation channel goes.+function facingToward(translationChannel) {+ const last = translationChannel.values.length - 3;+ const yaw = Math.atan2(translationChannel.values[last] - translationChannel.values[0], translationChannel.values[last + 2] - translationChannel.values[2]);+ return new Float32Array([0, Math.sin(yaw / 2), 0, Math.cos(yaw / 2)]);+}++function constantChannel(channel, source, legSeconds) {+ const width = PATH_WIDTH[channel.path];+ return { node: channel.node, path: channel.path, constant: true, times: Float32Array.of(0, 2 * legSeconds), keys: [source.values.slice(0, width), source.values.slice(0, width)] };+}++// Quaternion keys stay in one hemisphere so the interpolation takes the short way.+function keepOneHemisphere(keys) {+ for (let key = 1; key < keys.length; key++) {+ const dot = keys[key].reduce((sum, value, index) => sum + value * keys[key - 1][index], 0);+ if (dot < 0) keys[key] = keys[key].map(value => -value);+ }+ return keys;+}++// The channels of the looped clip: { node, path, constant, times, keys: Float32Array[] } sampled at rate keys a second over two legs.+// An engineer exported without a rotation channel gets one that faces it along its path: a GLB with no rotation on the+// engineer node makes it walk sideways. engineerSpeed (metres a second) shortens or lengthens the path so the planted foot does not slide.+export function buildLoopedChannels(json, sourceChannels, options = {}) {+ const { legSeconds, cornerSeconds, startSeconds, rate, cycleSeconds } = { ...LOOP_DEFAULTS, ...options };+ const walkChannels = options.walkChannels ?? null;+ const walkCycleSeconds = options.walkCycleSeconds ?? cycleSeconds;+ const keyCount = Math.round(2 * legSeconds * rate) + 1;+ if (Math.abs(walkCycleSeconds * rate - Math.round(walkCycleSeconds * rate)) > 1e-3) throw new Error(`The walk cycle of ${walkCycleSeconds} s is not a whole number of keys at ${rate} keys a second, so it would jump at the seam.`);+ if (Math.abs((2 * legSeconds) / walkCycleSeconds - Math.round((2 * legSeconds) / walkCycleSeconds)) > 1e-3) throw new Error('The looped clip must hold a whole number of walk cycles.');+ const skeletonNodes = new Set();+ const engineerNodes = new Set();+ json.nodes.forEach((node, index) => {+ if (!ENGINEER_NAME.test(node.name ?? '')) return;+ engineerNodes.add(index);+ for (const descendant of descendantsOf(json, index)) skeletonNodes.add(descendant);+ });+ const walkByName = new Map((walkChannels ?? []).map(channel => [`${channel.nodeName}/${channel.path}`, channel]));+ const times = Float32Array.from({ length: keyCount }, (_, key) => key / rate);+ const channelsByNode = path => new Map(sourceChannels.filter(channel => channel.path === path).map(channel => [channel.node, channel]));+ const translations = channelsByNode('translation');+ const rotations = channelsByNode('rotation');++ const patrolChannel = channel => {+ const isEngineer = engineerNodes.has(channel.node);+ const travel = translations.get(channel.node);+ const originalSpeed = isEngineer && travel ? Math.hypot(travel.values.at(-3) - travel.values[0], travel.values.at(-1) - travel.values[2]) / legSeconds : 0;+ const speedScale = isEngineer && options.engineerSpeed && originalSpeed > 0 ? options.engineerSpeed / originalSpeed : 1;+ const keys = Array.from(times, time => {+ const sampled = sampleChannel(channel, patrolLegTime(time + startSeconds, legSeconds, cornerSeconds));+ if (channel.path !== 'translation' || speedScale === 1) return sampled;+ return sampled.map((value, axis) => channel.values[axis] + (value - channel.values[axis]) * speedScale);+ });+ return { node: channel.node, path: channel.path, constant: false, times, keys };+ };++ const gaitChannel = (channel, source) => ({ node: channel.node, path: channel.path, constant: false, times, keys: keepOneHemisphere(Array.from(times, time => sampleChannel(source, time % walkCycleSeconds))) });++ const looped = sourceChannels.map(channel => {+ const gaitSource = skeletonNodes.has(channel.node) ? (walkByName.get(`${channel.nodeName}/${channel.path}`) ?? channel) : null;+ const source = gaitSource ?? channel;+ if (isConstant(source)) return constantChannel(channel, source, legSeconds);+ if (source.interpolation === 'STEP') throw new Error(`The channel ${channel.nodeName}/${channel.path} changes but uses STEP interpolation, which would be sampled as linear.`);+ return gaitSource ? gaitChannel(channel, gaitSource) : patrolChannel(channel);+ });++ for (const node of engineerNodes) {+ const existing = rotations.get(node);+ const travel = translations.get(node);+ if (existing || !travel) continue;+ const facing = facingToward(travel);+ const keys = Array.from(times, time => {+ const halfTurn = (Math.PI * patrolTurnAmount(time + startSeconds, legSeconds, cornerSeconds)) / 2;+ return multiplyQuaternions(new Float32Array([0, Math.sin(halfTurn), 0, Math.cos(halfTurn)]), facing);+ });+ looped.push({ node, path: 'rotation', constant: false, times, keys: keepOneHemisphere(keys) });+ }+ return looped;+}++function alignedEnd(length) {+ return length + ((4 - (length % 4)) % 4);+}++// The byte ranges of the first buffer that hold geometry, in order: a plain view, or the compressed range a meshopt view points at.+function bufferRanges(json, skippedViews) {+ const ranges = [];+ json.bufferViews.forEach((view, index) => {+ if (skippedViews.has(index)) return;+ if (view.buffer === 0) ranges.push({ holder: view, offset: view.byteOffset ?? 0, length: view.byteLength });+ const compressed = view.extensions?.EXT_meshopt_compression;+ if (compressed?.buffer === 0) ranges.push({ holder: compressed, offset: compressed.byteOffset ?? 0, length: compressed.byteLength });+ });+ return ranges;+}++// Removes the animation accessors, their buffer views and their bytes, and moves whatever came after those bytes (an image) up.+// The animation accessors must be the tail of the accessor list and their views one contiguous run that nothing else shares;+// anything else is refused instead of guessed. Returns the binary without the animation data.+function removeAnimationData(json, binary) {+ const oldAccessors = new Set(json.animations[0].samplers.flatMap(sampler => [sampler.input, sampler.output]));+ const firstAccessor = Math.min(...oldAccessors);+ if (Math.max(...oldAccessors) !== json.accessors.length - 1 || json.accessors.length - firstAccessor !== oldAccessors.size) throw new Error('The animation accessors are not the tail of the accessor list.');+ const oldViews = new Set(json.accessors.slice(firstAccessor).map(accessor => accessor.bufferView));+ const firstView = Math.min(...oldViews);+ const viewRunLength = oldViews.size;+ if (Math.max(...oldViews) !== firstView + viewRunLength - 1) throw new Error('The animation buffer views are not one contiguous run.');+ const sharesView = view => view !== undefined && oldViews.has(view);+ if (json.accessors.slice(0, firstAccessor).some(accessor => sharesView(accessor.bufferView)) || (json.images ?? []).some(image => sharesView(image.bufferView))) throw new Error('Something else shares an animation buffer view.');+ const removedStart = Math.min(...[...oldViews].map(index => json.bufferViews[index].byteOffset));+ const removedEnd = Math.max(...[...oldViews].map(index => json.bufferViews[index].byteOffset + json.bufferViews[index].byteLength));+ const others = bufferRanges(json, oldViews);+ if (others.some(range => range.offset < removedEnd && range.offset + range.length > removedStart)) throw new Error('Other data overlaps the animation bytes.');+ const removedLength = removedEnd - removedStart;+ for (const range of others) if (range.offset >= removedEnd) range.holder.byteOffset = range.offset - removedLength;+ const renumber = index => (index === undefined || index < firstView ? index : index - viewRunLength);+ json.accessors.length = firstAccessor;+ for (const accessor of json.accessors) accessor.bufferView = renumber(accessor.bufferView);+ for (const image of json.images ?? []) image.bufferView = renumber(image.bufferView);+ json.bufferViews.splice(firstView, viewRunLength);+ return Buffer.concat([binary.subarray(0, removedStart), binary.subarray(removedEnd)]);+}++export function writeLoopedClip(json, binary, loopedChannels, clipName) {+ const oldClip = json.animations[0];+ const keptBinary = removeAnimationData(json, binary);+ const chunks = [keptBinary];+ let length = keptBinary.length;+ const addView = bytes => {+ const padding = alignedEnd(length) - length;+ if (padding) chunks.push(Buffer.alloc(padding));+ length += padding;+ json.bufferViews.push({ buffer: 0, byteOffset: length, byteLength: bytes.length });+ chunks.push(bytes);+ length += bytes.length;+ return json.bufferViews.length - 1;+ };+ const addAccessor = (array, type, extra = {}) => {+ const bufferView = addView(Buffer.from(array.buffer, array.byteOffset, array.byteLength));+ json.accessors.push({ bufferView, componentType: FLOAT, count: array.length / TYPE_WIDTH[type], type, ...extra });+ return json.accessors.length - 1;+ };++ const sharedAccessors = new Map();+ const shared = (key, create) => {+ if (!sharedAccessors.has(key)) sharedAccessors.set(key, create());+ return sharedAccessors.get(key);+ };+ const samplers = [];+ const samplerIndexByPair = new Map();+ const channels = loopedChannels.map(looped => {+ const timeKey = `t:${looped.times.length}:${looped.times.at(-1)}`;+ const input = shared(timeKey, () => addAccessor(looped.times, 'SCALAR', { min: [looped.times[0]], max: [looped.times.at(-1)] }));+ const flat = Float32Array.from(looped.keys.flatMap(key => Array.from(key)));+ const hash = createHash('sha1').update(Buffer.from(flat.buffer)).digest('hex');+ const output = shared(`v:${hash}`, () => addAccessor(flat, WIDTH_TYPE[PATH_WIDTH[looped.path]]));+ const pair = `${input}/${output}`;+ if (!samplerIndexByPair.has(pair)) {+ samplerIndexByPair.set(pair, samplers.length);+ samplers.push({ input, interpolation: 'LINEAR', output });+ }+ return { sampler: samplerIndexByPair.get(pair), target: { node: looped.node, path: looped.path } };+ });+ json.animations = [{ name: clipName ?? oldClip.name, channels, samplers }];+ const total = Buffer.concat(chunks);+ json.buffers[0].byteLength = total.length;+ return total;+}++export function loopHeroClip(glbBytes, options = {}) {+ const { json, binary } = readGlb(glbBytes);+ if (json.animations?.length !== 1) throw new Error('Expected exactly one merged animation clip.');+ const sourceChannels = readClipChannels(json, binary, json.animations[0]);+ const looped = buildLoopedChannels(json, sourceChannels, options);+ const newBinary = writeLoopedClip(json, binary, looped, json.animations[0].name);+ return writeGlb(json, newBinary);+}++export function readWalkClip(walkGlbBytes, clipName) {+ const { json, binary } = readGlb(walkGlbBytes);+ const clip = json.animations.find(entry => entry.name === clipName);+ if (!clip) throw new Error(`The walk source has no clip named ${clipName}: ${json.animations.map(entry => entry.name).join(', ')}.`);+ const channels = readClipChannels(json, binary, clip);+ return { channels, duration: Math.max(...channels.map(channel => channel.times.at(-1))) };+}++function parseOptions(argv) {+ const positional = [];+ const options = {};+ for (let index = 0; index < argv.length; index++) {+ if (!argv[index].startsWith('--')) { positional.push(argv[index]); continue; }+ const key = argv[index].slice(2).replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());+ options[key] = argv[++index];+ }+ return { positional, options };+}++function main() {+ const { positional, options } = parseOptions(process.argv.slice(2));+ if (positional.length !== 2) throw new Error('Pass <in.glb> and <out.glb>.');+ const numeric = ['legSeconds', 'cornerSeconds', 'startSeconds', 'rate', 'cycleSeconds', 'engineerSpeed'];+ const loopOptions = Object.fromEntries(numeric.filter(key => options[key] !== undefined).map(key => [key, Number(options[key])]));+ if (options.walkSource) {+ const walk = readWalkClip(readFileSync(options.walkSource), options.walkClip ?? LOOP_DEFAULTS.walkClip);+ loopOptions.walkChannels = walk.channels;+ loopOptions.walkCycleSeconds = walk.duration;+ }+ const output = loopHeroClip(readFileSync(positional[0]), loopOptions);+ writeFileSync(positional[1], output);+ console.log(`looped clip written: ${output.length} bytes`);+}++if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) main();diff --git a/src/hero-lab/loop/clip-time.js b/src/hero-lab/loop/clip-time.jsnew file mode 100644index 00000000..01fbf5b7--- /dev/null+++ b/src/hero-lab/loop/clip-time.js@@ -0,0 +1,7 @@+// The time inside a looping animation clip for a world that has been drawn for `seconds`. A clip that is only clamped stops on+// its last pose once the world stays on screen longer than the clip (a next world still building, a link that is slow), and every+// engineer and vehicle freezes. A clip made to loop (its last pose equals its first) is played with its time modulo its length.+export function loopedClipTime(seconds, clipDuration) {+ if (!(clipDuration > 0) || !Number.isFinite(seconds)) return 0;+ return seconds % clipDuration;+}diff --git a/src/hero-lab/loop/scenes.js b/src/hero-lab/loop/scenes.jsindex 5283aa4c..7ba72d0f 100644--- a/src/hero-lab/loop/scenes.js+++ b/src/hero-lab/loop/scenes.js@@ -45,7 +45,7 @@ export const SCENES = [id: 'chipfab',name: 'Chip fab',description: '/showcase/chipfab/scene.json',- seconds: 11, // the merged clip is 12 s: 11 s on screen plus the fade+ seconds: 11, // the merged clip is a 24 s patrol that loops, so a world held longer than this keeps movingscrim: 0.6,near: 0.3,far: 400,diff --git a/src/hero-lab/loop/world.js b/src/hero-lab/loop/world.jsindex 5f4d94b8..b14e9ffd 100644--- a/src/hero-lab/loop/world.js+++ b/src/hero-lab/loop/world.js@@ -12,6 +12,7 @@ import { applyWaterReflection, attachWaterReflection } from '../../water-reflectimport { readPartRanks } from '../../showcase-download.js';import { prepareEffects } from './effects.js';import { createSlicer, yieldToPage } from '../../cooperative.js';+import { loopedClipTime } from './clip-time.js';// The water mirror is off in the loop: once the camera moves between two draws the port world drew only its sky (the same happens// on hero-b.html?scene=port when the camera is set by hand; with the mirror off every pose draws). Turn it on again when that is fixed.@@ -282,10 +283,10 @@ export async function buildWorld(download, canvas, overrides = {}) {// While a swap replaces the parts the canvas keeps its last frame: a half-built world is never drawn.if (disposed || drawsHeld) return false;lastDraw = { camera: { eye: [...camera.eye], target: [...camera.target], fov: camera.fov }, seconds };- // A GLB with an animation clip (vehicles on rails, people walking) plays from the world's first drawn frame.+ // A GLB with an animation clip (vehicles on rails, people walking) plays from the world's first drawn frame and loops.if (animated) {animationOrigin ??= seconds;- const clipSeconds = seconds - animationOrigin;+ const clipSeconds = loopedClipTime(seconds - animationOrigin, animated.animations[0].duration);// The shadow map follows the clip 8 times a second, not on every frame.const shadowStep = Math.floor(clipSeconds * 8);renderer.updateParts(animated.applyAnimation(clipSeconds, 0), { shadows: shadowStep !== animationShadowStep });diff --git a/tests/hero-chipfab-animation.test.js b/tests/hero-chipfab-animation.test.jsnew file mode 100644index 00000000..61354745--- /dev/null+++ b/tests/hero-chipfab-animation.test.js@@ -0,0 +1,184 @@+import assert from 'node:assert/strict';+import { readFileSync } from 'node:fs';+import test from 'node:test';+import { parseGltf } from '../src/gltf.js';+import { loopedClipTime } from '../src/hero-lab/loop/clip-time.js';+import { patrolLegTime, patrolTurnAmount, readClipChannels, readGlb, sampleChannel } from '../scripts/hero-clip-loop.mjs';++const CHIPFAB_GLB = new URL('../public/showcase/chipfab/scene.glb', import.meta.url);+const LEG_SECONDS = 12;+const CORNER_SECONDS = 0.5;+const FRAME_SECONDS = 1 / 30;+const ENGINEER_COUNT = 4;+const SKINS_PER_ENGINEER = 2;+const LIMITS = { maxBytes: 64 * 1024 * 1024, maxVertices: 4_000_000, maxParts: 20_000, maxTexturePixels: 512 * 1024 * 1024, maxTextureImagePixels: 100_000_000 };++async function loadChipfab() {+ // Node has no image decoder, so the test stubs createImageBitmap and only the geometry and the clip are real.+ globalThis.createImageBitmap ??= async () => ({ width: 4, height: 4, close() {} });+ const buffer = readFileSync(CHIPFAB_GLB);+ return parseGltf(buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength), LIMITS);+}++function maximumDifference(first, second) {+ let largest = 0;+ for (let index = 0; index < first.length; index++) largest = Math.max(largest, Math.abs(first[index] - second[index]));+ return largest;+}++function engineerSkins(asset) {+ return Array.from({ length: ENGINEER_COUNT }, (_, engineer) => asset.skins[engineer * SKINS_PER_ENGINEER]);+}++function jointPosition(skin, jointName) {+ // The importer names the joints of the second engineer onward with a numeric suffix (foot_l_1).+ const index = skin.joints.findIndex(joint => joint.name.replace(/_\d+$/, '') === jointName);+ assert.ok(index >= 0, `the skin has a ${jointName} joint`);+ return Array.from(skin.jointWorldMatrices.slice(index * 16 + 12, index * 16 + 15));+}++test('loopedClipTime plays a clip again from its start instead of stopping on its last pose', () => {+ assert.equal(loopedClipTime(0, 24), 0);+ assert.equal(loopedClipTime(5.5, 24), 5.5);+ assert.ok(Math.abs(loopedClipTime(24 + 3, 24) - 3) < 1e-9);+ assert.ok(Math.abs(loopedClipTime(24 * 7 + 11, 24) - 11) < 1e-9);+ assert.ok(loopedClipTime(1e6, 24) < 24);+ assert.equal(loopedClipTime(10, 0), 0);+ assert.equal(loopedClipTime(Number.NaN, 24), 0);+});++test('a patrol goes out and back at walking pace, slows to a stop at each end and repeats without a jump', () => {+ const period = 2 * LEG_SECONDS;+ let previous = patrolLegTime(0, LEG_SECONDS, CORNER_SECONDS);+ for (let step = 1; step <= period * 60 * 3; step++) {+ const phase = step / 60;+ const position = patrolLegTime(phase, LEG_SECONDS, CORNER_SECONDS);+ assert.ok(position >= 0 && position <= LEG_SECONDS, `position ${position} stays on the leg`);+ assert.ok(Math.abs(position - previous) <= 1 / 60 + 1e-9, `position never moves faster than the one-way clip at ${phase}`);+ previous = position;+ }+ assert.ok(Math.abs(patrolLegTime(3.3, LEG_SECONDS, CORNER_SECONDS) - patrolLegTime(3.3 + period, LEG_SECONDS, CORNER_SECONDS)) < 1e-9);+ assert.ok(Math.abs(patrolLegTime(LEG_SECONDS + 0.0001, LEG_SECONDS, CORNER_SECONDS) - patrolLegTime(LEG_SECONDS - 0.0001, LEG_SECONDS, CORNER_SECONDS)) < 1e-6, 'it stops at the far end');+ assert.ok(patrolLegTime(LEG_SECONDS / 2, LEG_SECONDS, CORNER_SECONDS) < patrolLegTime(LEG_SECONDS / 2 + 1, LEG_SECONDS, CORNER_SECONDS), 'outbound goes forward');+ assert.ok(patrolLegTime(LEG_SECONDS + 3, LEG_SECONDS, CORNER_SECONDS) > patrolLegTime(LEG_SECONDS + 4, LEG_SECONDS, CORNER_SECONDS), 'the way back goes backward');+});++test('a patrol turns an engineer around while it is slow, and not on the legs', () => {+ assert.equal(patrolTurnAmount(5, LEG_SECONDS, CORNER_SECONDS), 0);+ assert.equal(patrolTurnAmount(LEG_SECONDS + 5, LEG_SECONDS, CORNER_SECONDS), 1);+ assert.ok(Math.abs(patrolTurnAmount(LEG_SECONDS, LEG_SECONDS, CORNER_SECONDS) - 0.5) < 1e-9);+ assert.ok(Math.abs(patrolTurnAmount(0, LEG_SECONDS, CORNER_SECONDS) - 0.5) < 1e-9);+ let previous = patrolTurnAmount(0, LEG_SECONDS, CORNER_SECONDS);+ for (let step = 1; step <= 2 * LEG_SECONDS * 60 * 2; step++) {+ const amount = patrolTurnAmount(step / 60, LEG_SECONDS, CORNER_SECONDS);+ assert.ok(Math.abs(amount - previous) < 0.05, `the turn is smooth at ${step / 60}`);+ previous = amount;+ }+});++test('the chip fab clip is a patrol long enough to loop and its last pose is its first', async () => {+ const asset = await loadChipfab();+ assert.equal(asset.animations.length, 1, 'one merged clip moves the whole scene');+ const duration = asset.animations[0].duration;+ assert.ok(duration >= 2 * LEG_SECONDS - 1e-6, `the clip lasts ${duration} s, two legs of ${LEG_SECONDS} s`);+ asset.applyAnimation(0, 0);+ const firstPose = asset.parts.map(part => Float32Array.from(part.matrix));+ const firstPalettes = asset.skins.map(skin => Float32Array.from(skin.jointMatrices));+ asset.applyAnimation(duration, 0);+ asset.parts.forEach((part, index) => assert.ok(maximumDifference(part.matrix, firstPose[index]) < 1e-3, `${part.name} is back where it started`));+ asset.skins.forEach((skin, index) => assert.ok(maximumDifference(skin.jointMatrices, firstPalettes[index]) < 1e-3, 'every skeleton is back in its first pose'));+});++test('nothing in the chip fab jumps from one frame to the next, including across the loop seam', async () => {+ const asset = await loadChipfab();+ const duration = asset.animations[0].duration;+ const framesPerSecond = 30;+ let previous = null;+ let largestStep = 0;+ for (let frame = 0; frame <= duration * framesPerSecond * 2; frame++) {+ asset.applyAnimation(loopedClipTime(frame / framesPerSecond, duration), 0);+ const positions = asset.parts.map(part => [part.matrix[12], part.matrix[13], part.matrix[14]]);+ if (previous) positions.forEach((position, index) => { largestStep = Math.max(largestStep, Math.hypot(position[0] - previous[index][0], position[1] - previous[index][1], position[2] - previous[index][2])); });+ previous = positions;+ }+ assert.ok(largestStep < 0.25, `the fastest part moves ${largestStep.toFixed(3)} m in one frame`);+});++test('every engineer keeps walking through the first, second and third pass of the clip', async () => {+ const asset = await loadChipfab();+ const duration = asset.animations[0].duration;+ const skins = engineerSkins(asset);+ let slowestChange = Infinity;+ for (let time = 0; time < duration * 3; time += 0.37) {+ asset.applyAnimation(loopedClipTime(time, duration), 0);+ const before = skins.map(skin => Float32Array.from(skin.jointMatrices));+ asset.applyAnimation(loopedClipTime(time + 0.1, duration), 0);+ skins.forEach((skin, index) => { slowestChange = Math.min(slowestChange, maximumDifference(skin.jointMatrices, before[index])); });+ }+ assert.ok(slowestChange > 0.005, `an engineer's joints moved only ${slowestChange} in 0.1 s at some time`);+});++test('an engineer faces the way it walks, on the way out and on the way back', async () => {+ const { json, binary } = readGlb(readFileSync(CHIPFAB_GLB));+ const channels = readClipChannels(json, binary, json.animations[0]);+ const duration = Math.max(...channels.map(channel => channel.times.at(-1)));+ for (let engineer = 0; engineer < ENGINEER_COUNT; engineer++) {+ const name = `engineer_${engineer}`;+ const translation = channels.find(channel => channel.nodeName === name && channel.path === 'translation');+ const rotation = channels.find(channel => channel.nodeName === name && channel.path === 'rotation');+ assert.ok(rotation, `${name} has a rotation, so it does not walk sideways`);+ let checked = 0;+ for (let time = 0; time < duration; time += 0.25) {+ const from = sampleChannel(translation, time);+ const to = sampleChannel(translation, time + 0.1);+ const speed = Math.hypot(to[0] - from[0], to[2] - from[2]) / 0.1;+ if (speed < 0.5) continue;+ const [x, y, z, w] = sampleChannel(rotation, time);+ // The model faces +Z; this is +Z turned by the rotation.+ const forward = [2 * (x * z + w * y), 2 * (y * z - w * x), 1 - 2 * (x * x + y * y)];+ const alignment = (forward[0] * (to[0] - from[0]) + forward[2] * (to[2] - from[2])) / (speed * 0.1);+ assert.ok(alignment > 0.98, `${name} faces away from its path at ${time} s (alignment ${alignment.toFixed(2)})`);+ checked++;+ }+ assert.ok(checked > 40, `${name} was checked on both legs`);+ }+});++test('a planted foot of an engineer does not skate across the floor', async () => {+ const asset = await loadChipfab();+ const skins = engineerSkins(asset);+ for (const [engineer, skin] of skins.entries()) {+ let slideSum = 0;+ let slideCount = 0;+ let previous = null;+ for (let time = 1; time <= 10; time += FRAME_SECONDS) {+ asset.applyAnimation(time, 0);+ const feet = { left: jointPosition(skin, 'foot_l'), right: jointPosition(skin, 'foot_r') };+ if (previous) {+ for (const side of ['left', 'right']) {+ if (feet[side][1] > 0.12 || previous[side][1] > 0.12) continue;+ slideSum += Math.hypot(feet[side][0] - previous[side][0], feet[side][2] - previous[side][2]) / FRAME_SECONDS;+ slideCount++;+ }+ }+ previous = feet;+ }+ assert.ok(slideCount > 100, `engineer ${engineer} has frames with a planted foot`);+ assert.ok(slideSum / slideCount < 0.3, `engineer ${engineer} planted foot slides at ${(slideSum / slideCount).toFixed(2)} m/s`);+ }+});++test('an engineer swings its arms while it walks', async () => {+ const asset = await loadChipfab();+ const skin = asset.skins[0];+ const wristHeights = [];+ const hip = [];+ for (let time = 1; time <= 2.4; time += FRAME_SECONDS) {+ asset.applyAnimation(time, 0);+ const wrist = jointPosition(skin, 'hand_l');+ const pelvis = jointPosition(skin, 'pelvis');+ wristHeights.push(Math.hypot(wrist[0] - pelvis[0], wrist[2] - pelvis[2]));+ hip.push(pelvis[1]);+ }+ assert.ok(Math.max(...wristHeights) - Math.min(...wristHeights) > 0.1, 'the hand moves back and forth beside the body');+});