@pose_flow/babylon 0.0.0-stage → 0.2.0

package/dist/offline/src/babylon.js

@@ -0,0 +1,201 @@
+import { Animation, AnimationGroup, Matrix, Quaternion, Vector3 } from '@babylonjs/core';
+import { compileSchema, LOCOMOTION_SCHEMA } from './core/schema.js';
+import { parseRootOrientation } from './core/profile.js';
+/** Constant authoring orientation belongs to the pose; varying root heading belongs to gameplay. */
+function constantRootRotation(animation) {
+    const keys = animation.getKeys();
+    if (!keys.length || keys.some(k => k.inTangent !== undefined || k.outTangent !== undefined))
+        return undefined;
+    const rotation = (value) => animation.targetProperty === 'rotationQuaternion' && value instanceof Quaternion ? value.clone()
+        : animation.targetProperty === 'rotation' && value instanceof Vector3 ? Quaternion.FromEulerVector(value) : undefined;
+    const first = rotation(keys[0].value);
+    if (!first || !first.asArray().every(Number.isFinite) || first.length() < 1e-8)
+        return undefined;
+    first.normalize();
+    for (const key of keys) {
+        const q = rotation(key.value);
+        if (!q || !q.asArray().every(Number.isFinite) || q.length() < 1e-8 || Math.abs(Quaternion.Dot(first, q.normalize())) < 1 - 1e-8)
+            return undefined;
+    }
+    return first;
+}
+/** Clone onto a target rig. Two playback slots allow crossfade between times of the same clip. */
+export class BabylonMotionPlayer {
+    scene;
+    clips;
+    sources;
+    nodes;
+    fadeSeconds;
+    rootName;
+    tracks = [];
+    active;
+    disposed = false;
+    strippedRoot;
+    rootRestRotation;
+    constructor(scene, clips, sources, nodes, fadeSeconds = 0.15, rootName = 'root') {
+        this.scene = scene;
+        this.clips = clips;
+        this.sources = sources;
+        this.nodes = nodes;
+        this.fadeSeconds = fadeSeconds;
+        this.rootName = rootName;
+        if (!Number.isFinite(fadeSeconds) || fadeSeconds < 0)
+            throw new Error('Invalid crossfade duration');
+        for (const clip of clips) {
+            const source = sources.get(clip.id);
+            if (!source)
+                throw new Error(`Missing animation source: ${clip.id}`);
+            const fps = source.targetedAnimations[0]?.animation.framePerSecond, start = clip.sourceStart ?? 0;
+            if (!Number.isFinite(start) || start < 0 || !Number.isFinite(clip.duration) || clip.duration <= 0 || !fps
+                || start + clip.duration > (source.to - source.from) / fps + 1e-5)
+                throw new Error(`Invalid source range: ${clip.id}`);
+        }
+        this.strippedRoot = [...nodes.values()].find(n => n.name === rootName);
+        if (this.strippedRoot) {
+            this.strippedRoot.rotationQuaternion ??= Quaternion.FromEulerVector(this.strippedRoot.rotation);
+            this.rootRestRotation = this.strippedRoot.rotationQuaternion.clone();
+        }
+        for (const clip of clips)
+            if (clip.rootOrientation !== undefined) {
+                parseRootOrientation(clip.rootOrientation);
+                if (!this.strippedRoot)
+                    throw new Error('rootOrientation requires a mapped stripped root');
+            }
+    }
+    create(clip, time) {
+        const source = this.sources.get(this.clips[clip].id);
+        const group = new AnimationGroup(`mm-${this.clips[clip].id}-${this.tracks.length}`, this.scene);
+        let rootRotation = this.rootRestRotation?.clone();
+        for (const targeted of source.targetedAnimations) {
+            const node = this.nodes.get(targeted.target.name);
+            if (!node)
+                continue;
+            const property = targeted.animation.targetProperty;
+            if (node === this.strippedRoot) {
+                if (property === 'position' || property.startsWith('position.'))
+                    continue;
+                if (property === 'rotationQuaternion' || property === 'rotation' || property.startsWith('rotation.') || property.startsWith('rotationQuaternion.')) {
+                    rootRotation = constantRootRotation(targeted.animation) ?? rootRotation;
+                    continue;
+                }
+            }
+            group.addTargetedAnimation(targeted.animation, node);
+        }
+        if (!group.targetedAnimations.length) {
+            group.dispose();
+            throw new Error('No matching rig animation tracks');
+        }
+        const correction = this.clips[clip].rootOrientation;
+        if (correction)
+            rootRotation = Quaternion.FromArray([...correction]).normalize();
+        if (this.strippedRoot && rootRotation) {
+            // An explicit constant binding also restores the baseline after a clip with
+            // another orientation, and participates in the same weighted crossfade.
+            const rotation = new Animation('mm-root-pose', 'rotationQuaternion', source.targetedAnimations[0].animation.framePerSecond, Animation.ANIMATIONTYPE_QUATERNION);
+            rotation.setKeys([{ frame: source.from, value: rootRotation }, { frame: source.to, value: rootRotation.clone() }]);
+            group.addTargetedAnimation(rotation, this.strippedRoot);
+        }
+        // Paused groups still participate in Babylon's late weighted bindings when
+        // goToFrame(frame, true) is called. Speed zero alone resets on scene.render().
+        group.start(true, 0);
+        group.pause();
+        group.setWeightForAllAnimatables(0);
+        const track = { group, clip, time, weight: this.tracks.length === 0 ? 1 : 0 };
+        this.tracks.push(track);
+        return track;
+    }
+    update(state, dt) {
+        if (this.disposed)
+            throw new Error('Player already disposed');
+        if (!Number.isFinite(dt) || dt < 0)
+            throw new Error('Invalid player delta');
+        if (state.clip < 0) {
+            this.clear();
+            return;
+        }
+        if (!this.clips[state.clip])
+            throw new Error('Unknown playback clip');
+        if (!this.active || state.switched || this.active.clip !== state.clip) {
+            // Bound simultaneous slots during rapid replanning; residual poses retain relative weights.
+            if (this.tracks.length >= 4) {
+                const oldest = this.tracks.shift();
+                oldest.group.dispose();
+            }
+            this.active = this.create(state.clip, state.time);
+        }
+        this.active.time = state.time;
+        const alpha = this.fadeSeconds === 0 ? 1 : 1 - Math.exp(-dt * 4 / this.fadeSeconds);
+        for (const track of this.tracks) {
+            if (track !== this.active)
+                track.time += dt;
+            track.weight += ((track === this.active ? 1 : 0) - track.weight) * alpha;
+        }
+        // First pose must be fully defined even at dt=0.
+        const total = this.tracks.reduce((sum, t) => sum + t.weight, 0);
+        for (const track of this.tracks) {
+            const descriptor = this.clips[track.clip], group = track.group;
+            const time = descriptor.looping ? ((track.time % descriptor.duration) + descriptor.duration) % descriptor.duration : Math.max(0, Math.min(track.time, descriptor.duration));
+            group.setWeightForAllAnimatables(total > 0 ? track.weight / total : (track === this.active ? 1 : 0));
+            const source = this.sources.get(descriptor.id), fps = source.targetedAnimations[0].animation.framePerSecond;
+            group.goToFrame(source.from + ((descriptor.sourceStart ?? 0) + time) * fps, true);
+        }
+        this.tracks = this.tracks.filter(track => {
+            if (track !== this.active && track.weight < 0.001) {
+                track.group.dispose();
+                return false;
+            }
+            return true;
+        });
+    }
+    clear() { for (const t of this.tracks)
+        t.group.dispose(); this.tracks = []; this.active = undefined; }
+    dispose() { this.clear(); this.disposed = true; }
+}
+/** Sample AFTER scene animation evaluation. Semantic roles are defined by the schema. */
+export class BabylonSchemaPoseReader {
+    root;
+    previous;
+    nodes;
+    constructor(root, bones, schema) {
+        this.root = root;
+        const roles = compileSchema(schema).bones;
+        for (const role of roles)
+            if (!bones.has(role))
+                throw new Error('Missing schema bone node: ' + role);
+        this.nodes = new Map(roles.map(role => [role, bones.get(role)]));
+    }
+    reset() { this.previous = undefined; }
+    read(dt) {
+        if (!Number.isFinite(dt) || dt < 0)
+            throw new Error('Invalid pose delta');
+        this.root.computeWorldMatrix(true);
+        const root = this.root.getAbsolutePosition().clone(), positions = new Map();
+        for (const [role, node] of this.nodes) {
+            node.computeWorldMatrix(true);
+            positions.set(role, node.getAbsolutePosition().clone());
+        }
+        const inverse = Matrix.Invert(this.root.getWorldMatrix());
+        // Vector transform through inverse includes inverse model scale: consumers should keep root scale 1.
+        const tuple = (v) => [v.x, v.y, v.z];
+        const velocity = (value, previous) => previous && dt > 0 ? Vector3.TransformNormal(value.subtract(previous).scale(1 / dt), inverse) : Vector3.Zero();
+        const bones = Object.fromEntries([...positions].map(([role, position]) => [role, {
+                position: tuple(Vector3.TransformCoordinates(position, inverse)), velocity: tuple(velocity(position, this.previous?.bones.get(role))),
+            }]));
+        const pose = { bones, rootVelocity: tuple(velocity(root, this.previous?.root)) };
+        this.previous = { bones: positions, root };
+        return pose;
+    }
+}
+/** Compatibility reader for the original two-foot preset. */
+export class BabylonPoseReader {
+    reader;
+    constructor(root, left, right) {
+        this.reader = new BabylonSchemaPoseReader(root, new Map([['leftFoot', left], ['rightFoot', right]]), LOCOMOTION_SCHEMA);
+    }
+    reset() { this.reader.reset(); }
+    read(dt) {
+        const pose = this.reader.read(dt);
+        return { leftPosition: pose.bones.leftFoot.position, rightPosition: pose.bones.rightFoot.position,
+            leftVelocity: pose.bones.leftFoot.velocity, rightVelocity: pose.bones.rightFoot.velocity, rootVelocity: pose.rootVelocity };
+    }
+}

