@pose_flow/babylon 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Motion Match contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# Motion Match · Babylon.js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+O código original desta biblioteca é distribuído sob a [licença MIT](LICENSE), com aviso de copyright “2026 Motion Match contributors”. Dependências, modelos, texturas e animações de terceiros mantêm suas próprias licenças; este aviso não os relicencia. Consulte a [proveniência dos assets](docs/ASSETS.md).
+
+Biblioteca TypeScript de Motion Matching clássico com Pose Search e laboratório 3D. Inspiração conceitual no Unreal Engine; implementação própria e inicial, sem paridade com o plugin da Epic.
+
+O banco compara **pose visível + velocidade + trajetória desejada** e seleciona clipe/tempo. O controlador do jogo continua responsável por posição, colisões, orientação e combate.
+
+**Prioridade atual: biblioteca reutilizável para diferentes personagens e jogos.** Modelo, rig, escala, clipes e banco são definidos por perfis JSON, compartilhados pelo bake e laboratório. Veja [como adicionar um personagem](docs/PROFILES.md). Há também o exemplo Barbarian com escala e sample rate próprios.
+
+## Executar
+
+```powershell
+npm ci
+npm run dev
+```
+
+Abrir http://127.0.0.1:5173. WASD movimenta, Shift corre, arraste orbita e scroll aproxima. O seletor alterna Knight/KayKit e Paladin/Mixamo. “Teste de locomoção” mantém um movimento ativo para inspeção, sem segurar teclas; voltar a “Manual” devolve o controle ao WASD. “Manter orientação” permite testar deslocamento lateral e para trás no modo manual. O painel mostra candidato, custo, tempo, transições e velocidade. O valor “Atualização MM” inclui o controlador e só inclui busca quando o intervalo vence.
+
+Os GLB e bancos já foram gerados neste workspace. Para regenerar:
+
+```powershell
+npm run bake
+npm run bake -- --paladin
+npm run validate:assets -- --profile public/profiles/barbarian.json
+npm run bake -- --profile public/profiles/barbarian.json
+npm run typecheck
+npm test
+npm run build
+npm run benchmark
+```
+
+O build produz `dist/` (biblioteca ESM + declarações) e `demo-dist/` (laboratório). O pacote npm inclui apenas a biblioteca, não os personagens. Não foi publicado.
+
+## Implementado
+
+- Núcleo sem engine: esquema fixo de 27 características, normalização compartilhada, busca exata ponderada em `Float32Array`, filtros de gait e banco versionado JSON + float32 little endian.
+- Continuidade: avanço natural, loops, fim de clipe, intervalo de busca, tempo mínimo entre trocas e margem de melhora. Defaults de tuning, não parâmetros oficiais do Unreal.
+- Predição com aceleração, frenagem e velocidade angular; horizontes 0,2 / 0,4 / 0,6 s.
+- Adaptador Babylon.js 7.54.3: leitura dos pés visíveis e reprodução com crossfade, incluindo saltos entre dois tempos do mesmo clipe.
+- Bake offline via o mesmo carregador/interpolador Babylon usado na demonstração.
+- Três bancos separados: **Knight, 174 poses / 6 clipes**; **Paladin, 610 poses / 9 clipes**; **Barbarian, 138 poses / 6 clipes**. Todos têm idle, walk, run, backward, left, right; o Paladin inclui stop, turn-left e turn-right sem loop.
+- Trajetória medida dos hips para os três novos clipes: posição, yaw contínuo, velocidade, interpolação e término sem repetir o início. Os dados extraídos alimentam apenas o bake; deslocamento e heading em runtime continuam definidos pelo controlador.
+- Pipeline Blender 5.2 para inspecionar e converter os FBX locais do Paladin.
+
+## Features e coordenadas
+
+| Índices | Característica |
+| --- | --- |
+| 0–5 | Posição local dos dois pés, XYZ |
+| 6–11 | Velocidade dos pés no mundo, expressa nos eixos locais, XYZ |
+| 12–14 | Velocidade do controlador nos eixos locais, XYZ |
+| 15–20 | Posições futuras locais, XZ, em três horizontes |
+| 21–26 | Direções futuras locais, XZ, em três horizontes |
+
+Metros, segundos, Y acima e Z frente. A demo e o bake usam `scene.useRightHandedSystem = true`. Nesse referencial, o lado anatômico esquerdo dos modelos olhando +Z aponta para +X; yaw positivo gira +Z em direção a +X. A direita da câmera é calculada por sua projeção, não por assumir +X. Query e banco precisam usar exatamente a mesma convenção e escala. Não mudar a convenção do MMORPG para importar a lib; adaptar seu referencial ou gerar banco compatível.
+
+Peso inicial por dimensão: pose/velocidade 1, trajetória/direção 3. Dimensões com desvio abaixo de 0,0001 usam escala 1, evitando amplificar canais constantes em bancos sem giros. Filtros são opcionais; a demonstração pesquisa todos os clipes.
+
+**Os dois conjuntos são reproduzidos in-place.** Nos seis loops básicos, velocidades em `tools/bake.ts` são parâmetros de autoria: frente 1,8/4,5 m/s; costas −1,5 m/s; strafe KayKit ±3,2 m/s; strafe Paladin ±1,8 m/s. São valores iniciais, não medidas. Esquerda usa +X e direita −X. O bake KayKit remove as mesmas trilhas de root que o player, inclusive o heading presente nos strafes.
+
+Para **stop e giros do Paladin**, Blender registra posição planar e yaw dos hips antes de remover esses movimentos da animação. Os arquivos `.motion.json` são amostrados em relação ao heading atual; futuros além do fim ficam no último estado. A velocidade dos pés inclui a contribuição da rotação do referencial. O movimento vertical do esqueleto é preservado. A orientação é um proxy extraído da pelvis e inclui oscilação natural; não equivale a root motion limpo de produção. Foot sliding ainda pode acontecer.
+
+O laboratório tem ciclos de parada e giros no seletor do Paladin. Filtros por estado disponibilizam parada durante frenagem e giro durante mudança de heading com baixa velocidade. A busca decide o clipe/tempo dentro dos candidatos permitidos. Clips concluídos ficam inelegíveis por 0,6 s (configurável em `reselectDelay`). `Query.excludedClips` permite outras exclusões explícitas. O painel exibe a origem da trajetória e as três últimas trocas.
+
+## API
+
+```ts
+import { decodeDatabase, MotionMatcher, featureVector, predictTrajectory } from '@motion-match/babylon';
+import { BabylonMotionPlayer, BabylonPoseReader } from '@motion-match/babylon/babylon';
+
+// manifest e bytes são carregados uma vez; sem bake durante o jogo.
+const database = decodeDatabase(manifest, bytes);
+const matcher = new MotionMatcher(database);
+// sources: Map<clip.id, AnimationGroup>; nodes: Map<nome original do osso, TransformNode>.
+const player = new BabylonMotionPlayer(scene, manifest.clips, sources, nodes);
+const reader = new BabylonPoseReader(controllerRoot, leftFoot, rightFoot);
+
+// A cada frame, usando a pose medida após a renderização anterior:
+const future = predictTrajectory(trajectoryInput);
+const query = { features: featureVector(lastVisiblePose, future) };
+const playback = matcher.update(dt, query);
+player.update(playback, dt); // antes de scene.render()
+scene.render();
+lastVisiblePose = reader.read(dt); // depois da avaliação de animações
+
+// Em teleporte/reconciliação descontínua: reader.reset(); matcher.reset().
+// Na remoção do personagem: player.dispose().
+```
+
+Instalar localmente no jogo, quando integrar: `npm install D:/motion_match`. Copiar os assets/banco necessários para a pasta pública do jogo é uma etapa separada. Ver contrato e restrições em [docs/INTEGRATION.md](docs/INTEGRATION.md).
+
+## Limites atuais
+
+Ainda não há IK, foot locking, contato dos pés, inertialization, motion warping, root-motion-driven movement, worker, KD-tree ou PCA. Starts e giros em movimento ainda não foram preparados. Os três clipes medidos são sem loop; não há extração com composição de root motion através de ciclos. A busca linear é apropriada para medir esta base pequena; não há garantia de orçamento em bancos grandes ou com muitos jogadores.
+
+A biblioteca tem esquema fixo, não um editor visual de schemas como o Unreal. Não há retargeting automático entre esqueletos diferentes. KayKit e Mixamo possuem bancos e mapas de ossos independentes. Crossfade de clips com trilhas ausentes exige preparação de cobertura dos ossos.
+
+O laboratório tem um bundle de demonstração grande pelo carregamento amplo de Babylon; o build avisa sobre isso. O núcleo da lib não depende de Babylon, e sua entrada pública separada permite usá-lo sem importar o adaptador.
+
+## Referências e proveniência
+
+- [Epic: Motion Matching](https://dev.epicgames.com/documentation/en-us/unreal-engine/motion-matching-in-unreal-engine): banco, pose, trajetória e busca.
+- [Babylon: Advanced Animations](https://doc.babylonjs.com/features/featuresDeepDive/animation/advanced_animations): grupos de animação e pesos. A implementação foi validada contra o código instalado da versão 7.54.3.
+- [Assets locais](docs/ASSETS.md), [evidências e pendências](docs/VALIDATION.md), [referência fornecida pelo usuário](MOTION_MATCHING_POSE_SEARCH_WEB_BASE_REFERENCIAS.md).

package/dist/babylon.d.ts

@@ -0,0 +1,29 @@
+import { AnimationGroup, TransformNode, type Scene } from '@babylonjs/core';
+import type { Clip, Playback, Pose } from './index.js';
+/** Clone onto a target rig. Two playback slots allow crossfade between times of the same clip. */
+export declare class BabylonMotionPlayer {
+    private scene;
+    private clips;
+    private sources;
+    private nodes;
+    readonly fadeSeconds: number;
+    private rootName;
+    private tracks;
+    private active?;
+    private disposed;
+    constructor(scene: Scene, clips: readonly Clip[], sources: ReadonlyMap<string, AnimationGroup>, nodes: ReadonlyMap<string, TransformNode>, fadeSeconds?: number, rootName?: string);
+    private create;
+    update(state: Playback, dt: number): void;
+    private clear;
+    dispose(): void;
+}
+/** Sample AFTER scene animation evaluation. Measures visible feet, including crossfade. */
+export declare class BabylonPoseReader {
+    private root;
+    private left;
+    private right;
+    private previous?;
+    constructor(root: TransformNode, left: TransformNode, right: TransformNode);
+    reset(): void;
+    read(dt: number): Pose;
+}

package/dist/babylon.js

@@ -0,0 +1,126 @@
+import { AnimationGroup, Matrix, Vector3 } from '@babylonjs/core';
+/** 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;
+    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)
+            if (!sources.has(clip.id))
+                throw new Error(`Missing animation source: ${clip.id}`);
+    }
+    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);
+        for (const targeted of source.targetedAnimations) {
+            const node = this.nodes.get(targeted.target.name);
+            if (!node)
+                continue;
+            const property = targeted.animation.targetProperty;
+            // Gameplay owns horizontal root displacement AND heading. Preserve vertical bob only on other bones.
+            if (node.name === this.rootName && (property === 'position' || property === 'rotationQuaternion' || property === 'rotation'))
+                continue;
+            group.addTargetedAnimation(targeted.animation, node);
+        }
+        if (!group.targetedAnimations.length) {
+            group.dispose();
+            throw new Error('No matching rig animation tracks');
+        }
+        // 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 : Math.min(track.time, descriptor.duration);
+            group.setWeightForAllAnimatables(total > 0 ? track.weight / total : (track === this.active ? 1 : 0));
+            group.goToFrame(group.from + (group.to - group.from) * time / descriptor.duration, 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. Measures visible feet, including crossfade. */
+export class BabylonPoseReader {
+    root;
+    left;
+    right;
+    previous;
+    constructor(root, left, right) {
+        this.root = root;
+        this.left = left;
+        this.right = right;
+    }
+    reset() { this.previous = undefined; }
+    read(dt) {
+        if (!Number.isFinite(dt) || dt < 0)
+            throw new Error('Invalid pose delta');
+        this.root.computeWorldMatrix(true);
+        this.left.computeWorldMatrix(true);
+        this.right.computeWorldMatrix(true);
+        const root = this.root.getAbsolutePosition().clone(), left = this.left.getAbsolutePosition().clone(), right = this.right.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 pose = { leftPosition: tuple(Vector3.TransformCoordinates(left, inverse)), rightPosition: tuple(Vector3.TransformCoordinates(right, inverse)),
+            leftVelocity: tuple(velocity(left, this.previous?.left)), rightVelocity: tuple(velocity(right, this.previous?.right)), rootVelocity: tuple(velocity(root, this.previous?.root)) };
+        this.previous = { left, right, root };
+        return pose;
+    }
+}

package/dist/core/controller.d.ts

@@ -0,0 +1,33 @@
+import { PoseSearch } from './search.js';
+import type { Database, Match, Query } from './types.js';
+export interface Playback {
+    clip: number;
+    time: number;
+    switched: boolean;
+    match: Match | null;
+}
+export interface MatcherOptions {
+    searchInterval: number;
+    minimumHold: number;
+    improvement: number;
+    jumpPenalty: number;
+    timeSeparation: number;
+    reselectDelay: number;
+}
+/** Owns animation time only. Caller retains movement and action authority. */
+export declare class MotionMatcher {
+    readonly database: Database;
+    readonly search: PoseSearch;
+    readonly options: MatcherOptions;
+    private clip;
+    private time;
+    private sinceSearch;
+    private sinceSwitch;
+    private last;
+    private completed;
+    private indices;
+    constructor(database: Database, options?: Partial<MatcherOptions>);
+    reset(): void;
+    update(dt: number, query: Query): Playback;
+    nearestFrame(clip: number, time: number): number;
+}

package/dist/core/controller.js

@@ -0,0 +1,92 @@
+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');
+        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);
+                if (current < 0 || !allowed || ended || (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/core/database.d.ts

@@ -0,0 +1,6 @@
+import { type Database, type DatabaseManifest } from './types.js';
+export declare function validateDatabase(db: Database): void;
+export declare function buildDatabase(manifest: Omit<DatabaseManifest, 'version' | 'dimensions' | 'coordinates' | 'horizons' | 'mean' | 'std'>, raw: Float32Array): Database;
+/** Binary format is explicitly little endian float32; version/layout live in manifest. */
+export declare function encodeFeatures(db: Database): ArrayBuffer;
+export declare function decodeDatabase(manifest: DatabaseManifest, bytes: ArrayBuffer): Database;

package/dist/core/database.js

@@ -0,0 +1,59 @@
+import { DIMENSIONS, HORIZONS } from './types.js';
+export function validateDatabase(db) {
+    const m = db.manifest;
+    if (m.version !== 1 || m.dimensions !== DIMENSIONS || m.coordinates !== 'meters-y-up-z-forward'
+        || m.horizons.length !== 3 || m.horizons.some((v, i) => v !== HORIZONS[i]))
+        throw new Error('Unsupported pose database schema');
+    if (!Number.isFinite(m.sampleRate) || m.sampleRate <= 0 || !m.frames.length || !m.clips.length
+        || db.features.length !== m.frames.length * DIMENSIONS)
+        throw new Error('Invalid database size/sample rate');
+    if (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');
+    const ids = new Set();
+    for (const clip of m.clips) {
+        if (ids.has(clip.id) || !clip.id || !clip.file || !clip.animation || !Number.isFinite(clip.duration) || clip.duration <= 0
+            || !['idle', 'walk', 'run', 'strafe', 'turn', 'stop'].includes(clip.gait))
+            throw new Error('Invalid clip');
+        ids.add(clip.id);
+    }
+    for (const frame of m.frames) {
+        if (!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');
+    }
+}
+export function buildDatabase(manifest, raw) {
+    const 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;
+    // Constant channels carry no measured variation. A unit scale avoids amplifying
+    // unsupported trajectories (e.g. turns absent from the dataset) by 10,000×.
+    for (let j = 0; j < DIMENSIONS; j++)
+        std[j] = Math.sqrt(std[j]) < 1e-4 ? 1 : Math.sqrt(std[j]);
+    const features = Float32Array.from(raw, (v, i) => (v - mean[i % DIMENSIONS]) / std[i % DIMENSIONS]);
+    const db = { manifest: { ...manifest, version: 1, dimensions: DIMENSIONS, coordinates: 'meters-y-up-z-forward', horizons: HORIZONS, mean, std }, features };
+    validateDatabase(db);
+    return db;
+}
+/** Binary format is explicitly little endian float32; version/layout live in manifest. */
+export function encodeFeatures(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) {
+    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, features };
+    validateDatabase(db);
+    return db;
+}

package/dist/core/features.d.ts

@@ -0,0 +1,15 @@
+import { type Pose, type TrajectoryPoint } from './types.js';
+export declare function featureVector(pose: Pose, trajectory: readonly TrajectoryPoint[], out?: Float32Array<ArrayBuffer>): Float32Array;
+/** World delta to current character-local XZ (yaw zero looks along +Z). */
+export declare function toLocal(x: number, z: number, yaw: number): [number, number];
+export interface TrajectoryInput {
+    velocity: readonly [number, number];
+    desiredVelocity: readonly [number, number];
+    yaw: number;
+    desiredYaw: number;
+    acceleration: number;
+    braking: number;
+    turnSpeed: number;
+}
+/** Prediction only: never writes to the gameplay controller. Uses fixed substeps. */
+export declare function predictTrajectory(input: TrajectoryInput): TrajectoryPoint[];

package/dist/core/features.js

@@ -0,0 +1,43 @@
+import { DIMENSIONS, HORIZONS } from './types.js';
+export function featureVector(pose, trajectory, out = new Float32Array(DIMENSIONS)) {
+    if (trajectory.length !== 3 || out.length !== DIMENSIONS)
+        throw new Error('Expected 3 trajectory points and 27 features');
+    out.set(pose.leftPosition, 0);
+    out.set(pose.rightPosition, 3);
+    out.set(pose.leftVelocity, 6);
+    out.set(pose.rightVelocity, 9);
+    out.set(pose.rootVelocity, 12);
+    trajectory.forEach((point, i) => { out.set(point.position, 15 + i * 2); out.set(point.facing, 21 + i * 2); });
+    return 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) {
+    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/core/profile.d.ts

@@ -0,0 +1,37 @@
+import type { Gait, Vec3 } from './types.js';
+export interface CharacterProfile {
+    version: 1;
+    id: string;
+    label: string;
+    assetBase: string;
+    model: string;
+    database: string;
+    scale: number;
+    sampleRate: number;
+    rig: {
+        root: string;
+        leftFoot: string;
+        rightFoot: string;
+    };
+    /** Source animation node -> model node; name mapping does not perform retargeting. */
+    boneMap?: Record<string, string>;
+    /** Model node whose position/heading tracks are excluded by the player. */
+    stripRoot?: string;
+    clips: {
+        id: string;
+        file: string;
+        animation: string;
+        gait: Gait;
+        looping: boolean;
+        nominalVelocity?: Vec3;
+        motionFile?: string;
+    }[];
+}
+/** Read untrusted JSON as unknown; report a configuration error before loading assets. */
+export declare function parseProfile(input: unknown): CharacterProfile;
+/** Deterministic configuration fingerprint; detects stale banks, not a security signature. */
+export declare function profileSignature(profile: CharacterProfile): string;
+/** Suggestions only: ambiguity is returned to the caller, never silently resolved. */
+export declare function suggestRig(names: readonly string[]): Record<'root' | 'leftFoot' | 'rightFoot', string[]>;
+/** Semantic availability, independent of character/clip names. Preserve optional actions. */
+export declare function filterLocomotionGaits(available: ReadonlySet<Gait>, speed: number): Set<Gait>;

package/dist/core/profile.js

@@ -0,0 +1,64 @@
+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);
+/** Read untrusted JSON as unknown; report a configuration error before loading assets. */
+export function parseProfile(input) {
+    if (!record(input) || input.version !== 1 || !name(input.id) || !/^[a-z0-9][a-z0-9-]*$/.test(input.id) || !name(input.label))
+        throw new Error('Profile: invalid version/id/label');
+    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) || !name(input.rig.leftFoot) || !name(input.rig.rightFoot))
+        throw new Error('Profile: root and both feet must be mapped');
+    const rig = input.rig;
+    if (new Set([rig.root, rig.leftFoot, rig.rightFoot]).size !== 3)
+        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');
+    if (!Array.isArray(input.clips) || !input.clips.length)
+        throw new Error('Profile: no 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);
+        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('/') || clip.looping))
+            throw new Error(`Profile ${clip.id}: measured motion requires a relative file and non-looping clip`);
+    }
+    return structuredClone(input);
+}
+/** 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/core/root-motion.d.ts

@@ -0,0 +1,22 @@
+import { type TrajectoryPoint } from './types.js';
+export interface RootMotionSample {
+    time: number;
+    x: number;
+    z: number;
+    yaw: number;
+}
+/** Unwrapped yaw in radians. Root track is a bake input, never a movement command. */
+export interface RootMotionTrack {
+    version: 1;
+    duration: number;
+    source: 'hips';
+    samples: RootMotionSample[];
+}
+export declare function validateRootMotion(track: RootMotionTrack): void;
+/** Clamped sampling for non-looping clips; completed motion stays at its endpoint. */
+export declare function sampleRootMotion(track: RootMotionTrack, time: number): RootMotionSample;
+export declare function rootMotionFeatures(track: RootMotionTrack, time: number, derivativeStep?: number): {
+    velocity: readonly [number, number, number];
+    angularVelocity: number;
+    trajectory: TrajectoryPoint[];
+};

