Communitygithub.com

toy-loops

使用 Python 與 Blender 打造無縫循環的 3D 紙雕世界動畫(GIF 與 MP4)、網頁主視覺圖片以及即時互動網頁元件(例如 Claude 的眼睛追蹤滑鼠)。

toy-loops 是什麼?

這個技能讓開發者能夠利用 Python 和 Blender 渲染引擎,創作出具有獨特紙雕風格(paper-craft)的 3D 動畫與靜態圖片。它完全基於程式碼建構每個物體,並透過數學計算每一幀,確保循環動畫完美閉合。此技能支援多種輸出格式,包括無縫循環的 GIF、MP4 影片,解析度達 2400x1200 的靜態英雄圖片,以及可讓 Claude 角色眼睛即時追蹤滑鼠的互動式網頁。 技能的核心是提供完整且可直接套用的工具庫,包含紙張材質(`paper`)、動畫輔助工具(如彈性緩動函數、軌跡追蹤 `Track`、`squash` 擠壓拉伸效果)、與 Claude 角色綁定(`Claude` 類別及其六種眼睛與姿勢控制)。使用者只需撰寫場景描述腳本(`scene.py`),並透過整合性的命令工具(如 `make_loop.py`)即可一鍵完成渲染、編碼、品質檢測與輸出。 此技能還內建品質檢測流程(`qa_loop.py`),會自動檢查循環接縫、影格數量、死幀停頓以及動作量是否足夠,避免常見的渲染錯誤。開發者必須遵循「在此之前先展示」以及「動畫如動畫師」等核心原則,透過預覽靜態圖與關鍵影格來確保最終成果符合作品風格與動態品質要求。

相容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/Pimboto/claude-skills/tree/HEAD/skills/toy-loops

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

toy-loops 是做什麼的?

小型紙藝世界(一座島嶼、一個露營地、一個片場),Claude 飾演主角,配上溫暖柔和的光線與如微縮模型般的淺景深。每個物體都由程式碼構建,每個影格都根據其編號計算得出,因此循環能完美閉合。此視覺風格是根據 Pimbo 在 anymation/3d_ref/style2 中的參考資料,並使用 reference-video-analysis 技能(第一輪分析:3d_ref/style2/analysis/FIRST_PASS.md)研究而來。這些參考資料是私人學習材料:請複製其工藝,切勿複製其場景。

狀態:v1,2026-11-18。 使用此技能製作並已審核的作品:

  • claude_isla:獲得 Pimbo 認可(「esta épica」)。
  • claude_fogata:第二個循環動畫。
  • director_hero:一張 2400x1200 的網頁主視覺圖片,有兩種配色。
  • claude_pose:具有即時網頁眼睛的剪影。
  • claude.glb:3D 模型。

所有檔案的位置

程式碼位於 Pimbo 電腦的資料夾:C:\Users\Pimbo\work\anymation\toy3d\skill。除非另有說明,以下所有路徑都是相對於其 kit/ 資料夾。

路徑說明
lib/toy.py視覺風格:白色斜角邊緣的紙張材質、形狀、燈光、攝影機、渲染設定
lib/anim.py動畫師工具:緩動函數、Track(姿勢到姿勢)、彈簧、squash、arc、looped
lib/chars.pyClaude:骨架及其六組眼睛;每影格呼叫一次 .pose(...)
lib/runner.py逐影格渲染場景;每個場景都以 runner.run(...) 結尾
loops/<name>/scene.py一個循環動畫
stills/<name>/scene.py一張圖片(T = 1)
tools/make_loop.py渲染、編碼為 GIF 1080/720 和 MP4 x1/x3、品質檢測、連絡表,一個指令搞定
tools/qa_loop.py循環接縫、影格數量、死幀停頓、與參考資料相比的動作量
tools/duotone.py圖片的藍色單色版本(網頁主視覺風格)
tools/web_eyes.py一個網頁,Claude 的眼睛會跟隨游標,基於無眼睛的渲染結果
tools/claude_glb.py將 Claude 模型輸出為 .glb 格式(平面色彩,保留白色邊緣),在 Blender 內部執行
out/<name>/輸出:frames/ 資料夾、最終檔案、sheet.jpg、qa.json