package/dist/offline/src/core/controller.js

@@ -0,0 +1,97 @@
+import { PoseSearch } from './search.js';
+/** Owns animation time only. Caller retains movement and action authority. */
+export class MotionMatcher {
+    database;
+    search;
+    options;
+    clip = -1;
+    time = 0;
+    sinceSearch = Infinity;
+    sinceSwitch = Infinity;
+    last = null;
+    completed = new Map();
+    indices;
+    constructor(database, options = {}) {
+        this.database = database;
+        this.search = new PoseSearch(database);
+        this.options = { searchInterval: 0.1, minimumHold: 0.12, improvement: 0.1, jumpPenalty: 0.5, timeSeparation: 0.2, reselectDelay: 0.6, ...options };
+        if (!Object.values(this.options).every(v => Number.isFinite(v) && v >= 0) || this.options.searchInterval === 0 || this.options.improvement >= 1)
+            throw new Error('Invalid matcher options');
+        this.indices = database.manifest.clips.map((_, clip) => database.manifest.frames.flatMap((f, i) => f.clip === clip ? [i] : []).sort((a, b) => database.manifest.frames[a].time - database.manifest.frames[b].time));
+        if (this.indices.some(i => !i.length))
+            throw new Error('Every clip must have indexed samples');
+    }
+    reset() { this.clip = -1; this.time = 0; this.sinceSearch = this.sinceSwitch = Infinity; this.last = null; this.completed.clear(); }
+    update(dt, query) {
+        if (!Number.isFinite(dt) || dt < 0)
+            throw new Error('Invalid delta time');
+        // Validate identity even while continuity skips a search this frame.
+        this.search.validateQuery(query);
+        let switched = false, ended = false;
+        for (const [clip, remaining] of this.completed) {
+            if (remaining <= dt)
+                this.completed.delete(clip);
+            else
+                this.completed.set(clip, remaining - dt);
+        }
+        if (this.clip >= 0) {
+            const clip = this.database.manifest.clips[this.clip];
+            this.time += dt;
+            ended = !clip.looping && this.time >= clip.duration;
+            this.time = clip.looping ? this.time % clip.duration : Math.min(this.time, clip.duration);
+        }
+        this.sinceSearch += dt;
+        this.sinceSwitch += dt;
+        const allowed = this.clip >= 0 && !query.excludedClips?.has(this.clip) && (!query.gaits || query.gaits.has(this.database.manifest.clips[this.clip].gait));
+        if (this.sinceSearch >= this.options.searchInterval || !allowed || ended) {
+            this.sinceSearch = 0;
+            // A finished one-shot must yield to another clip, rather than selecting
+            // its terminal pose and restarting forever. User exclusions still apply.
+            if (ended)
+                this.completed.set(this.clip, this.options.reselectDelay);
+            const excludedClips = new Set([...(query.excludedClips ?? []), ...this.completed.keys()]);
+            const best = this.search.search({ ...query, excludedClips });
+            this.last = best;
+            if (best) {
+                const current = this.clip >= 0 ? this.nearestFrame(this.clip, this.time) : -1;
+                const duration = this.database.manifest.clips[best.clip].duration;
+                let gap = Math.abs(best.time - this.time);
+                if (best.clip === this.clip && this.database.manifest.clips[best.clip].looping)
+                    gap = Math.min(gap, duration - gap);
+                const distant = best.clip !== this.clip || gap > this.options.timeSeparation;
+                const better = current < 0 || best.cost + this.options.jumpPenalty < this.search.cost(current) * (1 - this.options.improvement);
+                const incompatibleVelocity = current >= 0 && distant && this.sinceSwitch >= this.options.minimumHold && query.velocityTolerance !== undefined
+                    && this.search.rootVelocityError(current, query) > Math.max(query.velocityTolerance, this.search.rootVelocityError(best.index, query) + 1e-6);
+                const mayReselectTime = query.allowTemporalReselection !== false || best.clip !== this.clip || !this.database.manifest.clips[best.clip].looping;
+                if (current < 0 || !allowed || ended || (mayReselectTime && (incompatibleVelocity || (distant && better && this.sinceSwitch >= this.options.minimumHold)))) {
+                    this.clip = best.clip;
+                    this.time = best.time;
+                    this.sinceSwitch = 0;
+                    switched = true;
+                }
+            }
+            else if (!allowed || ended) {
+                this.clip = -1;
+                this.time = 0;
+            }
+        }
+        return { clip: this.clip, time: this.time, switched, match: this.last };
+    }
+    nearestFrame(clip, time) {
+        const indices = this.indices[clip];
+        if (!indices?.length)
+            return -1;
+        const { frames, clips } = this.database.manifest;
+        let best = indices[0], distance = Infinity;
+        for (const i of indices) {
+            let delta = Math.abs(frames[i].time - time);
+            if (clips[clip].looping)
+                delta = Math.min(delta, clips[clip].duration - delta);
+            if (delta < distance) {
+                best = i;
+                distance = delta;
+            }
+        }
+        return best;
+    }
+}