package/dist/core/root-motion.js

@@ -0,0 +1,42 @@
+import { HORIZONS } from './types.js';
+import { toLocal } from './features.js';
+export function validateRootMotion(track) {
+    if (track.version !== 1 || track.source !== 'hips' || !Number.isFinite(track.duration) || track.duration <= 0 || track.samples.length < 2)
+        throw new Error('Invalid root motion track');
+    let previous = -Infinity;
+    for (const sample of track.samples) {
+        if (!Object.values(sample).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) {
+    if (!Number.isFinite(time))
+        throw new Error('Invalid root motion time');
+    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) {
+    if (!Number.isFinite(derivativeStep) || derivativeStep <= 0)
+        throw new Error('Invalid derivative step');
+    const now = sampleRootMotion(track, time), a = sampleRootMotion(track, time - derivativeStep), b = sampleRootMotion(track, time + derivativeStep);
+    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), 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)] };
+        }) };
+}

package/dist/core/search.d.ts

@@ -0,0 +1,11 @@
+import { type Database, type Match, type Query } from './types.js';
+export declare function defaultWeights(): Float32Array;
+export declare class PoseSearch {
+    readonly database: Database;
+    private normalized;
+    readonly weights: Float32Array;
+    constructor(database: Database, weights?: Float32Array<ArrayBufferLike>);
+    normalize(query: Query): void;
+    cost(index: number): number;
+    search(query: Query): Match | null;
+}

