3D 動畫師
「做一個酷炫的 3D 影片」這個提示，通常只會產出灰暗、平淡光線、攝影機靜止不動的場景，因為模型在未經任何電影決策的情況下，只會使用預設值。此技能強制在編寫程式碼之前做出這些決策，並提供實作的基礎架構。
目標： 首次交付時無技術錯誤，只需幾次修訂即可完成的影片。重點不在於完美無瑕，而在於提供一個穩固、可修改的起點。能達成此目標的關鍵並非基礎架構，而是以下嚴謹的流程順序；絕對不可跳過任何步驟。
專案格式為 HyperFrames。關於構圖規則，請參考 hyperframes-core。
從哪個範例開始
| 需求 | 起始點 | 閱讀文件 |
|---|---|---|
| 人物、車輛、物體運動、動作、故事 | assets/example-street-film/ | references/motion.md |
| 旁白敘述、概念解說、產品介紹 | assets/example-chip-film/ | references/film-grammar.md |
| 兩者兼具 | 取街頭電影為基礎，再加入敘述語言 | 兩份文件皆讀 |
務必閱讀： references/materials.md, references/craft.md, references/sound.md。
保持架構，根據主題重新撰寫內容。 不要將範例中的街道、球體或晶片直接套用到新專案中。若有參考影片，請學習其技術，但切勿複製文字與剪輯。scene.js 的章節依序為：場景、演員、編舞、攝影機、視覺效果。
影片的必要條件
缺少任何一項，成品就會像「3D 展示」而非電影：
- 真實比例： 1 單位等於 1 公尺。鏡頭模糊、陰影與紋理才能正確呈現。
- 豐富且具深度的場景： 包含前景、中景、背景及更遠處。至少 25 個物件。主角需分件建模。
- 自然光： 有動機的主光 +
skyDome。沒有陰影的物件會像是漂浮在空中。 - 正確的材質： 每個表面都使用
M.*或同等嚴謹的材質。沒有任何表面是純色。 - 一個故事與動機： 每個動作都有其理由。大約每 3 秒發生一個新事件。
- 鏡頭語言： 每個鏡頭只有一個任務。鏡頭焦距與運動都是為了服務這個任務。
- 聲音： 真實錄音、音樂、旁白。每個聲音都必須與畫面中的事件相關聯。
工作流程
1. 規劃 (shot-plan.md)
在撰寫任何程式碼之前：先定義一句話訊息、主角、場景列表、燈光構想、色板、材質列表以及分鏡表。
| 時間 | 事件 | 攝影機 (焦距、運動) | 聲音 | 字幕 |
|---|---|---|---|---|
| 9.1–10.2 | 球從孩子手中滑落 | 46mm，低角度，f/3.2 | 短促的吸氣聲 | 沒人在看那顆球。 |
若未指定格式，預設為 16:9 1920×1080。若為直式 Reels，則設定為 1080×1920 並重新規劃構圖。若使用者已提供主題，無需等待批准，簡短展示規劃後即可繼續。若某項決策會根本性地改變影片（例如格式、語言、要求擬真人物），則需先提問。
2. 設定專案
npx hyperframes init <專案名稱> --resolution landscape --non-interactive
將 assets/rig/ 下的所有檔案，以及所選範例的檔案，複製到專案根目錄。
3. 先聲音，後影像
時間長度由對話決定，攝影機的時機點依賴於此。先設定聲音。
node <技能資料夾>/scripts/make-sfx.mjs assets/sfx <時長-秒>
node <技能資料夾>/scripts/build-audio.mjs .
腳本會輸出 voiceToMusicDb、overrun、voiceClash、overlap 以及混音電平。若以錯誤碼結束，請修正時間。關於來源查找、授權與混音，請參考 references/sound.md。若找不到合適音樂或授權不符，可使用 scripts/make-music.mjs 從程式碼生成基本的背景音樂。街頭電影的錄音檔案不包含在技能中，列表請見 assets/example-street-film/SOURCES.md。首次安裝時：
py -3.12 -m venv "%USERPROFILE%\.cache\3d-animator-venv"
"%USERPROFILE%\.cache\3d-animator-venv\Scripts\python" -m pip install kokoro-onnx soundfile faster-whisper "av<16"
將 HYPERFRAMES_PYTHON 環境變數指向此 python 執行檔。Kokoro 不支援土耳其語：若需土耳其語，需在使用者允許下從其他供應商生成語音，並放置為 voice/NN.wav 及相同文字的 voice/NN.txt。腳本不會重新生成這組檔案。
4. 場景
| 工具 | 功能 |
|---|---|
createFilm({canvas, width, height, fps, samples, bloom, environment, background}) | 渲染管線 |
film.setShots([...]) | 鏡頭列表；每個 at 代表一個剪接。track: (t) => ({pos, look, lens, fstop, focus, roll}) 用於跟蹤移動主體 |
film.setKeys([...]) | 無剪接的單一攝影機 |
film.onUpdate(t => ...) | 物件與角色運動。每個子影格呼叫一次 |
film.onFrame(T => ...) | 燈光、look、模式切換。每個影格呼叫一次 |
film.look | exposure、saturation、contrast、blackPoint、lift、shadowTint、midTint、highlightTint、flash、grain、vignette、aberration、fade、invert、bloom、stylize |
film.skyDome、film.softLight、film.skyBackdrop、film.bakeEnvironment | 自然光與反射 |
film.mirrorFloor(mesh) | 用於濕地面與水面的真實反射 |
film.sunThroughBlinds、film.shaft、film.dust、film.burst、film.sparks、film.screen、film.wire | 特效與細節 |
M.*、skinned、boxUV | 材質 (references/materials.md) |
createCharacter、walker、createCar、driver、createBicycle、rider、loadRigged | 演員 (references/motion.md) |
speedProfile、groundPath、bounces、springTrack、track、noise1、rng、EASE | 運動輔助工具 |
addCaptions(tl, el, LINES) | 逐字字幕 |
不變的法則： 所有可見的事物都必須是時間的純函數。不要寫 rotation.y += 0.01，要寫 rotation.y = t * 0.6。影格可能會以隨機順序被請求多次。禁止使用 Date.now()、performance.now()、requestAnimationFrame 以及無種子的 Math.random。
5. 視覺檢查
將 SAMPLES 設為 4，並擷取影片中每一「拍」的影格。至少擷取 15 個影格。使用 setTextureScale(SAMPLES < 16 ? 0.5 : 1) 可以大幅縮短測試時間，因為每個渲染執行緒都會從頭生成所有紋理：
npx hyperframes check
npx hyperframes snapshot --at <t1>,<t2>,... --timeout 240000
若發生衝突，使用 --angle top。SAMPLES 在 1–4 時，天空光與對焦會不準確：陰影會過硬，對焦會呈點狀。請在 16 取樣時下材質與燈光的最終決定。
打開影格仔細檢查。材質： 凹凸貼圖是否過度？是否有拉伸？每個表面都有紋理嗎？構圖： 主體或頭部被裁切了嗎？每個鏡頭的任務是否清晰可讀？燈光： 方向、接觸陰影、眩光。運動： 腳部滑動、互相穿模、物體懸空。文字： 字幕在淺色背景上是否清晰可見？
若有參考影片，將相同時間點的影格並排比較 (scripts/look-stats.mjs 可提供數值色調比較)。參考影片的分析方法請見 references/film-grammar.md。
6. 草稿、掃描、修正
npx hyperframes render --quality draft --output draft.mp4
node <技能資料夾>/scripts/qa-film.mjs draft.mp4 --script script.json --whisper <python> --earshot <python>
掃描器會將影格輸出為 qa/sheet-*.jpg (每秒 4 個影格)，並回報黑畫面、凍結、單影格閃爍、音量、無法聽清的字詞以及 earshot 報告。請逐一檢查所有頁面。 即使機器報告無異常，錯誤通常仍會在那裡顯現。然後，將每個特寫鏡頭以全尺寸開啟 (references/materials.md，逐影格檢查)：在小縮圖上看起來乾淨的影格，放大後通常不然。此類影片中的大多數錯誤，只有這樣才能被發現。
在切換到最高品質之前，必須修正所有發現的問題。僅重新渲染有問題的片段：
npx hyperframes render --quality draft --start 18 --end 21 --output 片段.mp4
7. 最終輸出
將 SAMPLES 設為 24–32。以街頭電影範例的規模為基準，單一場景在 RTX 4060 上約需數分鐘；若摘要行中顯示 software gpu，則耗時會大幅增加，需事先告知使用者。
npx hyperframes render --quality delivery --output final.mp4
在最終影片上重複掃描程序，因為低 SAMPLES 可能會隱藏對焦錯誤。若無 earshot，需請求使用者允許安裝 (約需 1–3 GB)。請注意，PyPI 上的 earshot 是另一個不同的套件；正確的來源是 github.com/Leonxlnx/earshot。在 Windows 上，請將虛擬環境安裝在路徑較短的地方，因為 torch 在長路徑下會出現問題。
交付
告知使用者：你做了什麼、你檢查了什麼、你無法檢查什麼，以及還有哪些遺漏。列出所有使用的聲音與音樂來源及其授權。即使報告分數很高，也不代表 launch-grade 影片就是好看的。品味與旁白的自然度仍屬於使用者。
修訂
當使用者要求修訂時：
- 將意見轉化為計畫： 在哪個鏡頭？什麼問題？應該如何呈現？若不明確，則做出最可能的解釋並告知使用者，不要對每個意見都提問。
- 修改正確的地方： 材質在
M.*，攝影機在setShots，時間由單一常數控制 (如BRAKE_T)，色調在film.look，聲音在script.json。所有依賴於同一個常數的元素會一起變動。 - 僅渲染修改的部分： 使用
--start與--end參數。如果只修改聲音，無需重新渲染畫面 (references/sound.md)。 - 將修改後的片段與修改前的版本並排顯示， 獲得使用者確認後再進行完整渲染。
- 將學到的教訓寫入技能中： 若某種錯誤類型再次發生，請將其記錄到此文件或相關的參考文件中。
擬真人物：參考 + AI 影片
此類影片將作為 AI 影片生成工具的參考，最終畫面由該工具生成。此流程尚未經過端到端的完整測試；首次使用時，請先用單一鏡頭測試並向使用者展示結果。
- 僅建立 Blocking (基本佈局) ： 構圖、攝影機運動、誰在哪裡、何時出現。無需在角色細節和精細材質上花費時間。
- 每個鏡頭獨立輸出： AI 工具在處理短片段時表現得更穩定。使用
--start與--end逐個鏡頭渲染。關閉字幕；將 grain、aberration 和 vignette 設為零。這些工具可能會將文字與特效誤認為是真實畫面。 - 鎖定外觀： 首先將每個鏡頭的第一個影格轉換為擬真圖像。在所有鏡頭中，保持角色與場景參考的一致性，獲得使用者確認後再進行影片生成。
- 預先告知成本： 說明你將使用哪個工具、用於多少個鏡頭，以及預估的信用點數花費，並獲得使用者同意。請即時查詢所使用工具的當前定價，不要預設已知。
- 檢查： 檢查全尺寸的影格與剪接點：臉部、手部、招牌與標誌上的文字、鏡頭間的服裝變化。若動作偏離了原始編舞，請降低轉換強度。
- 在此完成音訊： 聲音與字幕仍透過
script.json在此管道中處理。檢查生成片段的實際長度，若長度有變，則調整聲音的時間點。
限制條件
必須在一開始就告知使用者，而非最後：
- 人物為風格化呈現： 品質約為動畫電影水準。不包含照片擬真度、臉部表演或口型同步。特寫鏡頭會顯得突兀。若需要擬真人物，請使用上述的參考流程；若為無人物影片，可將主角設定為物體或車輛，並讓人物保持遠景。
- 物理是藝術指導的： 物理效果是根據故事需求編寫的，並非真實模擬。不包含布料、毛髮或流體模擬；水面效果使用粒子系統模擬。
- 程式生成的合成語音聽起來就是合成語音。 真實錄音需要取得授權。
- 土耳其語旁白 需要外部提供聲音來源。
交付
告知使用者：你做了什麼、你檢查了什麼、你無法檢查什麼，以及還有哪些遺漏。列出所有使用的聲音與音樂來源及其授權。
修訂
(內容與上述相同，此處省略以避免重複)
擬真人物：參考 + AI 影片
(內容與上述相同，此處省略以避免重複)
限制條件
(內容與上述相同，此處省略以避免重複)