完成的作品會複製到 anymation/toy3d/videos/<name>/;網頁作品則放在 anymation/toy3d/web/。

需求:

  • Blender 5.2:Pimbo 的可攜帶版本位於 anymation/tools/blender;在其他環境請設定 $BLENDER 環境變數或將 blender 加入 PATH。
  • ffmpeg 需在 PATH 中。
  • 需安裝 Python 及 numpy 與 Pillow 函式庫,以執行工具。

Pimbo 不執行腳本:由你執行腳本並向他展示圖片結果。

不可打破的規則

  1. 建設之前先展示。 在開始一個新世界或角色前,先渲染 2-3 張靜態預覽(--frames ... --scale 0.5),讓 Pimbo 選擇。在展示之前,你自己必須先仔細檢查每一張圖片。
  2. pose(f) 是影格的純函數。 影格之間不攜帶狀態,不使用無固定種子的亂數,所有週期性運動在每個循環中必須是完整的循環次數。跨越循環結尾的效果請使用 looped()。
  3. 像動畫師一樣製作動畫(詳見 references/ANIMATION.md)。首先撰寫律動表(dope sheet),然後使用帶有緩動函數的關鍵姿勢。每個動作前都要有預備動作(anticipation),撞擊時擠壓(squash),快速時拉伸(stretch),手臂有重疊動作(overlap),以及單影格的眼睛切換。絕對不要線性地移動身體。
  4. 只有當品質檢測通過(make_loop.py 會顯示 PASS/FAIL),並且你已逐影格檢視過每個動作的連續畫面(請見下方「連續截圖」),才算循環完成。
  5. 明確說明哪些是測量得出的 [M]、肉眼觀察得出的 [V] 以及假設的 [S]。

工作流程

步驟內容指令(在 kit/ 目錄下執行)
1構思:一個地點,一個有開頭且能循環回來的小故事;長度 6-9 秒與 Pimbo 討論
2複製最接近的場景:loops/claude_isla(白天,戶外)或 loops/claude_fogata(夜晚,道具,特效)
3建立場景、放置 Claude、設定燈光與攝影機;檢視靜態預覽python tools/make_loop.py <name> --frames 0 --scale 0.5
4撰寫律動表註解,然後建立各個 Track;渲染關鍵姿勢python tools/make_loop.py <name> --frames 44,62,66,71,77,81
5快速預覽整個循環python tools/make_loop.py <name> --preview(每隔 8 幀顯示一張)
6完整渲染 + 輸出 GIF + MP4 + 品質檢測python tools/make_loop.py <name>
7為每個動作製作連續截圖檢查,修正問題後重新渲染請見下方「連續截圖」
8將完成的檔案複製到 anymation/toy3d/videos/<name>/,然後傳送給 Pimbo

在 Pimbo 電腦上的耗時(RX 6800 XT)[M]:

  • EEVEE: 每個 1080x1080 影格約需 0.7 秒,因此 200 影格的循環大約需要 2.5 分鐘。
  • Cycles: 每個影格約需 10 秒,但視覺效果幾乎相同。僅在靜態圖片時使用:--engine cycles --samples 256 在 2400x1200 解析度下約需 20 秒。

連續截圖。 若要逐影格檢視某個動作:

ffmpeg -framerate 25 -start_number 56 -i out/<n>/frames/%04d.png -frames:v 30 -vf "crop=...,scale=260:-1,tile=6x5" -frames:v 1 strip.jpg

