timeqsz/motion-atoms

Motion Atoms

讓 Agent 按描述製作動效，也能從參考影片中拆出可復用的動作與組合。Agent 負責觀察、理解用途和編排，包內原子、驗證器與渲染工具負責執行；使用者不必先挑效果或記住原子名。發行包包含 53 個二維原子，分 8 族，與網站共用實作。使用相對路徑存取隨包資源，不依賴網站線上、原始碼倉庫或 npm 安裝。首次安裝見 安裝與環境；manifest.json 記錄本包版本、檔案與校驗值。

按任務讀，不要一次載入全部目錄

任務	先讀	再取用
按描述生成，或繼續修改現有效果	生成與修改閉環	意圖映射
拆解參考影片，或分析某個動作如何實現	影片動效拆解	按觀察結果查原子清單與用法，以 breakdown 截取原片；按動效類型分軌，軌道間清晰分隔，同軌多個無文字動作塊獨立高亮
二維文字、圖形、屬性動畫	二維清單，只篩需要的族	atoms/<ID>.md 與同名 .mjs；輸入輸出約定
導出二維素材檔案	場景編排	scripts/motion.mjs；精確欄位見 MotionSpec
修復卡頓、偏移、遮擋、不可讀	時間與畫面檢查	修復實際問題，再檢查受影響的幀與播放

製作時先明確宿主、畫幅、幀率、目標主體及交付物；拆解時先確認可觀看的影片、範圍與分析目的，保留源時間碼。沿用使用者已有決定。動效名稱、參數和行為以包內說明為準。

交付使用者要求的結果，不止推薦候選原子；已有結果的修改保留原始檔案，核對實際變更。二維 deliver 可打包獨立預覽、可編輯場景、資源與檢查報告；報告不會把數值校驗冒充視覺驗收。超出已實現能力時說明缺口，再用呼叫方的宿主實作，不能把相近效果包裝成已經滿足需求。

製作核心

• 先有用途，再選動作。 組合展示一個明確的產品、事件或狀態變化；每個原子都要解釋得出作用。參考真實 PV 的主體、節奏和銜接，實際觀看後提煉方法，不照搬畫面，不用無關圖示、假控制項或裝飾運動湊數量。網站短篇約 5 秒、2–3 種原子；這不是所有影片的時長和數量限制。
• 編排變化，不給海報掛特效。 先排好主次，再寫清楚入場、變化、落定和離場；動作之間有因果或視覺承接，關鍵變化一眼可見。各組採用適合主體的進出方式，文字停穩後留足閱讀時間；刪掉無用邊角小字。
• 運動必須完整、連貫。 不提前截斷、不統一反向播放；接鏡兼顧位置、方向、速度和亮度。有限動作與連續循環分別設計，循環檢查真實首尾，不能用補幀或提高標稱幀率掩蓋停頓。
• 主體作為整體。 圖像、字標、徽記共用正確的座標和樞軸；真實遮罩與繪製順序決定遮擋。入退場檢查整組文字和細節，不能只讓底板離開；在實際畫幅與顯示尺寸檢查對齊、清晰度和裁切。
• 素材服務於動作。 選擇匹配用途、許可不可追溯的免費商用素材，按許可處理署名和原始檔案分發；別用同一素材鋪滿不同案例。控制素材載入體積；網站與宣傳片引用同一場景時同步素材和運動。
• 以實際輸出驗收。 網頁檢查真實播放和目標尺寸；製作影片時先分鏡，再逐幀渲染、合成影片，抽查編碼後的入場／穩態／退場／接縫並完整播放。沒看過的部分不聲稱檢查通過；可播放結果與檢查範圍一起交付。具體技術檢查見 時間與畫面檢查。

二維：嵌入宿主渲染

只複製需要的 .mjs；需要繪製時再複製 atoms/draw.mjs。原子按顯式幀求值，不自帶播放器。宿主掌握繪製順序、座標與時間。八族各答一個問題：屬性（變什麼）、節奏（怎麼變）、循環（一直動）、編排（誰先誰後）、轉場（出現消失）、文字（字的動法）、質感（疊在上面）、生成（憑空產生）。

import move from './atoms/prop.move.mjs';
import spring from './atoms/timing.spring.mjs';
import breathe from './atoms/loop.breathe.mjs';
import { drawAtom } from './atoms/draw.mjs';