package/dist/offline/src/core/database.js

@@ -0,0 +1,95 @@
+import { compileSchema, LOCOMOTION_SCHEMA } from './schema.js';
+import { parseRootOrientation } from './profile.js';
+const record = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+export function validateDatabase(db) {
+    const m = db?.manifest;
+    if (!record(m) || m.version !== 2)
+        throw new Error('Unsupported pose database version; v1 requires migrateLegacyDatabase or a new bake');
+    const layout = compileSchema(m.schema), dimensions = layout.dimensions;
+    if (m.dimensions !== dimensions || m.schemaSignature !== layout.signature || m.coordinates !== 'meters-y-up-z-forward'
+        || !Array.isArray(m.horizons) || m.horizons.length !== layout.horizons.length || m.horizons.some((v, i) => v !== layout.horizons[i]))
+        throw new Error('Incompatible pose database schema');
+    if (!Number.isFinite(m.sampleRate) || m.sampleRate <= 0 || !Array.isArray(m.frames) || !m.frames.length || !Array.isArray(m.clips) || !m.clips.length
+        || !(db.features instanceof Float32Array) || db.features.length !== m.frames.length * dimensions)
+        throw new Error('Invalid database size/sample rate');
+    if (!Array.isArray(m.mean) || !Array.isArray(m.std) || m.mean.length !== dimensions || m.std.length !== dimensions || ![...m.mean].every(Number.isFinite)
+        || ![...m.std].every(v => Number.isFinite(v) && v >= 1e-4) || !db.features.every(Number.isFinite))
+        throw new Error('Invalid normalization/features');
+    for (const { channel, offset, dimensions: width } of layout.channels)
+        if (channel.normalization === 'none') {
+            for (let j = offset; j < offset + width; j++)
+                if (m.mean[j] !== 0 || m.std[j] !== 1)
+                    throw new Error('Invalid unnormalized channel statistics');
+        }
+    if (m.assetHashes !== undefined && (!record(m.assetHashes) || !Object.entries(m.assetHashes).length || !Object.entries(m.assetHashes).every(([url, hash]) => url.startsWith('/') && typeof hash === 'string' && /^[a-f0-9]{64}$/.test(hash))))
+        throw new Error('Invalid asset hashes');
+    const ids = new Set();
+    for (const clip of m.clips) {
+        if (!record(clip) || typeof clip.id !== 'string' || ids.has(clip.id) || !clip.id || typeof clip.file !== 'string' || !clip.file
+            || typeof clip.animation !== 'string' || !clip.animation || !Number.isFinite(clip.duration) || clip.duration <= 0 || typeof clip.looping !== 'boolean'
+            || !['idle', 'walk', 'run', 'strafe', 'turn', 'stop'].includes(clip.gait))
+            throw new Error('Invalid clip');
+        ids.add(clip.id);
+        if (clip.sourceStart !== undefined && (!Number.isFinite(clip.sourceStart) || clip.sourceStart < 0))
+            throw new Error('Invalid source start');
+        if (clip.averageVelocity !== undefined && (!Array.isArray(clip.averageVelocity) || clip.averageVelocity.length !== 3 || !clip.averageVelocity.every(Number.isFinite)))
+            throw new Error('Invalid measured average velocity');
+        if (clip.rootOrientation !== undefined)
+            parseRootOrientation(clip.rootOrientation);
+    }
+    for (const frame of m.frames) {
+        if (!record(frame) || !Number.isInteger(frame.clip) || !m.clips[frame.clip] || !Number.isFinite(frame.time)
+            || frame.time < 0 || frame.time > m.clips[frame.clip].duration + 1e-6)
+            throw new Error('Invalid pose metadata');
+    }
+}
+/** Omitting schema selects the legacy biped preset. New data is always v2. */
+export function buildDatabase(manifest, raw, schema = LOCOMOTION_SCHEMA) {
+    const layout = compileSchema(schema), dimensions = layout.dimensions, count = manifest.frames.length;
+    if (!count || raw.length !== count * dimensions || !raw.every(Number.isFinite))
+        throw new Error('Invalid raw samples');
+    const mean = Array(dimensions).fill(0), std = Array(dimensions).fill(0);
+    for (let i = 0; i < raw.length; i++)
+        mean[i % dimensions] += raw[i] / count;
+    for (let i = 0; i < raw.length; i++)
+        std[i % dimensions] += (raw[i] - mean[i % dimensions]) ** 2 / count;
+    for (let j = 0; j < dimensions; j++)
+        std[j] = Math.sqrt(std[j]) < 1e-4 ? 1 : Math.sqrt(std[j]);
+    for (const { channel, offset, dimensions: width } of layout.channels)
+        if (channel.normalization === 'none') {
+            mean.fill(0, offset, offset + width);
+            std.fill(1, offset, offset + width);
+        }
+    const features = Float32Array.from(raw, (v, i) => (v - mean[i % dimensions]) / std[i % dimensions]);
+    const db = { manifest: { ...manifest, version: 2, dimensions, schema: layout.schema, schemaSignature: layout.signature,
+            coordinates: 'meters-y-up-z-forward', horizons: layout.horizons, mean, std }, features };
+    validateDatabase(db);
+    return db;
+}
+/** Binary format is explicitly little endian float32; version/layout live in manifest. */
+export function encodeFeatures(db) {
+    validateDatabase(db);
+    const bytes = new ArrayBuffer(db.features.length * 4), view = new DataView(bytes);
+    db.features.forEach((v, i) => view.setFloat32(i * 4, v, true));
+    return bytes;
+}
+export function decodeDatabase(manifest, bytes, expectedSchema) {
+    if (bytes.byteLength % 4)
+        throw new Error('Truncated feature binary');
+    const view = new DataView(bytes), features = new Float32Array(bytes.byteLength / 4);
+    for (let i = 0; i < features.length; i++)
+        features[i] = view.getFloat32(i * 4, true);
+    const db = { manifest: manifest, features };
+    validateDatabase(db);
+    if (expectedSchema && db.manifest.schemaSignature !== compileSchema(expectedSchema).signature)
+        throw new Error('Incompatible expected schema; regenerate database');
+    return db;
+}
+/** Explicit, lossless conversion ONLY for the original v1 27-dimensional preset. */
+export function migrateLegacyDatabase(input, bytes) {
+    const layout = compileSchema(LOCOMOTION_SCHEMA);
+    if (!record(input) || input.version !== 1 || input.dimensions !== layout.dimensions || !Array.isArray(input.horizons)
+        || input.horizons.length !== layout.horizons.length || input.horizons.some((h, i) => h !== layout.horizons[i]))
+        throw new Error('Unsupported legacy database schema');
+    return decodeDatabase({ ...input, version: 2, schema: layout.schema, schemaSignature: layout.signature }, bytes);
+}

