@pose_flow/babylon

Biblioteca TypeScript/ESM de Motion Matching com Pose Search e adaptador Babylon.js. Seleciona clipe e tempo a partir da pose, velocidade e trajetória desejada.

Instalação

npm install @pose_flow/babylon @babylonjs/[email protected] @babylonjs/[email protected]

Mantenha Babylon core e loaders alinhados. A base validada é 9.32.1; o peer de core aceita ^9.32.1. Babylon 7/8 não são suportados por esta base.

Preparação dos dados

Prepare offline um perfil JSON v2, schema v1, conjunto de animações v1 e GLB compatíveis com o rig. Gere o banco v2 (manifest.json e poses.bin) antes de executar o jogo. Assets, perfis e bancos não acompanham o pacote.

A CLI instalada fornece os comandos de validação e bake:

npx --no-install pose-flow validate --profile public/profiles/hero.json
npx --no-install pose-flow bake --profile public/profiles/hero.json

Sirva os dados gerados na pasta pública da aplicação. Não reconstrua o banco ao carregar cada personagem. Consulte os formatos e o exemplo completo no guia de integração instalado.

Integração

O núcleo é independente da engine; o adaptador possui entrada separada:

import {
  decodeDatabase, MotionMatcher, SchemaQueryBuilder, predictTrajectory,
} from '@pose_flow/babylon';
import {
  BabylonMotionPlayer, BabylonSchemaPoseReader, BabylonSearchCoordinates,
} from '@pose_flow/babylon/babylon';

Fluxo de integração:

1. Carregue e valide o perfil, schema, conjunto de animações e banco uma vez.
2. Crie um matcher, player e leitor de pose por personagem, usando os mapas de ossos e fontes de animação do seu rig.
3. Construa a query com a pose visível e a trajetória desejada, usando os horizontes do schema.
4. Atualize matcher e player antes de renderizar; leia a pose após a avaliação das animações.
5. Resete o leitor e o matcher após teleporte; descarte os recursos ao remover o personagem.

Use metros e segundos, Y para cima e +Z para frente. No banco RH, yaw positivo gira +Z para +X. Para cenas LH, use BabylonSearchCoordinates na fronteira da busca, conforme o guia. Bake e player devem remover as mesmas trilhas de root.

O jogo controla posição, orientação, colisões e regras de combate. A reprodução é in-place; root motion alimenta a busca sem alterar a posição autoritativa. Velocidades nominais declaradas são parâmetros de autoria, não medidas.

Guia completo e API

Após instalar, abra:

• node_modules/@pose_flow/babylon/dist/AI_USAGE.md: formatos JSON, carregamento e exemplo completo TypeScript, coordenadas, ciclo de vida e opções de integração.
• node_modules/@pose_flow/babylon/dist/ACTIONS.md: seleção de ações autorizadas, janelas, eventos e integração com o relógio do jogo.

Em Node ESM, localize o guia sem importá-lo como JavaScript:

const guideUrl = import.meta.resolve('@pose_flow/babylon/AI_USAGE.md');

As declarações TypeScript acompanham as entradas públicas. Use os exports do pacote; os módulos internos de dist/offline não são API pública.

Laboratórios locais

No checkout, execute npm run dev. Abra /?coverage=1 para comparar locomoção, equipamento, orientação corporal e olhar em dois rigs e cenas RH/LH. A matriz R3 registra fontes, autoria, validação e limites. Os novos cenários têm trajetórias autoradas offline; não são capturas adicionais. Assets de demonstração mantêm as licenças registradas em ASSETS.md.

Limitações de integração

Não há retargeting automático entre rigs, motion warping ou garantia de eliminação de foot sliding. Inertialization, contatos offline e foot locking/IK são opcionais e exigem configuração e validação no seu personagem. O custo da busca depende do banco e da quantidade de personagens; meça no dispositivo alvo.

Licença

MIT para o código da biblioteca. Assets e dependências de terceiros mantêm suas próprias licenças.