mcpField
T
three

three

github.com/heygen-com创意与媒体74.7k69.6k 次安装今天更新
代码仓库

关于 three

面向 HyperFrames 的 Three.js 技能，用于按指定时间确定性地渲染场景。内容涵盖场景与动画混合器的时间定位、资源准备和验证。

主要功能

  1. 01按 HyperFrames 时间定位渲染
  2. 02处理 hf-seek 事件
  3. 03同步多个 AnimationMixer
  4. 04渲染前准备资源
  5. 05使用 HyperFrames 命令验证

适用场景

  1. 01渲染可复现的 3D 产品旋转
  2. 02制作基于时间的摄像机移动
  3. 03使用本地加载的 GLTF 动画片段

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/heygen-com/hyperframes --skill three

安装后在 Claude Code 中输入/three确认已加载。

详细介绍

HyperFrames 中的 Three.js

HyperFrames 通过其 three 运行时适配器支持 Three.js。该适配器不负责管理场景，而是发布 HyperFrames 时间并派发 seek 事件，以便你的合成内容能够渲染精确的帧。

约定

  • 尽可能同步创建场景、相机、渲染器、材质和资源。
  • 使用 HyperFrames 时间进行渲染，而不是墙上时钟时间。
  • 监听 hf-seek 事件，并精确渲染该时间点。
  • 在关键渲染寻帧之前加载模型、纹理和 HDRI。不要在寻帧时获取它们。
  • 避免将 requestAnimationFrame 或 renderer.setAnimationLoop 作为关键渲染动画的事实来源。

适配器会在每次寻帧时设置 window.__hfThreeTime，并派发 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 });
  // Match these to your composition's frame size.
  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 或自定义剪辑动画，直接寻帧混合器：

function renderAt(time) {
  mixer.setTime(time);
  renderer.render(scene, camera);
}

如果存在多个混合器，请使用同一 time 对它们全部进行寻帧。

适用场景

  • 确定性的 3D 对象、产品旋转、使用种子数据的粒子，以及着色器画面。
  • 根据 time 推导出的相机移动。
  • 在验证完成前已加载本地资源的 GLTF 动画剪辑。

避免

  • 使用 Date.now()、performance.now() 或时钟增量来更新场景状态。
  • 将关键渲染工作留在持续运行的动画循环中。
  • 在渲染时加载远程模型或纹理。
  • 依赖设备像素比的输出。对于视频渲染，请固定渲染器尺寸和像素比。
  • 使用依赖上一帧历史的后期处理通道，除非你能根据时间重建状态。

验证

编辑 Three.js 合成内容后：

npx hyperframes lint
npx hyperframes validate

致谢与参考资料

评论

支持 Markdown