Three.js para HyperFrames
HyperFrames admite Three.js a través de su adaptador de runtime three. El adaptador no posee tu escena. Publica el tiempo de HyperFrames y despacha un evento de búsqueda para que tu composición pueda renderizar el fotograma exacto.
Contrato
- Crea la escena, cámara, renderizador, materiales y recursos de forma síncrona cuando sea posible.
- Renderiza desde el tiempo de HyperFrames, no desde el tiempo de reloj.
- Escucha el evento
hf-seeky renderiza exactamente ese tiempo. - Carga modelos, texturas e HDRIs antes de la búsqueda crítica para el renderizado. No los obtengas en el momento de la búsqueda.
- Evita
requestAnimationFrameorenderer.setAnimationLoopcomo fuente de verdad para movimientos críticos de renderizado.
El adaptador establece window.__hfThreeTime y despacha new CustomEvent("hf-seek", { detail: { time } }) en cada búsqueda.
Patrón 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 });
// Ajusta estos valores al tamaño de fotograma de tu composición.
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;
}
Patrón AnimationMixer
Para animaciones con clips GLTF o creadas, busca directamente en el mixer:
function renderAt(time) {
mixer.setTime(time);
renderer.render(scene, camera);
}
Si hay varios mixers, busca en todos ellos desde el mismo time.
Buenos Usos
- Objetos 3D deterministas, giros de producto, partículas con datos semilla y placas de shaders.
- Movimientos de cámara derivados de
time. - Clips de animación GLTF cuando los recursos son locales y se cargan antes de que se complete la validación.
Evitar
- Usar
Date.now(),performance.now()o deltas de reloj para actualizar el estado de la escena. - Dejar trabajo crítico de renderizado dentro de un bucle de animación de ejecución libre.
- Cargar modelos o texturas remotos en tiempo de renderizado.
- Salida dependiente del device-pixel-ratio. Fija el tamaño del renderizador y el píxel ratio para renders de video.
- Pasos de post-procesamiento que dependan del historial de fotogramas anterior, a menos que puedas reconstruir el estado a partir del tiempo.
Validación
Después de editar una composición de Three.js:
npx hyperframes lint
npx hyperframes validate
Créditos y Referencias
- Código fuente del adaptador de HyperFrames:
packages/core/src/runtime/adapters/three.ts. - Documentación de
WebGLRendererde Three.js: https://threejs.org/docs/pages/WebGLRenderer.html - Documentación de
AnimationMixer.setTime()de Three.js: https://threejs.org/docs/pages/AnimationMixer.html