OpenMontage HyperFrames 动画规则实战：Orbit 3D Entry——从三维空间翻转入场到持续椭圆环绕

orbit-3d-entry 是 OpenMontage 仓库中 HyperFrames 动画技能库（.agents/skills/hyperframes-animation/rules/orbit-3d-entry.md）收录的一条原子级运动规则：让一组元素先以 rotateX + rotateY + translateZ 的三维姿态从空间深处翻转进场，再汇聚为围绕画面中心焦点不断旋转的椭圆轨道。它面向的典型场景是「中心主视觉/主标题 + 外围环绕图标」的视频构图——例如功能特性环绕 CTA、技术栈图标环绕品牌词、能力标签环绕 Logo 的产品开场与品牌展示镜头。

读完本文你可以掌握：规则背后的两阶段运行机制、可直接复制的完整 HTML/CSS/GSAP 实现、八大可调参数的取值区间与设计意图、两种常用变体（向心塌缩与轨道平面倾斜）、以及保证 HyperFrames 逐帧 seek 确定性的关键约束。仓库内的完整可运行示例位于 .agents/skills/hyperframes-animation/examples/cta-orbit-collapse.html，建议对照阅读。

规则定位：先了解 orbit-3d-entry 在技能库中的角色

在深入代码之前，先看清这条规则所处的知识结构。OpenMontage 将全部动画知识收敛进一个技能目录中（.agents/skills/hyperframes-animation/SKILL.md），按用途拆分为五类：

• rules（原子运动规则）：每个 .md 描述一种可独立使用的动作配方，orbit-3d-entry 属于此类，完整清单见 rules-index.md；
• blueprints（多阶段场景模板）：如 cta-orbit-collapse 等整场编排，见 blueprints-index.md；
• transitions（场景到场景的切换）；
• techniques 与 adapters（GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU 等七种运行时适配）。

按该技能的默认工作流，最省事的做法是：从 rules-index.md 里挑选 2～4 条原子规则，用一条暂停的 GSAP 时间线粘合到一起。orbit-3d-entry 正是可以被自由组合的原子配方之一，它与 center-outward-expansion.md（爆发式散开）互为两种相反的入场哲学：一个「从外围环绕飞入」，一个「从中心炸开」。

核心机制：一次入场 + 永不停止的轨道

规则的动画由每个元素各自的两个阶段构成：

1. 入场阶段（按元素执行）：GSAP tween 将元素从隐藏的三维姿态（负的 rotateX/rotateY 与负 z 深度）翻转回正对屏幕的平面状态（rotateX: 0, rotateY: 0, z: 0）。翻转使用带回弹过冲的 back.out 缓动，形成「卡片从空间深处弹出」的质感。
2. 轨道阶段（入场后持续）：元素位置由三角函数连续驱动——x = cos(t) · RADIUS_X、y = sin(t) · RADIUS_Y，以很慢的角速度绕中心旋转。

与一次性 reveal 动画的根本区别在于——轨道不会停，它构成画面持续存在的环境运动层，直到被后续场景阶段主动收掉。

最关键的工程决策是轨道跑在 GSAP 时间线内部，而不是用 requestAnimationFrame。HyperFrames 的渲染哲学是"单条暂停时间线 + 可寻址帧"（见 hyperframes-core 契约），所有运动必须能通过 tl.time() 精确回放；任何游离于时间线之外、自行 rAF 驱动的循环都会破坏逐帧 seek 的确定性。orbiting 代码里通过驱动一个 { p: 0 → 1 } 的假想状态对象实现，天然满足这一约束。

场景 HTML：以 data-* 契约声明的轨道舞台

轨道场景本身是一个标准的 HyperFrames clip 容器，根节点携带 data-composition-id、data-start、data-duration、data-track-index 四个时序属性，这与 hyperframes-core 的 composition 契约一致。轨道元素通过 data-angle 声明各自的初始相位角（度），多个角度平分 360°；中心标签是独立的 .orbit-center：

<div
  class="scene"
  id="orbit-scene"
  data-composition-id="orbit-scene"
  data-start="0"
  data-duration="5"
  data-track-index="0"
