Communitygithub.com

MSP — Manim 風格與協定

指導 AI 代理如何規劃、建置或剪輯「MSP — Manim 風格與協定」的具體流程,確保產出可直接使用的文案或腳本。

MSP — Manim 風格與協定 是什麼?

MSP(Manim 風格與協定)是一套專為 AI 代理設計的生產級技能規範,旨在生成乾淨、有組織、流暢變形的 Manim 動畫。此技能支援 Manim Community Edition (ManimCE) 0.18 以上版本,並強制執行從專案結構、顏色字體、變形協定到時間節奏等一系列專業標準。代理會遵循「0. 首要指令」——確保每個場景看起來都像出自專業動畫工作室,而非學生習作。透過主題檔統一管理顏色與字體、使用 TransformMatchingTex 等變形工具避免突兀切換、並遵守嚴格的時間與速率函數規則,MSP 能讓 AI 代理預設產生流暢、連貫、高品質的動畫輸出,大幅降低人工修正需求。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Frqme21/MSP-Manim-Style-protocol/tree/HEAD/v1

在你喜歡的 AI 中提問

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

說明文件

MSP — Manim 風格與協定 是做什麼的?

適用於 AI 生成 Manim 動畫的生產級技能規範

版本: 1.0
目標: Manim Community Edition (ManimCE) ≥ v0.18
目的: 讓任何 AI 系統預設就能生成乾淨、有組織、流暢變形、工作室/生產品質的 Manim 動畫——而非例外。

0. 首要指令

你寫的每個場景都必須看起來出自專業動畫工作室,而不是學生習作。如果有選擇模糊之處,選擇更流暢、更乾淨、更用心的選項——永遠不要選最偷懶的預設值。

在編寫任何程式碼之前,默默地在心中檢查這份清單:

  1. 這個場景要傳達的一個核心概念是什麼?
  2. 視覺層次是什麼(眼睛應該先看哪裡、接著看哪裡、最後看哪裡)?
  3. 我使用的色調和字體是什麼?整個專案是否一致?
  4. 每個物件要如何進入、轉換和退出——任何東西都不該沒有動畫動詞就直接「出現」或「消失」。
  5. 場景的節奏(總 run_time 預算)是多少?

1. 環境與版本鎖定

除非使用者明確要求 3b1b 風格的 ManimGL,否則一律預設使用 Manim Community Edition,而非 ManimGL。

from manim import *
  • CLI 二進位檔案: manim (非 manimgl)
  • 建立動詞: Create() (非 ShowCreation())
  • 數學渲染: MathTex(r"...") (非 Tex(R"..."))

切勿混用 API。 如果某段程式碼在非 MovingCameraScene/ThreeDScene 的情況下使用了 self.camera.frame,請將其標記——這是 ManimGL 語法滲入的徵兆。


2. 專案檔案結構

對於任何超過單一簡單場景的專案,強制採用以下結構——絕不把所有東西都塞進一個龐大的單一檔案:

project/
├── manim.cfg              # 鎖定渲染設定 (請見 §9)
├── theme.py               # 顏色、字體、常數 (單一事實來源)
├── helpers.py             # 可重複使用的 mobject 建構器 / 佈局函數
├── scenes/
│   ├── 01_intro.py
│   ├── 02_derivation.py
│   └── 03_outro.py
└── assets/                # svg、圖片、音訊

theme.py 範例 (對於多場景專案,務必建立一個):

from manim import *

# ---- 色調 ----
BG_COLOR      = "#0E0E12"
PRIMARY       = "#58C4DD"   # manim 預設藍色,或品牌色
SECONDARY     = "#FFD166"
ACCENT        = "#EF476F"
TEXT_MAIN     = "#F5F5F5"
TEXT_MUTED    = "#8A8A8F"
SUCCESS       = "#06D6A0"

# ---- 字體排印 ----
FONT_MAIN = "Helvetica"      # 或專案特定字體
FONT_MONO = "JetBrains Mono"

# ---- 時間常數 ----
T_FAST   = 0.5
T_NORMAL = 1.0
T_SLOW   = 1.8
LAG      = 0.08   # 分組揭示的預設 lag_ratio

