MooT020/gsap-explainer

GSAP 解說器——專業影片等級

建立一個自包含的 HTML/SVG/GSAP 解說器，播放起來像一部製作出的 YouTube 動畫，而非幻燈片：每個場景使用一條 GSAP 時間軸驅動物理感編排、一個持續存在的飛行主持人吉祥物、具有深度感的分層漸層世界、角色群體、一個帶有暗角與顆粒感的「攝影機」，以及可搜尋的播放器。CSS-only 框架適用於小型漏斗嵌入；使用此技能製作 YouTube 等級的內容影片。

參考建置是此技能資料夾中的 scaffold.html——一個可執行的 5 場景完整範例（主題：「複利如何滾雪球」），包含下方所有模式的上下文，已通過保留與零重疊檢查。它出廠時不包含 GSAP：執行 python3 inline-gsap.py scaffold.html 一次（擷取 GSAP 3.13 到 gitignored 的 vendor/ 目錄，然後內嵌），打開檔案——它必須能播放。當下方某個模式不清楚時，請閱讀此檔案。

從這裡開始——絕不失敗的路徑

1. 首先撰寫分鏡劇本，格式為 markdown 文件：每個場景——時間戳記、持續時間、視覺內容、螢幕文字、旁白台詞。最後附上準確性檢查清單，並驗證其中的每一項陳述。場景持續時間成為 SCENES 陣列；旁白台詞成為 sr-only 逐字稿。
2. 複製 scaffold.html 到 <主題>.html。它已預先修正所有常見問題：框架時鐘、搜尋 chrome、主持人飛行、世界背景、攝影機覆蓋層、群體角色、減少動畫模式、逐字稿。對它執行 inline-gsap.py 並在觸碰任何東西之前先打開它——它必須能播放。
3. 一次替換一個場景，保留五個範例作為你的慣用語來源，直到每個都被替換：S0 = 帶有翻轉揭示的黑暗鉤子；S1 = 帶有彈跳的掉落物理；S2 = 傾倒/motionPath 飛行 + DrawSVG；S3 = 強制重疊碰撞證明（巔峰模式）；S4 = CTA 停留。同時更新 SCENES、FL、ACTS、CH_STARTS——它們是依場景索引鍵入的平行結構。
4. 使用定格畫面進行每個場景的 QA（參見 QA），修正，然後發布（自包含檔案）。

當下方某個模式符合時，切勿從頭開始編寫場景的編舞——改為調整該模式。無論模型為何，這就是達到標準的方法。

架構合約（已在範本中接線）

• 固定的 800×500 舞台，縮放至容器（fitScale）。場景時鐘使用 setTimeout（SCENES 陣列，每個場景的秒數；最後一個條目 999 = CTA 停留；advance() 對其呼叫 done()）。
• 文字/晶片/字幕透過 CSS 基本效果進入（.fu 淡入上升、.pp 彈出、.fi 淡入），帶有內聯 animation-delay——廉價且可重播。英雄級編舞使用 GSAP：runScene(i)（從 showScene 呼叫）終止前一個時間軸，並從 FL[i]（主持人飛行）+ ACTS[i]（場景動作）建立 gsap.timeline()。
• 每個 ACTS[i] 必須以 gsap.set(...) 重設開始，針對其觸及的所有元素——場景在重播/搜尋時會重新啟用，且被終止的補間會留下過時的內聯樣式。
• GSAP 擁有的元素獲得 g-hero 類別（或存在於其中），且絕不攜帶 .fu/.pp/.fi——每個元素只有一個擁有者。
• pause()/resume() 呼叫 curTl.pause()/play()；CSS 端透過 .paused 類別凍結。導航總是恢復播放（暫停且剛切換的場景停留在透明度為 0 的入口——絕不「搜尋並保持暫停」）。
• 播放器：點擊進度條進行搜尋（sceneAt(frac)）、上一頁/下一頁按鈕、←/→ 鍵、章節標記（CH_STARTS）、滾動時自動播放、標籤頁隱藏時自動暫停。
• 交付物是無聲視覺軌道（主軌保持無聲）；旁白作為 EleventLabs 管線建置的獨立 <名稱>-vo.html 預覽變體交付（參見 VO 製作）。sr-only 逐字稿即為 VO 腳本。根據朗讀速度重新計時 = 將 SCENES[i] 延長至片段的 1.5–2 秒（延長絕不會使節拍懸空；只有修剪會）。

