Three 是 HyperFrames 生态中的 Three.js 与 WebGL 适配器模式技能,用于在 HyperFrames 中创建确定性的 Three.js 场景与 WebGL 画布图层。它的核心思路是:适配器不拥有你的场景,而是发布 HyperFrames 时间并派发 seek 事件,让合成能够渲染出精确的帧。
【用途】 适用于需要确定性渲染的 3D 内容,例如确定性 3D 物体、产品旋转、使用种子数据的粒子、着色器画面,以及由时间驱动的相机运动;在素材为本地、且能在校验完成前加载完毕时,也适用于 GLTF 动画片段。
【主要能力与约定】
- 尽量同步创建场景、相机、渲染器、材质与素材。
- 依据 HyperFrames 时间渲染,而不是墙钟时间。
- 监听 hf-seek 事件,并精确渲染该时间。
- 在关键的 seek 渲染之前加载模型、纹理与 HDRI,不要在 seek 时才去获取。
- 避免把 requestAnimationFrame 或 renderer.setAnimationLoop 作为关键运动的真实来源。
- 适配器会设置 window.__hfThreeTime,并在每次 seek 时派发 new CustomEvent("hf-seek", { detail: { time } })。
【使用方式】 文档给出基础模式:在页面中放置 canvas,通过 CDN 以 ES module 引入 Three.js(示例使用 https://cdn.jsdelivr.net/npm/three@0.181.2/+esm),创建 WebGLRenderer 并将尺寸与像素比固定为合成帧大小(示例为 1920x1080、pixelRatio 为 1),创建场景、相机与网格,然后在 renderAt(time) 中根据时间更新旋转并调用 renderer.render。通过 window.addEventListener("hf-seek", event => renderAt(event.detail.time)) 响应 seek,并在初始化时以 renderAt(window.__hfThreeTime || 0) 渲染首帧。对于 GLTF 或已制作的片段动画,可在 renderAt 中调用 mixer.setTime(time) 后渲染;若存在多个 mixer,则用同一时间对全部进行 seek。
【适用场景】 适合确定性 3D 对象、产品旋转、种子化粒子、着色器画面,以及由时间推导的相机运动;在素材本地且校验前完成加载的前提下,也适合 GLTF 动画片段。
【限制与应避免的做法】 不要使用 Date.now()、performance.now() 或时钟增量来更新场景状态;不要把关键渲染工作留在自由运行的动画循环里;不要在渲染时加载远程模型或纹理;不要产生依赖设备像素比的输出,视频渲染时应固定渲染器尺寸与像素比;对于依赖前一帧历史的后期处理通道,除非能够从时间重建状态,否则应避免。
【校验】 编辑 Three.js 合成后运行:npx hyperframes lint 和 npx hyperframes validate。
【参考资料】 适配器源码位于 packages/core/src/runtime/adapters/three.ts;Three.js WebGLRenderer 文档:https://threejs.org/docs/pages/WebGLRenderer.html;AnimationMixer.setTime() 文档:https://threejs.org/docs/pages/AnimationMixer.html。关于收费、价格与具体平台支持等信息,资料中暂未提供。