package/dist/core/search.js

@@ -0,0 +1,50 @@
+import { validateDatabase } from './database.js';
+import { DIMENSIONS } from './types.js';
+export function defaultWeights() {
+    const weights = new Float32Array(DIMENSIONS).fill(1);
+    weights.fill(3, 15);
+    return weights;
+}
+export class PoseSearch {
+    database;
+    normalized = new Float32Array(DIMENSIONS);
+    weights;
+    constructor(database, weights = defaultWeights()) {
+        this.database = database;
+        validateDatabase(database);
+        if (weights.length !== DIMENSIONS || !weights.every(v => Number.isFinite(v) && v >= 0))
+            throw new Error('Invalid feature weights');
+        this.weights = weights.slice();
+    }
+    normalize(query) {
+        if (query.features.length !== DIMENSIONS || !query.features.every(Number.isFinite))
+            throw new Error('Invalid pose query');
+        const { mean, std } = this.database.manifest;
+        for (let j = 0; j < DIMENSIONS; j++)
+            this.normalized[j] = (query.features[j] - mean[j]) / std[j];
+    }
+    cost(index) {
+        const { features } = this.database;
+        let sum = 0;
+        for (let j = 0; j < DIMENSIONS; j++)
+            sum += this.weights[j] * (this.normalized[j] - features[index * DIMENSIONS + j]) ** 2;
+        return sum;
+    }
+    search(query) {
+        this.normalize(query);
+        const { frames, clips } = this.database.manifest;
+        let index = -1, cost = Infinity;
+        for (let i = 0; i < frames.length; i++) {
+            if (query.excludedClips?.has(frames[i].clip))
+                continue;
+            if (query.gaits && !query.gaits.has(clips[frames[i].clip].gait))
+                continue;
+            const score = this.cost(i);
+            if (score < cost) {
+                index = i;
+                cost = score;
+            }
+        }
+        return index < 0 ? null : { ...frames[index], index, cost };
+    }
+}