>
  <div class="orbit-stage">
    <div class="orbit-item" data-angle="0">{glyph1}</div>
    <div class="orbit-item" data-angle="60">{glyph2}</div>
    <div class="orbit-item" data-angle="120">{glyph3}</div>
    <div class="orbit-item" data-angle="180">{glyph4}</div>
    <div class="orbit-item" data-angle="240">{glyph5}</div>
    <div class="orbit-item" data-angle="300">{glyph6}</div>
    <div class="orbit-center">{centerLabel}</div>
  </div>
</div>

6 个轨道项以 60° 均分整圈——这是规则的推荐数量区间（4～12）里的典型编排。入场时按角度的先后顺序依次翻转，让元素在轨道起点位置原位现形。

关键 CSS：perspective 是 3D 翻转成立的前提

CSS 部分有两点被特别标注为 REQUIRED：

• 场景根 .scene 必须设置 perspective: 1800px。文档强调：没有 perspective，rotateX/rotateY 会被压平为 2D 缩放，翻转将失去空间纵深感。
• .orbit-stage 与每个 .orbit-item 都要 transform-style: preserve-3d——因为轨道项各自拥有独立 transform，必须显式保留 3D 上下文。

其余结构要点：轨道项使用 position: absolute; top: 50%; left: 50% 锚定在舞台中心，实际位移完全交给 GSAP 的 translate（translate(-50%, -50%) 负责自身居中）；轨道项是圆形 border-radius: 50% 的强调色图标，配深投影营造悬浮感；中心标签通过 z-index: 5 提到上层。

.scene {
  position: relative;
  width: 100%;
  height: 100%;
  display: grid;
  place-items: center;
  background: {sceneBackground};
  perspective: 1800px; /* REQUIRED — without perspective, rotateX/Y flatten */
}
.orbit-stage {
  position: relative;
  width: 1000px;
  height: 700px;
  display: grid;
  place-items: center;
  transform-style: preserve-3d;
}
.orbit-item {
  position: absolute;
  /* Items live at stage center; GSAP translates them along the orbit. */
  top: 50%;
  left: 50%;
  width: 140px;
  height: 140px;
  display: grid;
  place-items: center;
  background: {accentColor};
  border-radius: 50%;
  font-family: {font};
  font-weight: 900;
  font-size: 64px;
  color: {itemTextColor};
  transform-style: preserve-3d;
  will-change: transform;
  box-shadow: 0 12px 36px {accentShadowColor};
}
.orbit-center {
  position: relative;
  z-index: 5;
  font-family: {font};
  font-weight: 900;
  font-size: 96px;
  letter-spacing: 8px;
  color: {centerTextColor};
  text-transform: uppercase;
}

注意 CSS 中使用了 {sceneBackground}、{accentColor}、{centerTextColor} 等占位符——这是 HyperFrames 规则文档的统一记号：具体取色交给 hyperframes-creative（调色板/排版方向）在创作阶段落实。

GSAP 时间线：一次 tween 同时管好翻转与轨道

JS 骨架完整如下。加载 GSAP 后，把时间线注册进 window.__timelines（key 必须等于根节点 data-composition-id），并保持 paused: true——这是 HyperFrames 渲染器按帧 seek 的前提。

<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
<script>
  window.__timelines = window.__timelines || {};
  const tl = gsap.timeline({ paused: true });

  const items = document.querySelectorAll(".orbit-item");
  // RADIUS_X, RADIUS_Y, ORBIT_DURATION, ENTRY_DUR, STAGGER, FLIP_BACK, CENTER_BACK
  // — all named constants; values per "How to Choose Values" below.
  const RADIUS_Y = RADIUS_X * Y_TO_X_RATIO; // perspective-flattened ellipse

  items.forEach((el, i) => {
    const initialAngleDeg = Number(el.dataset.angle);
    const initialAngleRad = (initialAngleDeg / 360) * Math.PI * 2;
    const startX = Math.cos(initialAngleRad) * RADIUS_X;
    const startY = Math.sin(initialAngleRad) * RADIUS_Y;

    // 1) Place at orbital position with opacity 0 — BEFORE any tween fires
    gsap.set(el, {
      xPercent: -50,
      yPercent: -50,
      x: startX,
      y: startY,
      rotateX: ROTATE_X_FROM,
      rotateY: ROTATE_Y_FROM,
      z: Z_FROM,
      opacity: 0,
      scale: SCALE_FROM,
    });

    // 2) Phase 1 — flip in IN PLACE at orbital position
    tl.to(
      el,
      {
        rotateX: 0,
        rotateY: 0,
        z: 0,
        opacity: 1,
        scale: 1,
        duration: ENTRY_DUR,
        ease: `back.out(${FLIP_BACK})`,
      },
      i * STAGGER,
    );

    // 3) Phase 2 — continuous orbit driven via a 0→1 progress tween
    const orbitState = { p: 0 };
    tl.to(
      orbitState,
      {
        p: 1,
        duration: ORBIT_DURATION,
        ease: "none",
        onUpdate: () => {
          const angle = initialAngleRad + orbitState.p * Math.PI * 2;
          const x = Math.cos(angle) * RADIUS_X;
          const y = Math.sin(angle) * RADIUS_Y;
          // z-index by orbit Y — see "Center label clearance" in Key Principles
          // for the capped-range form when a center label is present.
          el.style.zIndex = String(Math.round(y + RADIUS_Y));
          el.style.transform = `translate(-50%, -50%) translate(${x}px, ${y}px)`;
        },
      },
      i * STAGGER + ENTRY_DUR,
    );
  });

  // Center label fades in once a few orbit items have landed
  tl.from(
    ".orbit-center",
    { opacity: 0, scale: 0.6, duration: ENTRY_DUR, ease: `back.out(${CENTER_BACK})` },
    CENTER_FADE_AT,
  );

  window.__timelines["orbit-scene"] = tl;
</script>

代码里暗含三个值得展开的工程细节：

1. 入场前先 gsap.set 摆放到位：元素先被放置到各自的轨道起点 (cos(θ)·RADIUS_X, sin(θ)·RADIUS_Y) 并置 opacity: 0，然后才添加 tween。这样第一阶段只翻转旋转/透明度/缩放，不碰位移；元素在轨道起点上原位淡入，第二阶段才能无跳变地接上轨道。若反过来先做「从中心飞入再跳上轨道」的 fromTo，元素会在第一阶段撞上中心标签，并在阶段切换瞬间发生肉眼可见的瞬移——这是该规则在 [Critical Constraints](#关键约束：保证 seek 确定性) 里标红强调的坑。
2. 逐元素独立的轨道 tween：每个元素从自己的 data-angle 起算相位，因此各自的相位推进互不相同；绝不能用一个 targets: '.orbit-item' 的共享 tween，否则所有元素会在同一角度上同步转圈，轨道塌缩成单点。
3. 伪状态对象驱动轨道：orbitState.p 从 0 匀速推进到 1，onUpdate 里以 initialAngleRad + p·2π 解出当前角度再写 transform。ease: "none" 保证角度与时间严格线性对应，这正是逐帧确定性所依赖的。z-index 依据元素当前 Y 坐标动态生成，保证轨道下半圈的元素画在"前面"、上半圈的元素画在"后面"，形成立体绕行感。

参数速查：八大常量的区间、观感与约束

规则为所有可调参数给出了明确的取值区间、视觉影响、硬约束与仓库参考值。表格化速查如下：

参数	含义	建议区间	视觉影响	关键约束	参考实现取值
RADIUS_X	轨道椭圆水平半径（px）	300–900	小→紧密簇；大→圆环铺开、给中心留白	需满足 `RADIUS_X · min(	cos(θ)
Y_TO_X_RATIO	RADIUS_Y / RADIUS_X，透视压扁系数	0.4–0.7	低→俯视的扁盘；接近 1→正对镜头的平面	必须 < 1，保持"倾斜圆环"而非"正面光环"	≈ 0.58（280/480）
ORBIT_DURATION	一整圈耗时（s）	4–25	短→狂躁；长→漂移/宁静	≥ 轨道可见时长，否则 tween 结束元素停转	≈ 25（0.25 rad/s）
ENTRY_DUR	单元素翻转时长（s）	0.4–0.8	短→干脆；长→庄重	≤ 首末元素入场间隔，避免级联糊成一团	0.55
STAGGER	相邻元素入场延迟（s）	0.06–0.12	低于 0.06→"爆米花式"齐响；高于 0.12→拖沓	总级联 (n-1)·STAGGER 需在下一场景阶段开始前完成	0.10
FLIP_BACK	back.out(<n>) 翻转过冲量	1.2–2.0	低→柔和到位；高→明显回弹	与中心标签的 CENTER_BACK 相邻触发时须搭配平和值，双过冲互相抵消	1.4
CENTER_BACK	中心标签 back.out(<n>) 过冲量	1.2–1.8	低→安静；高→弹跳感	—	1.4
ROTATE_X/Y_FROM、Z_FROM、SCALE_FROM	入场前 3D 初始姿态	rotateX ±60°~±120°；rotateY ±45°~±120°；z −200~−400；scale 0.2–0.6	旋转角越大 + z 越深 →"从纵深翻出"越戏剧化	方向须与场景透视一致；元素间混用正负 rotateY 会显得杂乱	rotateX 90、rotateY −45、z −100、scale 0

还有两个文档未进表格但实际存在的节奏参数：

• CENTER_FADE_AT：中心标签淡入的时刻，建议落在前 2～4 个轨道元素落地之后——过早会与入场级联抢注意力，过晚会留下一个空洞的中心；
• RADIUS_Y 通常不作为独立输入，而由 RADIUS_X × Y_TO_X_RATIO 推导（如上面的 const RADIUS_Y = RADIUS_X * Y_TO_X_RATIO;），保证压扁比例始终受控。

参考列取自仓库内真实示例 cta-orbit-collapse.html：它以 RADIUS_X = 480、RADIUS_Y = 280、角速度 0.25 rad/s（≈ 25 s/圈）、单图标入场 0.55 s + back.out(1.4)、入场级联步长 0.10 s 的参数组合运行，是验证上述取值建议的直接落地样本。

两种变体：向心塌缩与倾斜轨道平面

变体一：塌缩到中心（collapse to center）

规则的收尾哲学是"让轨道有一个结局"。反向操作——先公转、再向心聚拢——通过引入一个 1 → 0 的半径驱动因子实现，它同时作用于 RADIUS_X 与 RADIUS_Y，使所有元素沿各自当前角度螺旋收向中心：

const collapse = { r: 1 };
tl.to(
  collapse,
  {
    r: 0,
    duration: COLLAPSE_DUR,
    ease: "power3.inOut",
    onUpdate: () =>
      items.forEach((el) => {
        const a = (Number(el.dataset.angle) / 360) * Math.PI * 2;
        const x = Math.cos(a) * RADIUS_X * collapse.r;
        const y = Math.sin(a) * RADIUS_Y * collapse.r;
        el.style.transform = `translate(-50%,-50%) translate(${x}px,${y}px) scale(${collapse.r})`;
      }),
  },
  COLLAPSE_AT,
);

power3.inOut 让收拢先慢后快再缓停；同步缩小 scale 让元素在触底时自然"融化"。这正是 cta-orbit-collapse 示例里「六枚技术图标在点击后向心聚拢、一张演示卡从汇聚点弹出」的后半程逻辑——它的塌缩驱动用 back.out(1.6) 缓动配合 0.85 s 时长、半径因子 1 − collapseEased 计算，示例源码 的第 1024 行起即为这一段"轨道 + 塌缩主引擎"。

塌缩变体与 center-outward-expansion.md 存在天然互补：后者本身就是"中心爆发"，两者共享"半径驱动 + 一次性到位"的数学结构，文档将其描述为"orbit-collapse 收尾的逆向驱动源"。

变体二：倾斜轨道平面

要让公转更具立体感，可对整块 .orbit-stage 施加 X 轴旋转，使轨道平面倾斜：

.orbit-stage {
  transform: rotateX(25deg);
}

平面倾斜后，位于"赤道"上下的元素会在穿越视平面时呈现出明显的弧线纵深轨迹，视觉上从"平面绕圈"升级为"空间环绕"。

关键原理：四个不能省的设计决策

规则把经验法则提炼为四条核心原则：

1. perspective 必须落在场景根节点——否则 rotateX/rotateY 退化成 2D 缩放，翻转毫无深度；与此同时 .orbit-stage 与每个 .orbit-item 都要 preserve-3d，元素拥有自身 transform 时 3D 上下文才能延续。
2. 级联入场优于齐射入场——按 STAGGER 依次翻转，视觉语义是"蜂群集结成形"；若所有元素同时进场则变成"爆米花"，丧失编排感。
3. 元素数量控制在 4–12——太少显得空荡，太多会挤压中心区域形成视觉拥堵。
4. 中心标签必须与轨道元素三维上分层（Clearance 规则）——在 preserve-3d 舞台内部，单纯的 z-index 并不可靠：绘制顺序遵循 Z 位置而非层叠上下文。文档给出三层递进的保护方案：
   • 把中心标签用 transform: translateZ(220px) 推到最前，并辅以 z-index: 9999；
   • 轨道元素的动态 z-index 限制在 [1, 50] 的有界区间——让轨道下半圈元素依然能盖住上半圈元素（保证环绕层次），但永远不可能盖过中心标签。区间映射公式为 1 + round((y + RADIUS_Y) / (2·RADIUS_Y) · 49)，把 y ∈ [-RADIUS_Y, +RADIUS_Y] 线性映射到 [1, 50]；
   • 同时用几何法保证水平方向也绝不重叠：若中心标签半宽为 L_w、轨道元素半宽为 I_w，则 RADIUS_X · min(|cos(θ)|) ≥ L_w + I_w + breathing_room。以 60° 等分、6 元素轨道为例，元素间最坏相位出现在 30°，cos(30°) ≈ 0.866——中心文字越宽，环半径就必须越大。

此外还有一条构图铁律：轨道是装饰，中心才是主角。如果观众的视线被环绕元素抢走，应当加大中心元素的尺寸或降低轨道元素的明度，让环绕收敛为背景层。

关键约束：保证 seek 确定性的硬性红线

• 禁用 requestAnimationFrame——轨道必须活在时间线内，否则 HyperFrames 逐帧 seek 会失去确定性。本文方案用「伪状态对象 p 的线性 tween + onUpdate」规避。
• 时间线必须暂停创建：gsap.timeline({ paused: true })。
• 注册表 key = data-composition-id：window.__timelines["orbit-scene"] 与根节点 ID 严格一致（hyperframes-core 契约 规定 key 不允许带 -mount/-slot 之类后缀）。
• 每个轨道元素拥有独立的轨道 tween——共享 targets 会让相位归零。
• will-change: transform——大量并发的轨道位移需要合成器提示避免掉帧。
• 不要动画 left/top——用 translate()，且与自身的 translate(-50%, -50%) 居中变换叠加书写。
• 入场必须"原位翻转"而非"中心翻转"——先 gsap.set 摆到轨道起点并 opacity: 0，再让第一阶段只动旋转/透明度/缩放。文档用 ❗ 标注：若 fromTo 的 from/to 都含 x:0,y:0，元素第一阶段会被钉在舞台中心与标签叠撞，并在第二阶段开始时肉眼瞬移。

在更大场景中组合：三条规则搭配参考

单条原子规则通常不足以撑起一个完整镜头，文档给出三组经过验证的搭配方向：

• center-outward-expansion.md——爆发式入场替代轨道式入场；同时是 orbit-collapse 收尾阶段的逆向驱动源，两条规则可构成"展开 + 收拢"的循环镜头；
• cursor-click-ripple.md——当中心元素是一个等待用户"点击"的 CTA 时，光标飞入 + 点击涟漪与塌缩收尾天然配对。cta-orbit-collapse 示例即演示了该组合：光标滑到白底按钮、按下（按钮与光标同步压缩 0.85/0.95）、涟漪扩散、图标塌缩、演示卡弹出；
• sine-wave-loop.md——给轨道上的每个元素叠一层细微的正弦浮动/微摆（±6 px 位移、±2.5° 旋转），避免公转过于机械。示例中的抖动按元素索引错开相位，且随塌缩过程衰减。

与 HyperFrames 配套技能的衔接

编写完 HTML/CSS/GSAP 后，规则建议按以下技能分工收尾验证：

• /hyperframes-animation——时间线编排与 onUpdate API 的知识源（即本规则所在技能，总纲见 .agents/skills/hyperframes-animation/SKILL.md）；
• /hyperframes-core——composition 装配契约：根节点须为有确定尺寸的盒子、每条动画只允许操作视觉属性白名单、禁 display/visibility、禁 repeat: -1 等不可谈判规则，详见 .agents/skills/hyperframes-core/SKILL.md；
• /hyperframes-cli——用 npx hyperframes lint 做静态体检、npx hyperframes validate/inspect 跑渲染期校验、npx hyperframes preview 在时间线编辑器里人工复检、最后 npx hyperframes render 出片（命令用法记录于 .agents/skills/hyperframes-cli/SKILL.md）。

仓库内的真实对照：cta-orbit-collapse 示例解析

若想看到这条规则在完整镜头里的形态，.agents/skills/hyperframes-animation/examples/cta-orbit-collapse.html 是最直接的参照物。它把六种 HyperFrames 能力（HTML/CSS/SVG/GSAP/3D/LOTTIE）作为六枚图标，以 2π/6 均分整圈环绕中央 "Drop an HTML scene · Render" CTA，整体 6.5 秒编排为五个阶段：

• 0.00–1.05 s 六枚图标以 0.10 s 级联 + back.out(1.4) 翻转入场（各 0.55 s），轮廓同步做 stroke-draw、内部点缀延迟 0.30 s 错峰淡入；
• 0.00–2.95 s 持续公转（0.25 rad/s），每个图标叠 ±6 px 位移、±2.5° 旋转的错相位摆动；
• 1.50–2.20 s 光标从屏幕右侧飞入落点 CTA 按钮（back.out(1.3) 过冲着陆）；
• 2.20–2.46 s 点击：光标与按钮压缩回弹、按钮辉光脉冲、涟漪 0.3→5.0 扩散；
• 2.20–3.05 s 图标按 back.out(1.6) 向心塌缩（半径因子 1→0、scale 1→0.5、透明度分段包络）；
• 2.95 s 起 演示卡从塌缩点弹出并进入有限次 yoyo 悬浮呼吸，直至 6.5 s 场景结束。

这个文件是值得通读的"参考答案"：注意它的图标 DOM 采用三层嵌套（.icon-pos 承担轨道位、.icon-collapse 承担塌缩缩放/透明度、.icon-entry 承担 3D 翻转入场），把「轨道位移、塌缩状态、翻转姿态」三组运动解耦到三个层上，再由不同 tween 分别驱动——这是把本规则从"单层原型"升级到"生产级整场编排"时的典型结构演进。

写在最后

orbit-3d-entry 的可贵之处在于它把「看起来自由散漫的环绕运动」收敛进了一条完全可预测、可 seek 的时间线：两阶段结构让入场富有戏剧张力，三角函数轨道让公转数学上可精确重放，onUpdate 内的伪状态对象则把「无限循环」这种天然违背确定性契约的动画，改写为受时间线控制的有限推进。在 OpenMontage 这类以 HTML 场景渲染视频的体系里，这正是原子规则应该有的样子——一个可复制、可调参、可组合、不破坏渲染契约的运动单元。下次需要为中心主视觉做「元素环绕」镜头时，直接以本文的 HTML/CSS/时间线为起点，再按上表的参数区间试镜即可。