視覺風格簡介(詳細數據請見 references/LOOK.md)

  • 玩具比例。 1 單位 = 1 公尺,Claude 約 9 公分寬。真實攝影機的景深(70 mm,f/4.5-7)即可自然產生微縮模型的模糊效果。
  • 紙張材質。 每個立體物件都使用 paper(...):霧面色彩、纖維凹凸、柔和斑點。具有斜角的物件會自動應用白色邊緣材質(box、prism、disc)。
  • 色彩。 色彩空間轉換使用 AgX 搭配 Punchy 風格。白天場景曝光值 -1,夜晚場景約 -0.35。
    • 受光面:Claude 受光面的色彩接近參考資料(我們的是 #DA8D6C,參考資料為 #EC815B)。
    • 亮度:白天影格的平均亮度為 120-140(參考資料範圍 91-181)。
  • 燈光。 一盞暖色主光,高位且位於前方,使頂面比正面更亮。加上微弱的冷色補光和一盞暖色邊緣光。發光物體(火焰、星星、煙霧)使用 flame_mat 和 no_shadow。
  • 攝影機。 在循環動畫中保持靜止(參考資料只在需要剪輯或推近鏡頭時移動攝影機)。
    • GIF 使用正方形 1080 解析度。
    • 英雄圖片是寬幅的,使用 shift_x 將主體推到畫面三分之一處。

Claude 角色簡介(詳見 references/CHARACTERS.md)

claude = Claude('claude', loc)

然後每影格呼叫:

claude.pose(s, hop, pitch, roll, yaw, arm_l, arm_r, eyes, eye_big, eye_look, loc)
  • 眼睛: sq、happy(^ ^)、line(- -)、squeeze(> <)、dot(. .)、sad。
  • 道具: 手持的道具會父子級聯到 claude.hand(side)。
  • 揮手: 揮動的手臂必須是面向攝影機的那一隻。

網頁作品:即時眼睛與 3D 模型

  • 即時眼睛。
    1. 使用 --eyes-off(和用於剪影的 --transparent)進行渲染: python tools/make_loop.py claude_pose --transparent --eyes-off --tag _noeyes。渲染器會隱藏眼睛,並寫入 eyes.json:包含每隻眼睛的像素中心點,以及以每毫米像素數為單位的人臉軸線。
    2. 執行 python tools/web_eyes.py <noeyes.png> <eyes.json> <out_dir> --ink-from <render with eyes>。它會產生 index.html 以及一個單檔 <dir>_un_archivo.html。
    3. 該頁面的功能:
      • 眼睛是在臉部平面上繪製的 SVG 形狀,因此在傾斜的臉部上也能保持正確的透視。
      • 眼睛會以欠阻尼彈簧運動跟隨滑鼠游標,並每隔 2.5-5.5 秒眨眼一次。
      • 游標靠近時顯示 ^ ^,按壓時顯示 > <。
      • 點擊時會有擠壓拉伸彈跳效果(但使用 --hero 時不會有此效果,--hero 會保持完整圖片靜止)。
    4. 已在 Chrome 瀏覽器中透過 playwright 進行測試(滑鼠左移、右移、上移、下移、靠近、按壓、放開):未發現控制台錯誤。
  • 3D 模型。 執行 blender -b --factory-startup --python tools/claude_glb.py -- <out.glb> [--eyes sq]。它會輸出一個約 27 KB 的 GLB 檔案,寬度約 9 公分,已重新匯入並檢查過。
  • 場景與 --eyes-off。 在建立時設定 Claude 姿勢的場景,必須在 pose(f) 中再次設定姿勢;--eyes-off 只在該函數內生效(請參考 stills/director_hero 範例)。

品質檢測門檻(tools/qa_loop.py)

失敗(FAIL):

  • 影格數量錯誤。
  • 存在接縫:從最後一個影格到第一個影格的變化量大於正常步數的第 90 百分位數。

警告(WARN):

  • 存在連續相同的影格(死幀停頓)。
  • 運動量低於平均亮度的 0.8%。測量值 [M]:參考資料 r2/r3/r4 為 1.65/1.97/1.07%,claude_isla 為 0.89%,claude_fogata 為 1.66%。

品質檢測無法評斷品味、表演或構圖。這些需要透過肉眼在靜態預覽和連續截圖上檢查。

已知錯誤(references/KNOWN_ERRORS.md)

那些會導致需要重新渲染的錯誤:

  • 手臂舉起超過約 70° 時會隱藏在身體側面。
  • 明亮的發光體在 AgX 色彩空間下會變成白色:請使用 flame_mat。
  • 側面主光會使得正面變暗。
  • 使用絕對灰階數值測量的夜晚場景會顯得「太安靜」。
  • 弧形的背景板如果弧度太窄,會露出其邊緣。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相關技能