模式庫（調整，不要發明）

所有這些模式都存在於 scaffold.html 中——複製最接近的一個。

• 主持人飛行——FL[i] = [[分數, x, y, 指向], ...]。第一個路徑點 = 前一個場景的最後一個（無縫剪輯）。長程通過 MotionPath 自動轉彎（在 fly() 中）。鉛筆尖位於角色偏移約 (-10, +95)：要指向目標，將主持人停在目標的右上方。當場景需要畫面時，將主持人送出舞台（x=850）。
• 帶有重量的掉落——gsap.set(els,{y:-300,opacity:0}) 然後 .to(els,{y:0,opacity:1,ease:'bounce.out',stagger:.09})。延遲 + 彈跳即是物理感。（layMarbles 將行打包在容器內；行寬為 168，而非 180——更寬則掉落會穿牆。）
• 強制重疊碰撞（證明巔峰）——兩條棒子掉落進一條無法容納兩者的軌道；第二條試圖閃避（x 搖擺），失敗，安定下來；重疊段以 back.out 彈入並發光（boxShadow 搖擺 repeat:-1）；然後兩個雙徽章角色小兵在其中彈出。意圖 → 失敗 → 後果是讓它栩栩如生的關鍵。
• 傾倒/變換——容器旋轉（transformOrigin 在壺嘴），內容物一個接一個沿著 motionPath 弧線飛出（{path:[{x,y},{x,y}],curviness:1.6}, ease:'power1.in'），著陸成一行，交叉淡入使用 DrawSVG 繪製的新形狀。
• 翻轉揭示——一個誘人的 ✓ 彈出（back.out(2.4)），搖擺，然後交換為 ✗ 猛力關上（scale:3→1, power4.out）+ 背景閃光（backgroundColor 搖擺）。
• 誘惑而後粉碎——答案發光/脈動（scale 搖擺 ×3），然後消亡（opacity:.25, scale:.92, rotation:-3, power2.in）；正確答案隨後蓋印進入。
• 蓋印猛擊——gsap.set(stamp,{opacity:0,scale:2.6,rotation:-14}) → .to({opacity:1,scale:1,rotation:0,duration:.35,ease:'power4.out'})。
• DrawSVG——gsap.set(path,{drawSVG:'0%'}) → .to({drawSVG:'100%'})；彈回 = 繪製到 72% 然後快速反向。DrawSVG 會覆寫 stroke-dasharray——虛線在繪製時會呈現實線；相應地設計。
• 作為角色的群體（最具 Kurzgesagt 風格的一招）——minion(size, badges) 小角色工廠：數量是角色，而非點。35–55 秒 CSS 循環上的環境 3 角色群；群組包含其角色陣容；證明時刻是角色同時佩戴兩個徽章。
• 場景剪輯擦拭（內建於 runScene）——兩個傾斜面板（強調色領先，墨水軌跡延遲 .09 秒）在每次剪輯時掃過舞台。保留它；這是「真正轉場」最便宜的勝利。值得偷用的豐富道具場景點子：一個活著的頁面角色、一個螢光筆破壞、一個檔案櫃、一個量表指針、一個進度條競賽。

免費外掛程式套件（GSAP 3.13——自 Webflow 收購以來全部免費）

inline-gsap.py 擷取並內嵌核心 + DrawSVG + MotionPath + MorphSVG、SplitText、Physics2D、PhysicsProps、CustomEase、CustomWiggle、CustomBounce、Flip、ScrambleText。所有內容均為免費授權。inline-gsap.py <檔案> 注入所有內容以及在 <!--GSAP_INLINE--> 標記處的 registerPlugin 區塊；--refresh 在已內嵌的檔案中交換套件。已證實的模式（全部存在於範本中）：

