HyperFrames Three.js集成实战：3D场景接入视频合成的完整步骤

HyperFrames Three.js集成实战：3D场景接入视频合成的完整步骤

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes

HyperFrames 是一个开源的「写 HTML、渲染视频」框架（Write HTML. Render video），它能把 HTML、CSS 和可寻址（seekable）动画确定性地渲染为 MP4 视频。本文将带你完成HyperFrames + Three.js 集成的完整步骤：为什么 3D 场景必须交给 Three.js、帧适配器（Frame Adapter）如何驱动 3D 场景逐帧渲染，以及如何把 3D 合成最终输出为视频。

为什么 3D 场景要交给 Three.js？

很多新手会先用 CSSperspective做"伪 3D"。但官方文档明确建议：真正的深度、光照和相机运动，一律用 Three.js 走帧适配器。原因在于 CSS 的 3D 变换只是把平面做透视变形——没有光源、没有相机，一旦需要阴影或视差，画面瞬间就显得扁平。

官方在 docs/prompting/runtimes-and-3d.mdx 中给出的经验法则：

✅build the isometric scene in Three.js via the adapter, with real depth and lighting❌isometric cards floating in CSS 3D with perspective

核心原理：帧适配器逐帧驱动 3D 场景

HyperFrames 渲染视频时从不"播放"动画，而是逐帧询问渲染器："第 N 帧屏幕应该长什么样？"——这套契约叫 frame adapter。

Three.js 是一方（first-party）seek-safe 运行时：适配器把 HyperFrames 的时间发布为window.__hfThreeTime，并在每次 seek 时分发hf-seek事件，3D 场景因此像其他素材一样帧精确地渲染。核心逻辑就在 packages/core/src/runtime/adapters/three.ts：

Renderer → 适配器: seekFrame(90) 适配器 → Three.js: 跳转到 3.0s 并稳定 Renderer → 捕获像素 → 编码

关键写法：Three.js 示例应暴露render(progress)适配器，而不是自由运行的requestAnimationFrame循环（参见 docs/catalog/components/three-orbiting-cards.mdx 中的注释）。

完整接入步骤

第 1 步：安装 Three.js 依赖库

在项目 HTML 头部通过<script>引入 Three.js（库由合成在运行时加载，不会被打包进框架）：

<script src="https://cdn.jsdelivr.net/npm/three@0.147.0/build/three.min.js"></script> <script src="https://cdn.jsdelivr.net/npm/three@0.147.0/examples/js/loaders/GLTFLoader.js"></script>

以上正是官方案例 vfx-iphone-device 的标准引入方式（源码片段）。加载 3D 模型时同理按需引入DRACOLoader。

第 2 步：创建场景、相机与光照

按照常规 Three.js 流程搭建Scene、PerspectiveCamera、WebGLRenderer和灯光即可。官方推荐的描述方式是"一个关键光 + 柔和补光"，例如把产品模型放在旋转台上缓慢旋转。

第 3 步：让场景响应 HyperFrames 时间

不要自己跑requestAnimationFrame循环，而是订阅适配器的 seek 机制：

// 监听 HyperFrames 的 seek 事件，按帧重绘 3D 场景 window.addEventListener('hf-seek', function () { const t = window.__hfThreeTime; // 当前时间（秒） renderer.render(scene, camera); });

也可以像three-orbiting-cards组件那样，用一个暂停的 GSAP timeline驱动 Three.js 场景——GSAP 负责时间线，Three.js 负责每帧绘制，两者组合后依然确定性渲染。

第 4 步：检查并渲染输出

npx hyperframes lint npx hyperframes check npx hyperframes render --output three-scene.mp4

渲染引擎会逐帧 seek 你的 3D 场景并捕获像素，同一帧永远得到同一画面。

进阶：HTML in Canvas——把 DOM 嵌进 3D 空间

如果你想在 3D 设备模型（如 iPhone）的屏幕上显示活的 HTML 界面，可以使用 HTML in Canvas 技术：借助 Chrome 实验性drawElementImage()API 把渲染后的 DOM 复制进 canvas，再作为纹理喂给 Three.js：

var texture = new THREE.CanvasTexture(captureCanvas); var material = new THREE.MeshBasicMaterial({ map: texture });

（完整模式见 docs/guides/html-in-canvas.mdx。）最快的上手路径是直接安装现成的 Catalog block：

npx hyperframes add vfx-iphone-device

该 block 包含真实 GLTF 设备模型 + 实时 HTML 屏幕内容 + 360° 转台运镜，并自带能力检测与降级逻辑。

确定性渲染注意事项

所有运行时都遵守同一套确定性契约：

• 🚫不要在渲染时拉取实时数据（如实时价格、天气）——渲染必须可复现
• 🚫不要使用未播种的随机数（每帧都会不同，破坏可复现性）；说seeded（已播种）随机，布局就会跨帧稳定
• ✅ 视频需要"知道"的一切，必须在渲染开始前烘焙进 HTML 或作为变量传入

常见问题

Q：小动效也要用 Three.js 吗？不用。淡入、滑入、计数器这类日常动效由默认 GSAP 适配器覆盖，无需指定运行时。Three.js 只用于真正的 3D、光照、相机场景。

Q：相机环绕、推近镜头怎么实现？CSS 没有相机可环绕，任何相机运动都属于 Three.js 的地盘：orbit the camera around the logo — Three.js via the adapter。

Q：相关源码和文档在哪里看？

掌握了「Three.js + 帧适配器 + 确定性渲染」这套组合，你就可以把任意 3D 场景接进 HyperFrames 的视频合成流水线，并得到逐帧精确、可复现的 MP4 输出。

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes