HyperFrames Waterfall Entry 动画规则：如何编排自下而上的交错入场级联

导读

waterfall-entry 是 HyperFrames 动画技能库（skills/hyperframes-animation/rules/waterfall-entry.md）中的一条原子级"入场"运动规则：让单词、短语或元素从同一方向（下方）甩入画面，并且每个元素都在前一个元素尚未完全落定之前就开始运动，从而形成一道不断加速的"瀑布式"级联，最终收束为一个完整、清晰的排版构图。它专用于标题卡（title card）、段落开场（segment opener）以及列表/特性简介（list/feature intro）等场景。读完本文，你将掌握：入场与场景切换（seam）的边界划分、按元素重量分配位移与时长的编排表、基于单个暂停 GSAP 时间轴（paused timeline）的落点计算公式，以及必须避开的反模式（anti-patterns）。

本文基于仓库中该规则文档展开，并结合 rules-index.md、SKILL.md 与同目录兄弟规则（如 nudge-curve.md）做源码级印证，帮助你写出**可被 HyperFrames 引擎确定性回放（seek-safe、deterministic）**的入场动画。

一、这是什么：一种"在场入场"，而不是一个"接缝"

waterfall-entry 的核心定位（front matter description）是：

Staggered ARRIVAL cascade — words/elements whip in from below (one consistent direction), each starting before the previous settles, an accelerating wave that resolves into a composed layout.

翻译过来即：交错的"到达"级联——词/元素从下方甩入（方向全程一致），每个元素在前一个元素落定之前就已开始，形成一道加速的波浪，最终收束为已经排版好的构图。

规则文档明确强调：This is an in-scene arrival, not a seam. 也就是说，瀑布入场是"场景内部"的动画，负责把文字"带进来"；而真正负责"场景到场景"切换的接缝动画由同门的 waterfall CUT（cut-the-curve 教学技能中的 seams/waterfall-cut.md）负责。两者的规则严禁混用，规则文档用一张对照表划清了边界：

维度	Entry（本规则 — 到达）	Waterfall Cut（接缝）
不透明度	入场时经 tl.set 做二进制 0→1，永不淡入淡出	在中途 0.35 处点燃——淡出/淡入本身就是速度技巧
默认轴向	Y 轴，自下而上	X 轴，顺着当前水流方向
出场侧	无	词以镜像的 power4.in 淡出

这一区分的工程意义在于：HyperFrames 的渲染管线以"单个暂停时间轴 + 可双向 seek"为契约（见 rules-index.md 的 contract 小节），场景内的"到达"必须表现为确定性的、可在任意时间点来回拖动的状态函数；而淡入淡出这类"速度感"语义被刻意保留给接缝层使用，避免在场景内部引入无法稳定回放的渐变。

二、编排（Choreography）核心原则

规则的编排哲学可以浓缩为三个词：重叠（overlap）、按重量变速（velocity varies by weight）、单向（one direction）。

1. 重叠，而不是排队

Overlap, don't queue — next element starts within ±2 frames of the previous settling; gaps SHRINK across the cascade; the last element snaps.

• 下一个元素的起始时间应落在前一个元素落定时刻的 ±2 帧之内；
• 级联过程中间隔逐渐收缩（gaps shrink），也就是说整个级联越来越紧凑；
• 最后一个元素要"咔哒"一下快速落定（the last element snaps），制造明确的收束感。

这与"排队式入场"（每个元素等前一个完全静止后再动）形成鲜明对比——后者在规则的反模式表中被明确禁止（见下文第五节）。

2. 速度按重量分配

规则把元素分为三档：重/锚点元素（anchor/heavy）、普通词（normal word）、轻元素/标点（light/punctuation）。重的元素走得远、持续久；轻的词和标点则快速收紧落位：

参数	锚点/重元素	普通词	轻元素/标点
Y 位移（Y offset）	60–80px	40–50px	30–48px
时长（Duration）	0.16–0.20s	0.13–0.16s	0.10–0.13s
重叠（Overlap）	间隔 0–2 帧	重叠 1 帧	重叠 1–2 帧

注意表内语义的微妙之处：锚点元素因为"最重"，给的是正间隔（gap）——它先落定，给视线一个"落点"；而普通词与轻元素则提前重叠（overlap）——它们在前一个元素尚未结束时就开始运动。这样形成的整体效果是"波浪"，而不是"一列火车依次到站"。

3. 缓动（Easing）与方向

• 使用 power4.out（需要更利落的"啪"感时用 expo.out）；入场永远不要用 .inOut——.inOut 的对称加速会让入场显得"黏滞"而非"甩入"。
• 一次级联只允许一个方向（One direction per cascade）。方向一致性是瀑布入场成立的前提——自下而上就是全程自下而上。
• 把最后一个词拆成片段（fragments）来延展高潮：最后一个词拆开后，各片段比整词飞得更远（extra travel），从而放大收尾的冲击力。
• 落定之后，整组元素通常会继续滑动为下一个节拍腾出空间——那是 nudge-curve.md（慢-快-慢三阶段组滑动）的职责，二者天然衔接。