• SplitText 字元瀑布——透過註冊表（splitOnce(key,sel) 快取在 SPL{} 中——在每次場景重新執行時重新分割會巢狀 span）在初始化時分割一次。踢腳：字元從 {opacity:0,y:14} 開始，延遲 .016，開始 ≤.15s。英雄字詞：字元從 {y:-64,rotation:-9} 使用 back.out(1.9) 延遲 .07；或 {scale:2.7} power4 延遲 .11 = 蓋印猛擊。場景透過透明度（而非 display:none）隱藏，因此初始化時分割是安全的。
• ScrambleText 定義鎖定——一個回報台詞置亂就位：scrambleText:{text:'≥ 1',chars:'<>=~≠≤≥',speed:.6}。在 JS 字串中偏好使用 JS \u 跳脫符號。主題化字元集（定義用數學符號）比 'upperCase' 讀起來更好——隨機大寫置亂讀起來像載入故障。
• CustomWiggle 安定——CustomWiggle.create('wigSettle',{wiggles:4,type:'easeOut'})，然後 rotation:'+=10', ease:'wigSettle'——振盪並返回起點，因此相對值在重播中永遠不會累積。用於：蓋印著陸、角色反應、主持人到來時的鉛筆輕敲（在 fly() 中 if(wp[i][3]&&!wp[i-1][3])）。
• CustomBounce 掉落擠壓——CustomBounce.create('thud',{strength:.58,squash:2.4}) 建立配對的 easing 'thud' + 'thud-squash'。drop(tl,targets,time,dur,stagger) 輔助函式執行 3 條同步補間：透明度彈出、y 使用 'thud'、scaleX:1.45,scaleY:.55 使用 'thud-squash'（在重設中 transformOrigin:'50% 100%'）。嚴格優於 bounce.out——擠壓即是重量。
• Physics2D 爆發——burst(tl,scene,x,y,n,time,colors)：慶祝/碎片粒子，適用於著陸位置不重要的情況（碰撞高峰、勝利蓋印）。基於索引的種子角度/速度（(i*53)%140）= 重播相同，無 Math.random。在重新進入時移除舊的 .pfx；在場景結束前淡出，以免殘留。
• MorphSVG 融合——最頂尖的 Kurzgesagt 招式：N 個物體「變成」概念。物品著陸成一排 → 一個膠囊路徑在它們上方淡入 → morphSVG 到箭頭輪廓，同時 fill 補間（「相同物體，新形狀」，字面意思）。重設需要 gsap.set(path,{morphSVG:ORIGINAL_D})——一個被變形的路徑會保留其突變的 d。
• Flip：在此請勿使用——在固定 800×500 絕對座標的舞台上，你總是知道 delta；一個普通的 y: 補間在 tl.pause(t) QA 下是確定性的，而 Flip 的運行時測量會破壞定格畫面搜尋（且回呼在抑制的搜尋上不會觸發）。Flip 僅在真正的回流版面（DOM 驅動的清單、響應式容器）中才有價值。一個「佔據空出位置」的節拍是一個已知 delta 的補間。

資產工藝（10 倍通過模式——道具如何不再像樣式化的 div）

深入探討：完整的資產生成規範（建置順序、工廠、SVG 合約、品質關卡）存在於 explainer-assets 技能中——在建立或重建資產時使用它；此部分為快速參考。