package/dist/core/types.d.ts

@@ -0,0 +1,57 @@
+export declare const DIMENSIONS = 27;
+export declare const HORIZONS: readonly [0.2, 0.4, 0.6];
+export type Vec3 = readonly [number, number, number];
+export type Gait = 'idle' | 'walk' | 'run' | 'strafe' | 'turn' | 'stop';
+export interface Clip {
+    id: string;
+    file: string;
+    animation: string;
+    duration: number;
+    looping: boolean;
+    gait: Gait;
+    /** Explicit authoring velocity for in-place clips, never inferred root motion. */
+    nominalVelocity?: Vec3;
+    /** Hips is a measured pelvis proxy, not a dedicated animation root. */
+    motionSource?: 'nominal' | 'hips';
+}
+export interface Frame {
+    clip: number;
+    time: number;
+}
+export interface DatabaseManifest {
+    profileId?: string;
+    profileSignature?: string;
+    version: 1;
+    dimensions: 27;
+    sampleRate: number;
+    coordinates: 'meters-y-up-z-forward';
+    horizons: readonly number[];
+    clips: Clip[];
+    frames: Frame[];
+    mean: number[];
+    std: number[];
+}
+export interface Database {
+    manifest: DatabaseManifest;
+    features: Float32Array;
+}
+export interface Match extends Frame {
+    index: number;
+    cost: number;
+}
+export interface Query {
+    features: Float32Array;
+    gaits?: ReadonlySet<Gait>;
+    excludedClips?: ReadonlySet<number>;
+}
+export interface Pose {
+    leftPosition: Vec3;
+    rightPosition: Vec3;
+    leftVelocity: Vec3;
+    rightVelocity: Vec3;
+    rootVelocity: Vec3;
+}
+export interface TrajectoryPoint {
+    position: readonly [number, number];
+    facing: readonly [number, number];
+}