config.background_color = BG_COLOR

每個場景檔案都從 theme.py 匯入。一旦主題檔案存在,絕對不要內聯硬編碼十六進位顏色或魔術 run_time 數字——這是不專業、不一致輸出的頭號標記。


3. 視覺設計標準

3.1 顏色規則

  • 每個專案最多 4–5 種顏色(1 種背景、1–2 種主要色、1–2 種強調色)。顏色太多會顯得雜亂/業餘。
  • 使用顏色要有語義:相同的顏色在整個影片中代表相同的意義(例如,藍色始終代表「已知」,紅色始終代表「未知」)。
  • 背景幾乎不該是純黑色 (#000000) 或純白色——使用柔和的接近黑色 (#0E0E12) 或柔和的米白色,以減輕眼睛疲勞並營造「工作室」氛圍。

3.2 字體排印規則

  • 使用 Text() 顯示 UI 標籤、標題、字幕——速度快,無需 LaTeX 依賴。
  • 使用 MathTex() 顯示所有數學符號——絕不使用 Text() 偽造數學。
  • Tex() 僅用於混合散文+數學的 LaTeX 區塊。
  • 透過主題常數全域設定 font=;絕不要讓字體選擇在不同場景間變化。
  • 標題慣例:.to_edge(UP)、粗體、跨場景使用一致的字體大小(例如 40pt)。

3.3 佈局規則

  • 遵守三分構圖法——避免預設將所有東西置中對齊;有意地使用 .to_edge()、.shift()、.next_to()。
  • 保持一致的邊距(buff 值)——定義一個 MARGIN = 0.75 常數,並在每次呼叫 .to_edge(..., buff=MARGIN) 時重複使用。
  • 將相關物件分組為單一 VGroup,並對群組進行定位和動畫處理,而不是散亂的個別 mobject——這能保證在後續的任何轉換過程中對齊保持正確。
  • 始終對群組呼叫 .arrange() 或 .arrange_in_grid(),而不是手動計算座標——手動座標計算很脆弱,是後續編輯時佈局出問題的首要原因。

4. 變形與轉換協定

這是「流暢變形」動畫的核心——高階解說影片的標誌性外觀。

4.1 規則:絕不剪輯,總是變換

如果一個物件概念上變成了另一個物件(方程式重新排列、形狀變成另一個形狀、標籤更新),絕對不要使用 FadeOut + FadeIn 作為兩個無關的 mobject——這看起來就像跳剪。始終使用一種變換家族:

情境正確工具
方程式重新排列,項次保留TransformMatchingTex(old, new)
形狀變形成不同形狀Transform(old, new) 或 ReplacementTransform(old, new)
Mobject 群組重組(例如項目符號列表 → 圖表)TransformMatchingShapes(old_group, new_group)
一個物件在場景圖中明確取代另一個物件ReplacementTransform (將 self.mobjects 中的舊物件替換為新物件)
淡出同時暗示連續性(例如殘影/疊加)FadeTransform(old, new)

關於 TransformMatchingTex 的協定細節: 始終以一致的字串分組方式(將相同的 LaTeX 片段放在不同的 {} 群組中)建立兩個 MathTex mobject,以便 Manim 能夠匹配相同的符號——這正是讓項次視覺上「滑入」新位置而不是交叉淡化的關鍵。

eq1 = MathTex("a", "+", "b", "=", "c")
eq2 = MathTex("c", "=", "a", "+", "b")
self.play(TransformMatchingTex(eq1, eq2), run_time=1.2)

4.2 規則:對單一屬性變形使用 .animate

對於一個 mobject 上的單一連續屬性變化(位置、縮放、顏色、旋轉),偏好使用 .animate 語法——它更乾淨,且 Manim 會自動插值淨變換:

self.play(square.animate.shift(RIGHT * 2).scale(1.5).set_color(ACCENT), run_time=1.0)

注意事項(非常重要,避免 AI 幻覺錯誤): 鏈式 .animate 呼叫會插值最終淨狀態,而不是每個中間步驟的順序。絕不要鏈式依賴中間結果的 .animate 呼叫(例如 .animate.move_to(X).rotate(angle_depending_on_position))——應將其拆分為單獨的 self.play() 呼叫。

4.3 規則:對連續/依賴運動使用 Updater

每當一個物件的狀態必須連續追蹤另一個物件時(標籤跟隨點、數值顯示追蹤 ValueTracker),使用 add_updater,絕不要手動對每個影格重新 play:

tracker = ValueTracker(0)
label = DecimalNumber(0).add_updater(lambda d: d.set_value(tracker.get_value()))
dot = Dot().add_updater(lambda m: m.move_to(axes.c2p(tracker.get_value(), f(tracker.get_value()))))
self.add(label, dot)
self.play(tracker.animate.set_value(5), run_time=3, rate_func=linear)

一旦物件的依賴階段結束,務必 remove_updater(或使用 always_redraw 進行更乾淨的從頭重新計算邏輯),以避免在長場景後期出現過時的 updater 錯誤。


5. 時間、節奏與緩動協定

5.1 預設速率函數政策

  • 預設(不要覆寫):smooth——S 曲線緩入/緩出。用於 90% 的動畫——方程式揭示、形狀建立、標準移動。
  • linear:對於任何描繪字面意義上恆定速率物理運動的內容——軌道點、勻速向量、時鐘指針、與實際經過時間綁定的進度條——是強制性的。
  • rush_into / rush_from:用於強調進入/退出,當某物應感覺像卡入到位或發射出去時。
  • there_and_back / there_and_back_with_pause:用於 Indicate 風格的注意力脈衝,絕不用於永久狀態變化。
  • ease_out_bounce / ease_out_elastic:僅保留用於俏皮、非正式的內容——永遠不要在正式的數學/科學推導中使用,這看起來不專業。

5.2 時間預算規則

  • 保持單個 run_time 在 0.4s 到 3s 之間。低於 0.4s 會顯得刺眼;高於 3s(無敘事理由)則會拖沓。
  • 標題/章節標題進入:0.8–1.2s。
  • 方程式/圖表變換:1.0–1.5s。
  • 強調脈衝(Indicate、Flash、Circumscribe):0.5–0.8s。
  • 攝影機移動(move_camera、self.camera.frame.animate):1.5–3s——比這更快的攝影機移動會讓人不適。
  • 在每個主要揭示之後,刻意插入 self.wait(0.3–1.0) 的呼吸空間——絕不要連續不間斷地鏈式呼叫 self.play();這會讓觀眾不堪負荷。

5.3 組合協定

  • 同時但獨立的事件 → 單個 self.play(AnimA, AnimB, ...) 呼叫。
  • 同時但有交錯開始(例如 6 個項目符號點依次但重疊出現)→ LaggedStart(*anims, lag_ratio=0.15)。
  • 嚴格順序、依賴的事件 → Succession(*anims) 或使用單獨的 self.play() 呼叫。
  • 列表/網格揭示(項目符號、形狀網格)→ 始終使用 LaggedStartMap(FadeIn, group, lag_ratio=0.08, shift=UP*0.3),而不是同時單個 FadeIn(group)——交錯是讓群體進入感覺有機而非機械化的關鍵。

6. 場景與程式碼組織協定

6.1 建構方法形狀

始終透過註解或輔助方法將 construct() 分解為清晰劃分、有名稱的階段——絕不要使用一個超過 100 行不間斷的區塊:

class DerivationScene(Scene):
    def construct(self):
        self.setup_title()
        self.show_initial_equation()
        self.derive_steps()
        self.highlight_result()
        self.cleanup()

    def setup_title(self):
        self.title = Text("Deriving the Quadratic Formula", font=FONT_MAIN).to_edge(UP)
        self.play(Write(self.title), run_time=T_NORMAL)
        self.wait(T_FAST)

    def show_initial_equation(self):
        ...

對於長影片,分割成多個場景類別(每個邏輯部分一個),而不是一個巨大的 construct()——從而能夠透過 -n 進行目標重新渲染和平行迭代。

6.2 Mobject 建構協定

  • 將複雜的自訂視覺元素(圖表、圖形、圖示)建構為 helpers.py 中獨立的函數,這些函數返回一個 VGroup,而不是在 construct() 中內聯建立:
# helpers.py
def make_neuron(radius=0.3, color=PRIMARY) -> VGroup:
    circle = Circle(radius=radius, color=color, fill_opacity=0.8)
    label = Text("n", font_size=20).move_to(circle)
    return VGroup(circle, label)
  • 始終為 mobject 賦予有意義的名稱(title、eq_initial、graph_group)——絕不留下未引用、匿名、之後需要變異或變換的字面值。
  • 對於任何具有重疊層的場景,明確使用 z_index(一旦存在超過 2 個層,不要僅依賴新增順序)。

6.3 風格/語法檢查規則

  • 變數/方法使用 snake_case,Scene 子類別使用 PascalCase。
  • 程式碼中每個動畫「節拍」之間留一個空行,以提高可讀性——程式碼結構應視覺上反映影片的節奏。
  • 不使用裸的魔術數字表示顏色/位置/時間——始終引用 theme.py 常數。
  • 為輔助函數添加型別提示(def make_axes() -> Axes:),以便在較大專案中維護。

7. 合成與攝影機協定 (2D 與 3D)

2D

  • 每當影片需要在 2D 中平移/縮放時(例如對焦圖表的子區域),使用 MovingCameraScene——透過 self.camera.frame.animate.move_to(...).set(width=...) 進行動畫處理,始終帶有明確的 run_time。

3D

  • 子類別化 ThreeDScene。
  • 在專用的設定步驟中使用 self.set_camera_orientation(phi=70*DEGREES, theta=-45*DEGREES, zoom=1) 設定初始方向——除非有意為之,否則從不使用預設方向。
  • 對於觀看者應感知為運動的任何攝影機重新定位,使用 self.move_camera(phi=..., theta=..., run_time=2.5)——絕不在場景中途透過 set_camera_orientation 進行跳躍剪輯。
  • 在旁白下進行緩慢待機旋轉時,使用 self.begin_ambient_camera_rotation(rate=0.15);在後續任何故意的 move_camera 之前,務必配對使用 self.stop_ambient_camera_rotation()。
  • 無論攝影機角度如何,都必須保持可讀的 HUD/標籤/標題 → self.add_fixed_in_frame_mobjects(label)。
  • 應追蹤 3D 物件但保持可讀的標籤 → self.add_fixed_orientation_mobjects(label)。
  • 在迭代期間保持 3D 表面 resolution 元組較低(例如 (24,24));僅在最終生產渲染時才提高——這純粹是性能/工作流程規則,而非視覺規則。

8. 強調與注意力協定

絕不要讓關鍵結果在視覺上與輔助內容相同。在揭示場景的「回報」(最終方程式、關鍵見解、結果)後,僅應用一種強調技術——不要堆疊超過一種,否則會顯得慌亂:

  • Circumscribe(mobject, color=ACCENT, run_time=1.2) —— 在其周圍繪製一個形狀。
  • Indicate(mobject, scale_factor=1.15) —— 簡短的脈衝縮放 + 顏色閃爍。
  • Flash(point, color=ACCENT) —— 徑向爆發,適用於特定的座標/交點。
  • mobject.animate.set_color(ACCENT) 結合輕微縮放 —— 用於永久重新著色,表示「這就是答案」。

9. 渲染與匯出協定

9.1 鎖定設定檔(提交此檔案——絕不依賴臨時標誌進行最終交付)

manim.cfg:

[CLI]
quality = production_quality
preview = False
background_color = "#0E0E12"
output_file = {scene_name}
frame_rate = 60
pixel_height = 1080
pixel_width = 1920

9.2 工作流程階段(始終遵循此順序,絕不首先渲染最終品質)

  1. 草稿階段:manim -pql scenes/02_derivation.py DerivationScene —— 快速迭代,檢查邏輯/時間。
  2. 抽查階段:manim -pqh -s scenes/02_derivation.py DerivationScene —— 單影格高品質檢查構圖/顏色。

...

[翻譯因長度截斷]

相關技能