• 單一配方貼紙——深度完全來自分層的 box-shadow：硬右下墨水點（3px 3px 0 var(--ink)）+ inset 0 2px 0 rgba(255,255,255,.3-.5) 頂部光澤 + inset 0 -3px 0 rgba(0,0,0,.1) 底部陰影 + inset 0 0 0 1-2px rgba(255,255,255,.14) 裁切邊緣。半透明內嵌適用於任何背景顏色，因此在 .xchip/.qbar/.stamp/.l3 span 上的一個 CSS 通道即可提升所有變體，無論亮色或暗色。保持一個半徑比例（sm 10 / base 13 / lg 16）和一個光方向（左上）全片適用。
• 任何平面填色的雙色調——將 background:rgba(...) 替換為 linear-gradient(180deg, lighter, base) + 光澤/陰影內嵌。語義顏色得以保留；表面讀起來像被照亮。
• 精心製作的容器配方（桶子/罐子/杯子）——基礎陰影橢圓 → 漸層主體 → 2 個帶有 1px 白色高光的錐形環帶 → 邊緣環 + 一個較暗的內部開口橢圓（那一個暗色橢圓就是讓開口讀起來像 3D 的關鍵）→ 柔和反射曲線。沿著梯形邊內插環帶端點。
• 在一個選擇器中製作的線稿——所有繪製的筆畫上的靜態 filter:drop-shadow(0 1.5px .5px rgba(0,0,0,.17)) 為每個箭頭/框提供 2 色調底面，並隨 DrawSVG 動畫揭示（filter 獨立於 dashoffset）。
• 使用偽元素裝飾 GSAP 驅動的道具——::before/::after（尺規線、膠帶條、裂縫、彎月面線）自動跟隨時間軸的變換：零新增編舞，零足跡變化。追蹤每個類別「佔用」了哪些偽元素——衝突是無聲的。
• 工廠角色：僅單例使用 id——主持人（一個實例）可能攜帶 uid 後綴的漸層/反射；一個多次內嵌的工廠（小角色）必須保持無 ID（僅平面填色），否則 id 會在文件中重複。
• 在重新製作時保留編舞合約——首先從腳本建立選擇器庫存；位置選擇器是地雷（.bkt3 path = 第一個路徑必須保持被補間的主體——以橢圓而非路徑開頭）。新的裝飾性變換應放在包裝器 <g> 上。
• 文字安全的光澤注意事項——在攜帶 SplitText/英雄文字的晶片上，光澤必須是內嵌的 box-shadow（在文字下方繪製），絕不能是定位的 ::before 覆蓋層（在字元上方繪製並使它們變暗）。
• 紙張堆疊 + 折角配方（任何紙張道具）——2 個偏移的背面矩形（±0.6–1.5° 旋轉，較暗的奶油色，svg 上 overflow:visible）、角落裁切陰影三角形 + 折疊翻蓋、頁面邊距規則、左上角光澤路徑。足跡不變，僅視覺溢出。
• 抽屜/家具正面套件——正面矩形 + 頂部光澤條 + 標籤板 + 嵌入式把手 + 單元間深度陰影線；為高亮單元參數化調色板，保留其動畫類別。
• 雙色調向量雲——淡色基礎橢圓 + 3 個重疊的白色圓形 + 一個較亮的頂部橢圓；根據情緒變體重新著色基礎色調。
• 藍圖卡片覆蓋層——絕對定位的子 svg（淡色尺規網格 + 4 個角落標記）作為卡片的第一個子元素：技術繪圖紋理，對卡片的補間類別或文字子元素零影響。

電影感層（Kurzgesagt 級別模式）

• 攝影機裝置 #xplCam——僅內容的包裝器，位於 #xplStage 內部，包含場景（環境層、演員、暗角/顆粒保持外部）。在回報時刻進行逐拍推近（~1.02–1.05，transformOrigin 在英雄物體）、揭示時拉遠、在 runScene 中每次剪輯時將縮放重設為 1。切勿縮放 #xplStage 本身——那是 fitScale 的任務。最重要的場景在其整個動作中獲得一個不間斷的緩慢推進。根據可見的藥丸/道具邊界檢查裁剪風險，而非全寬容器。
• 主持人表演控制 actorBody——.xpl-actor > [data-host] div，獨立於 fly()（外部 x/y）和 armEl。輔助函式：跳躍（y-8 搖擺）、傾斜（±4° 朝向指向目標）、驚嚇（後退+傾斜）、在最大勝利時 360 度旋轉。每次剪輯重設。小角色進入個性：在彈出之前從邊緣窺視（x 偏移 → 0）。
• 回報光——一個共享的 #xplGlow 模糊徑向（mix-blend-mode:screen，透過 CSS var 著色），在每個場景最大節拍時定位並發散在英雄物體後方，每次剪輯重設。約 15 行即可獲得即時的「照亮」感覺。
• 一天中的時間漂移——在初始化時為 #envFar 播種一個基礎 filter（讓補間可以內插，永遠不會從 none 跳躍），然後輕鬆調整亮度/色調...

...

[為翻譯截斷]