Three.js para HyperFrames
O HyperFrames suporta Three.js através do seu adaptador de runtime three. O adaptador não é dono da sua cena. Ele publica o tempo do HyperFrames e despacha um evento de seek para que sua composição renderize o quadro exato.
Contrato
- Crie a cena, câmera, renderizador, materiais e assets de forma síncrona quando possível.
- Renderize a partir do tempo do HyperFrames, não do tempo de parede.
- Escute o evento
hf-seeke renderize exatamente naquele tempo. - Carregue modelos, texturas e HDRIs antes da renderização crítica. Não os busque no momento do seek.
- Evite
requestAnimationFrameourenderer.setAnimationLoopcomo fonte de verdade para movimentos críticos de renderização.
O adaptador define window.__hfThreeTime e despacha new CustomEvent("hf-seek", { detail: { time } }) em cada seek.
Padrão Básico
<canvas id="three-layer"></canvas>
<script type="module">
import * as THREE from "https://cdn.jsdelivr.net/npm/[email protected]/+esm";
const canvas = document.getElementById("three-layer");
const renderer = new THREE.WebGLRenderer({ canvas, alpha: true, antialias: true });
// Ajuste para o tamanho do quadro da sua composição.
renderer.setSize(1920, 1080, false);
renderer.setPixelRatio(1);
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(35, 1920 / 1080, 0.1, 100);
camera.position.set(0, 0, 6);
const mesh = new THREE.Mesh(
new THREE.IcosahedronGeometry(1.4, 4),
new THREE.MeshStandardMaterial({ color: 0x64d2ff, roughness: 0.38 }),
);
scene.add(mesh);
scene.add(new THREE.HemisphereLight(0xffffff, 0x223344, 2));
function renderAt(time) {
mesh.rotation.y = time * 0.7;
mesh.rotation.x = Math.sin(time * 0.6) * 0.16;
renderer.render(scene, camera);
}
window.addEventListener("hf-seek", (event) => {
renderAt(event.detail.time);
});
renderAt(window.__hfThreeTime || 0);
</script>
#three-layer {
width: 100%;
height: 100%;
display: block;
}
Padrão AnimationMixer
Para clips de animação GLTF ou autorais, busque o mixer diretamente:
function renderAt(time) {
mixer.setTime(time);
renderer.render(scene, camera);
}
Se houver vários mixers, busque todos a partir do mesmo time.
Bons Usos
- Objetos 3D determinísticos, rotações de produto, partículas com dados semeados e placas de shader.
- Movimentos de câmera derivados de
time. - Clipes de animação GLTF quando os assets são locais e carregados antes da validação.
Evite
- Usar
Date.now(),performance.now()ou deltas de clock para atualizar o estado da cena. - Deixar trabalho crítico de renderização dentro de um loop de animação contínuo.
- Carregar modelos ou texturas remotas no momento da renderização.
- Saída dependente de device-pixel-ratio. Fixe o tamanho do renderizador e o pixel ratio para renderizações de vídeo.
- Passos de pós-processamento que dependem do histórico de quadros anteriores, a menos que você possa reconstruir o estado a partir do tempo.
Validação
Após editar uma composição Three.js:
npx hyperframes lint
npx hyperframes validate
Créditos e Referências
- Código fonte do adaptador HyperFrames:
packages/core/src/runtime/adapters/three.ts. - Documentação do Three.js
WebGLRenderer: https://threejs.org/docs/pages/WebGLRenderer.html - Documentação do Three.js
AnimationMixer.setTime(): https://threejs.org/docs/pages/AnimationMixer.html