const subject = { points: [[-50,-50],[50,-50],[50,50],[-50,50]], closed: true, fill: true };
const curve = (t) => spring({ frame: t, durationFrames: 1 }).value;   // 節奏：只給曲線
function renderFrame(ctx, frame) {
  const shape = move({ frame, durationFrames: 30, subject, params: { fromPx: -200, toPx: 0 }, ease: curve });
  const breath = breathe({ frame, startFrame: 30, durationFrames: 90 });   // 循環：疊在上面
  drawAtom(ctx, { ...shape, scale: shape.scale * breath.scale }, { x: 320, y: 200, color: '#f4f1ea' });
}

• 獨立函式的 params 可只傳改動項；MotionSpec clips 必須寫全參數。不要混用這兩種約定。
• 同時組合先看角色與 writes：位移、角度相加，縮放、透明度、拉伸相乘，濾鏡依次拼接；編排原子返回 copies，宿主按副本的偏移和延遲各畫一次。一個主體的輪廓輸出不能靠物件展開疊加兩個 layers。
• MotionSpec 裡寫同一屬性的屬性動畫不能時間重疊，可前後接力；前段終值與後段起值要相接。節奏、循環、編排和質感是疊加的。檔案匯出不會自動沿用網站的循環播放策略。
• 圖形座標相對主體原點；文字位置為首行左側基線。裝置字型（system、mono）可直接使用，精確跨機字形才需固定字型資產。
• 可執行最小範例：atoms/example.html，陣列 × 錯開 × 位移 × 彈簧。

二維：交付素材檔案

以下命令在解壓後的 motion-atoms/ 內執行；輸出寫入自己的工作目錄。匯出前按需檢測本機瀏覽器／FFmpeg，不在基礎檢索時要求這些工具。

node scripts/motion.mjs describe transition.slices
node scripts/motion.mjs scaffold transition.slices --out work/slices.scene.json --width 1920 --height 1080 --fps 30 --duration 60
node scripts/motion.mjs validate work/slices.scene.json
node scripts/motion.mjs frames work/slices.scene.json --out work/check --frames 0,20,40,59 --transparent
node scripts/motion.mjs render work/slices.scene.json --out work/slices.mov --transparent

多原子場景可直接用，例如：

node scripts/motion.mjs preview assets/examples/showcase.scene.json --out work/showcase.html
node scripts/motion.mjs breakdown assets/examples/showcase.scene.json --out work/showcase-breakdown.gif --title "片頭 · 原子拆解"

preview 是 HTML，不是影片。render 可輸出 MP4（不透明）、MOV / WebM（可透明）；frames 輸出 PNG；breakdown 在畫面下方加一條條原子時間軸，輸出 GIF、MP4 或 WebM：輸入場景時說明自己做的動效，輸入拆解檔案時截取參考影片片段做拆解（見 影片動效拆解）。verified: true 只證明尺寸、幀數、時長等檔案檢查，不證明構圖、節奏或遮擋正確。交付前按 畫面檢查 看編碼結果與實際播放，並說明實際檢查範圍。回傳檔案路徑、場景路徑、幀率、時長和透明通道；這些素材沒有音軌。

能力邊界

• 影片拆解由 Agent 使用宿主的播放、抽幀和聽音工具觀察完成；包內 CLI 沒有影片辨識命令，breakdown 按 Agent 寫好的拆解檔案截取原片片段，並在下方畫出原子時間軸。可以分析超出本包的動作，但必須區分直接可用、部分近似和宿主另做，不能從成片斷言原工程、外掛或精確參數；截取的原片只用於分析，不當作素材再發布。
• 二維場景只有 text / path 節點，沒有圖片、影片、音訊、父子 group 或 z-index 欄位。屬性、曲線和副本輸出可由宿主套到圖片或影片上；幾何原子只處理折線圖形。宿主負責圖片與影片合成。
• 轉場與質感可用於文字和圖形；文字的包圍盒按渲染時的實際字形測量。循環與節拍都不讀取音訊。
• 預設範例與 scaffold 使用系統字型，包內不攜帶字庫。需要跨機一致時由宿主提供獲許可的固定字型，宣告路徑與哈希並檢查字形。
• 目前沒有三維原子；三維場景由宿主自行實作。
• 整片製作繼續使用呼叫方的分鏡、聲音、剪輯與交付流程；本 Skill 不強制使用某個宿主、視覺風格或統一轉場。

參考與致謝

本包所屬 MotionFlux 專案的早期動效索引構想參考了 Kazuki Akamine（赤嶺一希）的 Motion Periodic Table。感謝其對基礎動效整理與展示的啟發。MotionFlux 為獨立專案。