4. 与兄弟规则的衔接

在 rules-index.md 的 "Transition & Motion" 分组中，waterfall-entry 与 spring-pop-entrance（缩放弹入）、motion-blur-streak（方向性速度模糊）、nudge-curve（组滑动）同属入场/运动家族。规则文档明确写道："A cascade arrival usually precedes this slide"，即瀑布入场之后通常接一段 nudge 滑动；而在 logo-assemble-lockup 蓝图中，"sequential per-letter slide-in + terminal punctuation landing"这一动作也直接映射到 waterfall-entry——末位标点正是级联的"最终、最重的节拍"。这说明该规则在仓库中的典型用法是作为多规则组合的一个原子构件，而非孤立使用。

三、JS 实现：落点计算公式与参考代码

规则的核心实现模型是：

Each element: tl.set (instant reveal + offset) then tl.to (whip to rest).

即每个元素分两步：

1. tl.set——立即揭示（二进制不透明度 0→1）并同时把元素推到下方的偏移位置；
2. tl.to——把 Y 偏移归零，完成"甩入归位"。

关键公式：

nextStart = prevStart + prevDuration − (overlapFrames × F)

其中 F = 1/60（一帧的秒数）。+overlap 表示级联重叠（后一个提前开始），−overlap 表示刻意留出的间隔（gap）。整个公式以帧为单位精细控制级联节奏。

CSS 侧的要求：元素初始为 opacity: 0; display: inline-block（保证动画开始前不可见，且允许对行内文本逐词位移）。

规则文档给出的参考实现（可直接在 HyperFrames 场景片段内使用）：

var F = 1 / 60;
var t0 = 0.1;
// anchor (heaviest): biggest travel, longest settle
tl.set("#el-1", { opacity: 1, y: 80 }, t0);
tl.to("#el-1", { y: 0, duration: 0.18, ease: "power4.out" }, t0);
// normal word: 2 frames after the anchor finishes
var t1 = t0 + 0.18 + 2 * F;
tl.set("#el-2", { opacity: 1, y: 45 }, t1);
tl.to("#el-2", { y: 0, duration: 0.15, ease: "power4.out" }, t1);
// light word: 1 frame BEFORE the previous finishes (overlap)
var t2 = t1 + 0.15 - F;
tl.set("#el-3", { opacity: 1, y: 40 }, t2);
tl.to("#el-3", { y: 0, duration: 0.14, ease: "power4.out" }, t2);
// split final-word fragments: tightest overlap, extra travel (lighter)
var t3 = t2 + 0.14 - F;
tl.set("#frag-a", { opacity: 1, y: 70 }, t3);
tl.to("#frag-a", { y: 0, duration: 0.16, ease: "power4.out" }, t3);
var t4 = t3 + 0.14 - F;
tl.set("#frag-b", { opacity: 1, y: 70 }, t4);
tl.to("#frag-b", { y: 0, duration: 0.15, ease: "power4.out" }, t4);
// punctuation: lightest, fastest
var t5 = t4 + 0.13 - 2 * F;
tl.set("#dot", { opacity: 1, y: 48 }, t5);
tl.to("#dot", { y: 0, duration: 0.12, ease: "power4.out" }, t5);

逐段解读这段代码所体现的编排思想：

• 锚点元素 #el-1：位移 80px、时长 0.18s，是全组"最重"的节拍，作为级联的起点；
• 普通词 #el-2：在锚点结束后 2 帧（+2 * F）才开始，构成一个短暂的"落点停顿"；
• 轻词 #el-3：在 #el-2 结束前 1 帧（-F）开始，实现重叠；
• 末词拆分成 #frag-a/#frag-b：重叠最紧（同样 -F），位移加大到 70px——"fragments travel further"；
• 标点 #dot：最轻、最快（0.12s），重叠 2 帧（-2 * F）快速"咔哒"落定，收束整个级联。

这套写法完全符合 rules-index.md 中"每个规则都假设的契约"：单条暂停时间轴（paused: true）、绝对时间值（无 += 相对位移）、无 Math.random/Date.now、无 repeat: -1、只动 transform 与 paint-only 属性（y 属于 GSAP transform 别名，SKILL.md 明确允许；width/height/top/left 被禁止）。

四、工程约束：为什么"二进制 0→1"而非淡入

规则在 front matter 与正文中反复强调一条核心纪律：

Opacity is BINARY 0→1 via tl.set — never fade an arrival.

原因可以从 HyperFrames 动画系统的整体契约来理解：

