VectoJS Three
Use este skill para colocar uma interface VectoJS 2D ao vivo em uma textura Three.js e rotear a entrada do ponteiro 3D de volta para a cena VectoJS.
Fluxo de trabalho de integração
- Instale
@vectojs/core,@vectojs/three,threee@vectojs/uise estiver usando componentes de UI. - Crie um
ThreeAdapterpara cada textura de painel VectoJS. - Adicione entidades VectoJS a
adapter.vectoScenee, em seguida, inicie a cena interna. - Adicione
adapter.meshou a textura/material do adaptador à cena Three.js hospedeira. - No loop de ponteiro/roda do hospedeiro, faça raycasting contra a malha do adaptador e chame
adapter.updateIntersection(...). - Chame
adapter.dispose()ao remover o painel.
Leia references/three-recipes.md para trechos de código.
Restrições
- A saída padrão é um plano texturizado plano, não DOM renderizado em 3D.
- O teste de colisão lógico do VectoJS permanece 2D mesmo quando a malha é transformada no espaço do mundo.
- O aplicativo hospedeiro possui a câmera, o renderizador, os controles, a sessão XR, o raycaster e as regras de oclusão.
- Os UVs do raycast devem mapear para
width/heightlógicos do adaptador; não use o tamanho do backing-store para cálculos de layout. - A resolução da textura afeta a nitidez e o custo de upload. Escolha dimensões de acordo com a distância de visualização.
Erros comuns
| Erro | Correção |
|---|---|
| Adicionar um canvas offscreen do adaptador ao DOM | Adicione adapter.mesh ao Three.js; o canvas dá suporte à textura. |
Esquecer de chamar updateIntersection | Roteie eventos do raycaster do hospedeiro para o adaptador a cada evento de ponteiro/roda. |
| Despachar por coordenadas de tela | Use UVs do raycast por meio de ThreeAdapter. |
| Manter texturas descartadas ativas | Chame adapter.dispose() e remova referências do hospedeiro. |
| Esperar acessibilidade total do DOM dentro de XR | Trate o painel 3D como textura de canvas; forneça semânticas de nível de hospedeiro onde necessário. |
Peculiaridades de versão e backend (verificadas na fonte)
- three ≤ 0.1.3:
ThreeRenderer.flush()realizava uma renderização GL completa, e a Cena era liberada em torno de cada nó não agrupado — o custo por quadro crescia O(N²) no número de entidades. three 0.1.4 renderiza uma vez por quadro por meio do ganchopresent(); atualize antes de qualquer outra análise de desempenho. - Entrada nativa dentro de uma textura é limitada. O canvas do adaptador está
offscreen, portanto os elementos de acessibilidade projetados da Cena nunca são conectados ao
documento;
updateIntersectionrecai no despacho de eventos próprio do VectoJS. Botões/hover/roda funcionam; edição de texto nativa completa (IME) não — mantenha a entrada de texto fora do painel 3D ou aceite entrada simplificada. - A largura da linha
stroke()é efetivamente 1px na maioria das plataformas (LineBasicMaterial.linewidthé uma limitação conhecida do WebGL). Desenhe linhas grossas como formas preenchidas. ThreeRenderer.drawImagealoca uma textura por chamada por quadro (descartada emclear()); reutilize um canvas de origem quando possível.fillTexté armazenado em cache desde three 0.1.4 (LRU chaveado por fonte|cor|texto, 256 entradas) — em ≤ 0.1.3 tinha o mesmo custo por chamada, então prefiraMSDFTextEntitynessa versão.