package/dist/core/types.js

@@ -0,0 +1,2 @@
+export const DIMENSIONS = 27;
+export const HORIZONS = [0.2, 0.4, 0.6];

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './core/types.js';
+export * from './core/features.js';
+export * from './core/database.js';
+export * from './core/search.js';
+export * from './core/controller.js';
+export * from './core/root-motion.js';
+export * from './core/profile.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from './core/types.js';
+export * from './core/features.js';
+export * from './core/database.js';
+export * from './core/search.js';
+export * from './core/controller.js';
+export * from './core/root-motion.js';
+export * from './core/profile.js';

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@pose_flow/babylon",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./babylon": {
+      "types": "./dist/babylon.d.ts",
+      "import": "./dist/babylon.js"
+    }
+  },
+  "scripts": {
+    "dev": "vite --host 127.0.0.1",
+    "build": "tsc -p tsconfig.build.json && vite build",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test tests/*.test.ts",
+    "bake": "tsx tools/bake.ts",
+    "validate:assets": "tsx tools/validate-assets.ts",
+    "benchmark": "tsx tools/benchmark.ts"
+  },
+  "peerDependencies": {
+    "@babylonjs/core": "^7.54.3"
+  },
+  "devDependencies": {
+    "@babylonjs/core": "7.54.3",
+    "@babylonjs/loaders": "7.54.3",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0"
+  }
+}