package/dist/offline/src/core/features.js

@@ -0,0 +1,41 @@
+import { DIMENSIONS, HORIZONS } from './types.js';
+import { SchemaQueryBuilder, validateHorizons } from './schema.js';
+const legacyBuilder = new SchemaQueryBuilder();
+export function featureVector(pose, trajectory, out = new Float32Array(DIMENSIONS)) {
+    return legacyBuilder.features({ rootVelocity: pose.rootVelocity, bones: {
+            leftFoot: { position: pose.leftPosition, velocity: pose.leftVelocity },
+            rightFoot: { position: pose.rightPosition, velocity: pose.rightVelocity },
+        } }, trajectory, out);
+}
+/** World delta to current character-local XZ (yaw zero looks along +Z). */
+export function toLocal(x, z, yaw) {
+    const c = Math.cos(yaw), s = Math.sin(yaw);
+    return [c * x - s * z, s * x + c * z];
+}
+/** Prediction only: never writes to the gameplay controller. Uses fixed substeps. */
+export function predictTrajectory(input, horizons = HORIZONS) {
+    validateHorizons(horizons);
+    if (![...input.velocity, ...input.desiredVelocity, input.yaw, input.desiredYaw, input.acceleration, input.braking, input.turnSpeed].every(Number.isFinite)
+        || Math.min(input.acceleration, input.braking, input.turnSpeed) < 0)
+        throw new Error('Invalid trajectory input');
+    let [vx, vz] = input.velocity, x = 0, z = 0, yaw = input.yaw, elapsed = 0;
+    const points = [];
+    for (const horizon of horizons) {
+        while (elapsed < horizon - 1e-9) {
+            const dt = Math.min(1 / 60, horizon - elapsed);
+            const dx = input.desiredVelocity[0] - vx, dz = input.desiredVelocity[1] - vz, length = Math.hypot(dx, dz);
+            const rate = Math.hypot(...input.desiredVelocity) < Math.hypot(vx, vz) ? input.braking : input.acceleration;
+            const amount = length > 0 ? Math.min(1, rate * dt / length) : 0;
+            const nx = vx + dx * amount, nz = vz + dz * amount;
+            x += (vx + nx) * 0.5 * dt;
+            z += (vz + nz) * 0.5 * dt;
+            vx = nx;
+            vz = nz;
+            const angle = Math.atan2(Math.sin(input.desiredYaw - yaw), Math.cos(input.desiredYaw - yaw));
+            yaw += Math.sign(angle) * Math.min(Math.abs(angle), input.turnSpeed * dt);
+            elapsed += dt;
+        }
+        points.push({ position: toLocal(x, z, input.yaw), facing: [Math.sin(yaw - input.yaw), Math.cos(yaw - input.yaw)] });
+    }
+    return points;
+}

