@pose_flow/babylon 0.1.0 → 0.3.0

package/README.md

@@ -1,105 +1,129 @@
-# Motion Match · Babylon.js
-
-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).
+# Motion Match · Babylon.js
+
+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 são definidos por perfis JSON v2, que referenciam schemas v1 e conjuntos de animações v1 separados, 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.
+
+O [roadmap revisado de Motion Matching + Pose Search](docs/ROADMAP.md) prioriza schemas configuráveis, preparação genérica de rigs/animações e conjuntos por contexto para chegar à versão estável. A Fase 1 está implementada: [schemas configuráveis e migração](docs/SCHEMAS.md). A Fase 2 está concluída no escopo documentado e inclui preparação GLB seletiva, recorte temporal, composição de loops medidos, hashes de assets, conferência de bind e CLI offline; retargeting automático continua futuro.
+
+Animação de combate também faz parte do escopo obrigatório planejado da 1.0.0 (etapa 4.1): seleção de ataques/combos, esquivas, defesa e reações, com entradas controladas, sequência temporal protegida, eventos de apresentação e camadas. Ainda não implementado; regras de combate permanecem no jogo/servidor. Motion warping é uma expansão posterior.
+
+Fase 3 em andamento: filtros por contexto, intervalos elegíveis, política de variantes de idle e roteamento de bancos. Exemplo local `?profile=/profiles/kaykit-context.json`, com dois subconjuntos e variantes no mesmo bake. Cobertura de olhar lateral/camadas permanece pendente; contrato em [PROFILES.md](docs/PROFILES.md) e [AI_USAGE.md](docs/AI_USAGE.md).
+
+Fase 4 em andamento: painel de candidatos/custos por canal/rejeições, trajetórias, gravação/replay de queries, máscaras disjuntas e inertialization opcional. Exemplo `?profile=/profiles/kaykit-transitions.json&debug=1`. Confirmar os limites e o aceite pendente em [task-14](task/task-14/task.md); gesto de tronco é somente prévia de apresentação, sem contratos de combate.
+
+O MMORPG será usado como consumidor de teste durante o desenvolvimento, em paralelo ao laboratório. Ajustes e problemas com prints, código, logs e erros são acompanhados em [task/summary.md](task/summary.md); veja o [modelo e instruções](task/README.md). A integração prática não precisa aguardar o término do roadmap.
+
+## Guias distribuídos com o pacote
+
+- [Tutorial para IA integrar a biblioteca](dist/AI_USAGE.md) — fonte em docs/AI_USAGE.md.
+- [Comandos de publicação](dist/PUBLISHING.md) — fonte em docs/PUBLISHING.md.
+
+O build copia os guias para dist/ e prepack executa o build antes de empacotar. Implementações e correções devem atualizar o tutorial na mesma alteração, conforme AGENTS.md.
+
+## 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 oferece Knight, Paladin, Barbarian e Knight com schema de mãos (33 dimensões). “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 bake -- --profile public/profiles/kaykit-hands.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 a biblioteca e os guias de integração/publicação, sem personagens. A publicação inicial 0.1.0 foi informada pelo mantenedor; os novos guias estarão disponíveis após a próxima publicação.
+
+## Implementado
+
+- Núcleo sem engine: schemas configuráveis de características (preset original de 27 dimensões e exemplo de 33), 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 configuráveis (preset: 0,2 / 0,4 / 0,6 s).
+- Adaptador Babylon.js 9.32.1: 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.
+- Quatro bancos separados: **Knight com mãos, 174 poses / 6 clipes / 33 dimensões**; **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.
+
+Banco/perfil agora são v2. decodeDatabase rejeita banco v1; usar migração explícita ou novo bake conforme [SCHEMAS.md](docs/SCHEMAS.md). API local ainda sem publicação; conferir os tipos e o guia da versão instalada.
+
+## Features e coordenadas
+
+A tabela abaixo descreve somente o preset original `LOCOMOTION_SCHEMA`. Para outros schemas, usar os offsets de `compileSchema`.
+
+| Í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 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 deslocamento/heading variável que o player. Orientação constante é parte da pose; o conjunto usa rootOrientation com yaw ±90° para alinhar os strafes originalmente diagonais (±60°) ao deslocamento lateral. O laboratório testa esses clipes na velocidade nominal declarada de 3,2 m/s.
+
+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, SchemaQueryBuilder, predictTrajectory } from '@pose_flow/babylon';
+import { BabylonMotionPlayer, BabylonSchemaPoseReader } from '@pose_flow/babylon/babylon';
+
+// manifest e bytes são carregados uma vez; sem bake durante o jogo.
+const builder = new SchemaQueryBuilder(schema);
+const database = decodeDatabase(manifest, bytes, builder.layout.schema);
+const matcher = new MotionMatcher(database);
+// sources: Map<clip.id, AnimationGroup>; nodes: Map<nome original do osso, TransformNode>.
+// semanticNodes: Map<papel do schema, TransformNode>; schema carregado/validado offline.
+const player = new BabylonMotionPlayer(scene, manifest.clips, sources, nodes);
+const reader = new BabylonSchemaPoseReader(controllerRoot, semanticNodes, builder.layout.schema);
+
+// A cada frame, usando a pose medida após a renderização anterior:
+const future = predictTrajectory(trajectoryInput, builder.layout.horizons);
+const query = builder.build(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, motion warping, root-motion-driven movement, worker, KD-tree ou PCA. Inertialization é opt-in e não garante melhor qualidade ou pés travados. Starts e giros em movimento ainda não foram preparados. Os três clipes medidos do perfil Paladin legado são sem loop; há composição de ciclos de trajetórias medidas no núcleo/bake, com caminhada medida do Paladin preparada e conferida no laboratório. A busca linear é apropriada para medir esta base pequena; não há garantia de orçamento em bancos grandes ou com muitos jogadores.
+
+Schemas JSON configuráveis não incluem editor visual nem histórico temporal de ossos. 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 9.32.1.
+- [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).