1. 确定性回放（determinism）：HyperFrames 的渲染是"单条暂停时间轴 + 按时间采样"的模型（rules-index.md 契约第 1、3 条：paused timeline、无 Math.random/Date.now）。tl.set 在指定时间点瞬时建立最终可见状态，是纯时间函数，任何帧位置都稳定可复现；而渐变淡入依赖中间插值，一旦与 seek 交互就容易出现"半透明残留"等不可控状态。
2. 速度语义的归属：规则文档的反模式表中写道——"seam cuts fade; arrivals don't"。淡出/淡入是接缝（seam）用来制造速度感的手段（waterfall cut 的 fade 本身就是速度技巧）；入场（arrival）如果也淡入，就会和接缝层的语言冲突，稀释级联的"甩入"冲击力。
3. 性能与合层：tl.set 一步到位避免了对 opacity 的逐帧插值；与 SKILL.md 中"空间运动只用 GSAP transform 别名（x/y/scale/rotation）"的纪律配合，y 位移走合成器、opacity 走 paint-only 允许列表，共同保证 seek 安全与渲染稳定性。

需要补充的是：tl.set 的"即时设置"与 spring-pop-entrance.md 中"必须在 fromTo 里显式写出 from 状态、不能依赖 CSS 隐藏起点"的约束同源——都为了保证 t=0 时刻在 seek 下依然状态正确。

五、反模式（Anti-patterns）：必须避免的三个错误

规则文档给出了一张"不要做 / 应该做"对照表，这是实战中最容易踩的坑：

不要（Don't）	应该（Instead）
排队式入场（每个元素等前一个落定后才开始）	重叠 ±1–2 帧——级联是波浪，不是队列
所有级联元素使用相同的位移与时长	按重量分配：锚点走得更远，标点快速收束
入场时渐变淡入（gradual opacity fade）	经 tl.set 做二进制 0→1——淡入与"啪"感冲突（接缝层才用淡出；入场不用）

这三个反模式恰好对应正文三大原则的"负面镜像"：不重叠 → 变成排队、不分区重量 → 失去波浪节奏、渐变淡入 → 削弱甩入的利落感。在做动画审查（audit）时，可以借助技能自带的 animation-map.mjs 脚本检查时间轴上的级联是否出现"死区（dead zones）"或 stagger 不一致——这正对应规则对重叠节奏的要求。

六、参数速查与取值建议

综合规则正文的参数表与上述参考代码，可整理出一份实战速查表（单位：秒/像素/帧）：

参数	建议取值	说明
F（帧时长）	1 / 60	以 60fps 为基准的帧换算常量
起始时间 t0	约 0.1s	给场景开拍留一个节拍的"安静"
锚点 Y 位移	60–80px	最重的元素，走得最远
普通词 Y 位移	40–50px	中档
轻元素/标点 Y 位移	30–48px	最轻，快速收束
锚点时长	0.16–0.20s	最长落定时间
普通词时长	0.13–0.16s	中档
轻元素/标点时长	0.10–0.13s	最短，产生"咔哒"收尾
锚点后间隔	0–2 帧（gap）	提供"落点"
普通词重叠	1 帧（overlap）	开始形成波浪
轻元素重叠	1–2 帧（overlap）	波浪加速
缓动	power4.out（或 expo.out）	入场永不 .inOut

七、在仓库中的使用场景与延伸阅读

从仓库证据看，waterfall-entry 被设计为可组合的原子规则：

• 规则索引定位：rules-index.md 将其收录于 "Transition & Motion" 分组，推荐"每个场景组合 2–4 条规则、用单条暂停时间轴粘合"（SKILL.md 的默认工作流）；
• 蓝图中的角色：logo-assemble-lockup.md 将"sequential per-letter slide-in + terminal punctuation landing"（逐字母滑入 + 末位标点落定）映射到本规则，说明它常用于品牌字标/词标的逐词构建；
• 与接缝层的分工：waterfall CUT（seams/waterfall-cut.md）负责场景切换，本规则负责场景内到达——两者以"不透明度策略 + 轴向 + 出场方式"三重维度严格区分；
• 与后续动作的衔接：级联落定后的组滑动由 nudge-curve.md 承接（慢-快-慢三阶段：power3.in 斜坡 → 线性爆发 → power4.out 尾巴，时间比上尾巴 ≥ 3× 斜坡），两个规则在文档中互相引用、构成"入场 → 腾位"的完整动作链。

如果你想在本地验证这套编排，可以按 SKILL.md 的脚本说明对某个 composition 目录运行动画图审计（animation-map.mjs），检查级联的 stagger 一致性；再结合 hyperframes-cli 的 lint / snapshot / preview / render 命令查看确定性回放效果。所有示例遵循 HyperFrames 核心契约：单条暂停时间轴、绝对时间值、transform-only 位移、无随机数——这让 waterfall entry 既可以稳定地逐帧审查，也能在 4K 渲染与合成管线中被精确复现。