package/dist/offline/src/core/profile.js

@@ -0,0 +1,89 @@
+import { compileSchema, parseSchema } from './schema.js';
+const record = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const name = (v) => typeof v === 'string' && v.trim().length > 0;
+const asset = (v) => name(v) && !v.includes('\\') && !v.includes('..') && !/[?#:]/.test(v);
+export function parseRootOrientation(value) {
+    if (!Array.isArray(value) || value.length !== 4 || ![...value].every(Number.isFinite) || Math.abs(Math.hypot(...value) - 1) > 1e-5)
+        throw new Error('Invalid rootOrientation: expected unit quaternion [x,y,z,w]');
+    return [...value];
+}
+/** Read untrusted JSON as unknown; report a configuration error before loading assets. */
+export function parseProfile(input) {
+    if (!record(input) || input.version !== 2 || !name(input.id) || !/^[a-z0-9][a-z0-9-]*$/.test(input.id) || !name(input.label))
+        throw new Error('Profile: expected version 2; split v1 clips into animationSet and declare schema');
+    if ('clips' in input || !asset(input.schema) || !input.schema.startsWith('/') || !input.schema.endsWith('.json')
+        || !asset(input.animationSet) || !input.animationSet.startsWith('/') || !input.animationSet.endsWith('.json'))
+        throw new Error('Profile: declare schema and animationSet JSON URLs, without inline clips');
+    if (!asset(input.assetBase) || !input.assetBase.startsWith('/') || !input.assetBase.endsWith('/') || !asset(input.database) || !input.database.startsWith('/') || !input.database.endsWith('/')
+        || !asset(input.model) || input.model.startsWith('/'))
+        throw new Error('Profile: use public URL folders and relative model files');
+    if (typeof input.scale !== 'number' || !Number.isFinite(input.scale) || input.scale <= 0 || typeof input.sampleRate !== 'number' || !Number.isFinite(input.sampleRate) || input.sampleRate < 1 || input.sampleRate > 120)
+        throw new Error('Profile: invalid scale/sampleRate');
+    if (!record(input.rig) || !name(input.rig.root) || !Object.entries(input.rig).every(([k, v]) => /^[a-zA-Z][a-zA-Z0-9_-]*$/.test(k) && name(v)))
+        throw new Error('Profile: semantic rig roles must be mapped');
+    if (new Set(Object.values(input.rig)).size !== Object.values(input.rig).length)
+        throw new Error('Profile: required bones must be distinct');
+    if (input.stripRoot !== undefined && !name(input.stripRoot))
+        throw new Error('Profile: invalid stripRoot');
+    if (input.boneMap !== undefined && (!record(input.boneMap) || !Object.entries(input.boneMap).every(([k, v]) => name(k) && name(v)) || new Set(Object.values(input.boneMap)).size !== Object.values(input.boneMap).length))
+        throw new Error('Profile: boneMap must map distinct nonempty names');
+    return structuredClone(input);
+}
+export function parseAnimationSet(input) {
+    if (!record(input) || input.version !== 1 || !name(input.id) || !Array.isArray(input.clips) || !input.clips.length)
+        throw new Error('AnimationSet: invalid version/id/clips');
+    const ids = new Set();
+    for (const clip of input.clips) {
+        if (!record(clip) || !name(clip.id) || ids.has(clip.id) || !asset(clip.file) || clip.file.startsWith('/') || !name(clip.animation) || typeof clip.looping !== 'boolean'
+            || !['idle', 'walk', 'run', 'strafe', 'turn', 'stop'].includes(String(clip.gait)))
+            throw new Error('Profile: invalid/duplicate clip');
+        ids.add(clip.id);
+        if (clip.rootOrientation !== undefined)
+            parseRootOrientation(clip.rootOrientation);
+        if (clip.range !== undefined && (!Array.isArray(clip.range) || clip.range.length !== 2 || !clip.range.every(Number.isFinite) || clip.range[0] < 0 || clip.range[1] <= clip.range[0]))
+            throw new Error('Invalid clip range');
+        const nominal = clip.nominalVelocity !== undefined, measured = clip.motionFile !== undefined;
+        if (nominal === measured)
+            throw new Error(`Profile ${clip.id}: declare exactly one of nominalVelocity or motionFile`);
+        if (nominal && (!Array.isArray(clip.nominalVelocity) || clip.nominalVelocity.length !== 3 || !clip.nominalVelocity.every(Number.isFinite)))
+            throw new Error(`Profile ${clip.id}: invalid velocity`);
+        if (measured && (!asset(clip.motionFile) || clip.motionFile.startsWith('/')))
+            throw new Error(`Profile ${clip.id}: measured motion requires a relative file`);
+    }
+    return structuredClone(input);
+}
+/** Resolve external configuration explicitly; core performs no I/O. */
+export function resolveProfile(profile, schemaInput, setInput) {
+    const config = parseProfile(profile), schemaDefinition = parseSchema(schemaInput), set = parseAnimationSet(setInput);
+    for (const role of compileSchema(schemaDefinition).bones)
+        if (!Object.hasOwn(config.rig, role))
+            throw new Error('Profile: missing schema bone role: ' + role);
+    if (!config.stripRoot && set.clips.some(c => c.rootOrientation !== undefined))
+        throw new Error('Profile: rootOrientation requires stripRoot');
+    return { ...config, schemaDefinition, clips: set.clips, setId: set.id };
+}
+/** Deterministic configuration fingerprint; detects stale banks, not a security signature. */
+export function profileSignature(profile) {
+    const sorted = (value) => Array.isArray(value) ? value.map(sorted) : record(value) ? Object.fromEntries(Object.keys(value).sort().map(k => [k, sorted(value[k])])) : value;
+    const text = JSON.stringify(sorted(profile));
+    let hash = 2166136261;
+    for (let i = 0; i < text.length; i++)
+        hash = Math.imul(hash ^ text.charCodeAt(i), 16777619);
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}
+/** Suggestions only: ambiguity is returned to the caller, never silently resolved. */
+export function suggestRig(names) {
+    const aliases = { root: ['root', 'hips', 'pelvis'], leftFoot: ['footl', 'leftfoot', 'lfoot'], rightFoot: ['footr', 'rightfoot', 'rfoot'] };
+    return Object.fromEntries(Object.entries(aliases).map(([role, values]) => [role, names.filter(n => values.includes(n.split(':').at(-1).toLowerCase().replace(/[^a-z]/g, '')))]));
+}
+/** Semantic availability, independent of character/clip names. Preserve optional actions. */
+export function filterLocomotionGaits(available, speed) {
+    if (!Number.isFinite(speed) || speed < 0)
+        throw new Error('Invalid locomotion speed');
+    const result = new Set(available), movement = ['walk', 'run', 'strafe'];
+    if (speed > 0.2 && movement.some(g => result.has(g)))
+        result.delete('idle');
+    else if (speed < 0.05 && result.has('idle'))
+        movement.forEach(g => result.delete(g));
+    return result;
+}

package/dist/offline/src/core/root-motion.js

@@ -0,0 +1,78 @@
+import { HORIZONS } from './types.js';
+import { toLocal } from './features.js';
+import { validateHorizons } from './schema.js';
+export function validateRootMotion(track) {
+    if (!track || track.version !== 1 || !['hips', 'root'].includes(track.source) || !Number.isFinite(track.duration) || track.duration <= 0 || !Array.isArray(track.samples) || track.samples.length < 2)
+        throw new Error('Invalid root motion track');
+    let previous = -Infinity;
+    for (const sample of track.samples) {
+        if (!sample || ![sample.time, sample.x, sample.z, sample.yaw].every(Number.isFinite) || sample.time <= previous || sample.time < 0 || sample.time > track.duration + 1e-6)
+            throw new Error('Invalid root motion sample');
+        previous = sample.time;
+    }
+    if (track.samples[0].time !== 0 || Math.abs(track.samples.at(-1).time - track.duration) > 1e-6)
+        throw new Error('Incomplete root motion track');
+}
+/** Clamped sampling for non-looping clips; completed motion stays at its endpoint. */
+export function sampleRootMotion(track, time, looping = false) {
+    if (!Number.isFinite(time))
+        throw new Error('Invalid root motion time');
+    if (looping) {
+        const cycle = Math.floor(time / track.duration), phase = time - cycle * track.duration;
+        if (!Number.isSafeInteger(cycle))
+            throw new Error('Root motion cycle out of range');
+        const first = track.samples[0], last = track.samples.at(-1);
+        const delta = toLocal(last.x - first.x, last.z - first.z, first.yaw), angle = last.yaw - first.yaw;
+        // Exponentiate planar rigid transforms, including negative cycles.
+        const compose = (a, b) => ({ time,
+            x: a.x + Math.cos(a.yaw) * b.x + Math.sin(a.yaw) * b.z,
+            z: a.z - Math.sin(a.yaw) * b.x + Math.cos(a.yaw) * b.z, yaw: a.yaw + b.yaw });
+        let power = { time, x: delta[0], z: delta[1], yaw: angle };
+        if (cycle < 0) {
+            const v = toLocal(-power.x, -power.z, angle);
+            power = { time, x: v[0], z: v[1], yaw: -angle };
+        }
+        let result = { time, x: 0, z: 0, yaw: 0 }, count = Math.abs(cycle);
+        while (count > 0) {
+            if (count % 2 === 1)
+                result = compose(result, power);
+            power = compose(power, power);
+            count = Math.floor(count / 2);
+        }
+        const sample = sampleRootMotion(track, phase), local = toLocal(sample.x - first.x, sample.z - first.z, first.yaw);
+        return compose(first, compose(result, { time, x: local[0], z: local[1], yaw: sample.yaw - first.yaw }));
+    }
+    const t = Math.max(0, Math.min(time, track.duration)), samples = track.samples;
+    let lo = 0, hi = samples.length - 1;
+    while (hi - lo > 1) {
+        const mid = (lo + hi) >>> 1;
+        if (samples[mid].time <= t)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    const a = samples[lo], b = samples[hi], alpha = (t - a.time) / (b.time - a.time);
+    return { time: t, x: a.x + (b.x - a.x) * alpha, z: a.z + (b.z - a.z) * alpha, yaw: a.yaw + (b.yaw - a.yaw) * alpha };
+}
+export function rootMotionFeatures(track, time, derivativeStep = 1 / 30, horizons = HORIZONS, looping = false) {
+    validateHorizons(horizons);
+    if (!Number.isFinite(derivativeStep) || derivativeStep <= 0)
+        throw new Error('Invalid derivative step');
+    const now = sampleRootMotion(track, time, looping), a = sampleRootMotion(track, time - derivativeStep, looping), b = sampleRootMotion(track, time + derivativeStep, looping);
+    const elapsed = b.time - a.time;
+    const v = elapsed > 0 ? toLocal((b.x - a.x) / elapsed, (b.z - a.z) / elapsed, now.yaw) : [0, 0];
+    return { velocity: [v[0], 0, v[1]], angularVelocity: elapsed > 0 ? (b.yaw - a.yaw) / elapsed : 0,
+        trajectory: horizons.map(horizon => {
+            const future = sampleRootMotion(track, time + horizon, looping), yaw = future.yaw - now.yaw;
+            return { position: toLocal(future.x - now.x, future.z - now.z, now.yaw), facing: [Math.sin(yaw), Math.cos(yaw)] };
+        }) };
+}
+/** Crop to the same source interval as playback; preserve the source coordinate frame. */
+export function cropRootMotion(track, start, end) {
+    validateRootMotion(track);
+    if (!Number.isFinite(start) || !Number.isFinite(end) || start < 0 || end <= start || end > track.duration)
+        throw new Error('Invalid root motion range');
+    const samples = [sampleRootMotion(track, start), ...track.samples.filter(s => s.time > start && s.time < end), sampleRootMotion(track, end)]
+        .map(s => ({ ...s, time: s.time - start }));
+    return { version: 1, source: track.source, duration: end - start, samples };
+}