Stickman 动画师
你编写 scenes.js —— 为 film.json 中的每个剪辑编写一个 film.scene(id, sc => { … }),ID 相同,顺序相同。所有代码均为纯浏览器端 JavaScript,使用全局 SM 引擎。在编写之前,请阅读 references/api.md(完整速查表)和 references/cookbook.md(可复制的配方)。
思维模型
- 本地时间。 在每个场景内部,所有时间均相对于该剪辑的起始时间。
sc.dur= 剪辑长度。 - 可链式调用。 每个动作返回其结束的时间:
const t = bob.walkTo(900, 0.2); bob.wave(t); - 语音同步。
sc.cue("word")= 旁白说出该词的估计本地时间(sc.cue(["word", 1])= 第二次出现,sc.cue(0.5)= 旁白时间轴的中点)。将视觉效果放在该词之上或稍前(sc.cue("idea") - 0.15)。 - 图层。
world(环境)→back(道具)→ 角色 →front(角色前方的道具)→ui(屏幕空间,忽略摄像机)→top(转场)。向道具传递{ layer: "front" }/"ui"。 - 坐标。 画布大小为
sc.W × sc.H(1920×1080、1080×1920 或 1080×1080)。sc.groundY是地面(横屏时位于画面下方 80% 处,竖屏时位于 74% 处)。角色的y坐标为其脚底。 - 事物。 道具、文字、图表、形状均为“事物”(Thing):
.pop(t) .fadeIn(t) .rise(t) .dropIn(t) .slideIn(t,d,dir) .moveTo(x,y,t,d) .arcTo(x,y,t,d,h) .scaleTo .rotateTo .spin .pulse .shake .wobble .bob(t0,t1) .glow .tint .draw .fadeOut .popOut .hide .show。 - 入场前隐藏。 创建时使用
{ hidden: true },然后.pop(t);文字默认隐藏,直到.in(t, fx)。
场景骨架
const film = SM.film(); // 主题/格式来自 film.json
film.scene("hook", sc => {
sc.enter("fade"); // 可选,匹配前一场景的退出
sc.ground(); // 地面线(样式: "grass" | "none")
const bob = sc.figure({ x: -150, face: "dots" }); // 或 sc.character("zeke", {...})
const t1 = bob.walkTo(sc.W * 0.35, 0.2);
bob.point(sc.W * 0.7, sc.H * 0.4, sc.cue("this"));
const chart = sc.barChart({ x: sc.W * 0.68, y: sc.H * 0.45, data: [{ label: "2024", value: 4 }, { label: "2025", value: 9 }] });
chart.grow(sc.cue("grew"));
sc.text("Revenue [doubled]", { x: sc.W * 0.68, y: 150, size: 80 }).in(sc.cue("doubled") - 0.1, "words");
sc.camera.focus(sc.W * 0.6, sc.H * 0.5, 1.12, 1.0, 3); // 缓慢推近
sc.exit("wipe-left");
});
片头与片尾
在 film.json 中声明 "intro" / "outro" 的剪辑会自动构建。你无需为它们编写场景。若要添加额外内容(例如在标题周围爆出的道具、在行动号召处挥舞的角色),编写场景并自行调用预设;此时自动版本会被跳过:
film.scene("intro", sc => {
const t = sc.intro("countdown", sc.clip.intro); // 返回标题落地的时间
sc.prop("rocket", { x: 1500, y: 300, size: 120, layer: "ui", hidden: true }).pop(t - 0.8);
sc.exit("wipe-left");
});
film.scene("outro", sc => {
sc.enter("fade", { color: "bg" });
sc.outro("kino", sc.clip.outro);
sc.figure({ x: 1500 }).point(1150, 830, 1.2);
});
导演规则(如何让画面更好看)
- 每 2-3 秒发生一点变化。 为每个剪辑规划 3 个节拍;用摄像机的推拉、角色的眨眼/点头、道具的弹动或高亮来填充间隙。
- 先布局再动画。 决定角色、主要道具和文字的位置(16:9 中使用三分法;9:16 中垂直堆叠)。让文字远离角色的头部和其他文字。
- 角色要表演,而非站立。 使用有意义的姿势:指向讨论的对象、在想法出现前思考、在揭示时惊讶、在谬误处耸肩、在胜利时庆祝、用推/爬/跑来表现努力。
- 一次只有一个焦点入场; 多个事物出现时,相互间隔 0.1-0.2 秒。
- 跨剪辑匹配退出和入场(相同转场类型)或匹配剪辑(相同姿势/物体位置)。
- 强调色承载意义:
"a1"问题、"a2"解决方案、"a3"奖励。可传递颜色名称:"a1" | "a2" | "a3" | "ink" | "muted" | "soft" | "paper"或十六进制。 - 地面真理: 角色站在
sc.groundY上(或你计算出的表面);放在地板上的道具使用y = sc.groundY - size*0.4。 - 竖屏: 角色大小 420-460,道具 200-300,文字 70-120,保持中间区域活跃,字幕放低。
验证(必须循环)
stickman check <dir>→ 必须显示 Check passed。page_error表示你的 JS 抛出了异常;修复它。stickman snapshot <dir>(或在关键节拍使用--at指定时间点)→ 打开snapshots/contact-sheet*.jpg和 PNG 图片并检查。 修复:裁剪、重叠、悬浮的角色、空白时刻、不可读的文字、手臂穿过头部(调整姿势覆盖)、错误的强调色。- 重复运行直到一切正常,然后渲染。
注意事项
- 按时间顺序安排每个角色动作。
celebrate()会在 +1.0 秒时调度回到stand状态;如果之后很快又要摆姿势,传递{ hold: true }。 bob.hold(prop)将道具附着到右手并保持直立;在使用前创建该道具并.pop(t)。- 文字标记:
"[强调的文字]"会使用accent选项(默认为a2)给短语着色。 - 图表以离散步长计数数字;在图表选项中指定
prefix/suffix/decimals。 - 不要使用
Math.random/Date/setTimeout。使用SM.rng(seed)。 - 允许使用原始 GSAP:
sc.tl.to(el, vars, sc.T(localTime))—— 确保它是时间的纯函数。