Three.js for HyperFrames
HyperFrames 透過其 three 執行階段適配器支援 Three.js。此適配器不會擁有你的場景,而是發布 HyperFrames 的時間並觸發 seek 事件,讓你的合成能渲染出確切影格。
合約
- 盡可能在同步狀態下建立場景、相機、渲染器、材質與素材。
- 使用 HyperFrames 的時間進行渲染,而非真實時間。
- 監聽
hf-seek事件並在該時間點渲染。 - 在關鍵 seek 發生前載入模型、紋理和 HDRIs,避免在 seek 時才擷取。
- 避免使用
requestAnimationFrame或renderer.setAnimationLoop作為渲染關鍵運動的基準。
此適配器會設定 window.__hfThreeTime 並在每次 seek 時觸發 new CustomEvent("hf-seek", { detail: { time } })。
基本模式
<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 });
// 將這些數值設為與合成影格尺寸一致。
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;
}
AnimationMixer 模式
對於 GLTF 或創建的動畫片段,可直接 seek mixer:
function renderAt(time) {
mixer.setTime(time);
renderer.render(scene, camera);
}
若有多個 mixer,請從相同的 time 對它們全部進行 seek。
適合用途
- 確定性 3D 物件、產品旋轉、使用種子資料的粒子效果、著色器面板。
- 由
time驅動的攝影機運動。 - 當素材為本機且於驗證完成前載入完成的 GLTF 動畫片段。
避免事項
- 使用
Date.now()、performance.now()或時脈增量來更新場景狀態。 - 將渲染關鍵工作留在自由執行的動畫迴圈中。
- 在渲染時遠端載入模型或紋理。
- 依賴裝置像素比例的輸出。為影片渲染固定渲染器尺寸與像素比例。
- 依賴前一個影格歷史的後處理流程,除非你能從時間重建狀態。
驗證
編輯 Three.js 合成後執行:
npx hyperframes lint
npx hyperframes validate
參考資料
- HyperFrames 適配器原始碼:
packages/core/src/runtime/adapters/three.ts。 - Three.js
WebGLRenderer文件:https://threejs.org/docs/pages/WebGLRenderer.html - Three.js
AnimationMixer.setTime()文件:https://threejs.org/docs/pages/AnimationMixer.html