Vos 動畫程式創作
您將生成 VosConfigJson 檔案 — 一種宣告式動畫配置，可編譯為在 vos 引擎 (github.com/vosjs/vos，MIT 授權) 上執行的 Three.js + GSAP 方言動畫。預覽即為渲染結果：同一份配置在每台機器上 都會產生相同的影格。
工作流程
- 解析提示：識別動畫概念、氛围、顏色以及任何引用的圖片。
- 設計方法：選擇攝影機預設值、材質、效果和動畫策略（請參閱下方分類指南）。
- 生成配置：在專案存放配置的位置，將完整且有效的 VosConfigJson 寫入
<連字號-命名.json>。 - 在本地端驗證（見下方），然後渲染或預覽。
如果使用者提供了一張圖片，請分析其視覺風格（顏色、氛围、構圖、光線），並將這些特質轉化到場景中。
在本地端驗證與渲染
npm i @vosjs/core # 編譯器 + lint 檢查
node -e "import('@vosjs/core/compiler').then(async m => { \
const cfg = JSON.parse(require('fs').readFileSync('my-config.json','utf8')); \
m.compileVosConfig(cfg); console.error('編譯通過') })"
compileVosConfig(config) 不得拋出錯誤 — 這是所有播放器和渲染伺服器
執行的同一個編譯器。若要進行視覺檢查，可以使用 CLI
（npm i -D @vosjs/cli）：
vos render my-config.json out.webm # 確定性影片渲染
vos still my-config.json out.webp --time 2.5
vos preview my-config.json # 本地端播放頁面
vos info my-config.json
分享以供預覽（無需帳號）
預設使用本地端渲染 — 除非使用者要求分享或託管，否則資料不會離開電腦。 當使用者想要看到它被託管（可播放的連結，在 vos.so 工作室進行微調） 但尚未配置 API 金鑰時，請使用可認領的推送：
vos push my-config.json --claimable --title "…"
# → claim: https://vos.so/claim/… 過期時間：<從現在起 72 小時>
# 沒有 CLI，或版本較舊？也可以透過普通的 HTTP 達成相同目的：
curl -s -X POST https://vos.so/api/claim \
-H 'content-type: application/json' \
-d '{"title": "…", "config": <VosConfigJson>}'
# → { "claimUrl": "https://vos.so/claim/…", "expiresAt": "…" }
將 claimUrl 交給使用者，切勿外流 — 它是唯一的參考憑證。
其有效期為 72 小時；未認領的作品將在此之後被刪除（如果過期可重新推送）。
認領會將該 vos 移動到使用者的資料庫中。如果已配置金鑰
（VOS_API_KEY 或 vos login），請優先使用 vos push —
使用金鑰的推送沒有過期時間。僅限程式，配置大小 ≤200KB，每個網路每天 5 次推送。
VosConfigJson 結構
{
"version": 2,
"duration": 8,
"scene": { "background": "#0a0a1a", "fog": { "type": "exp2", "color": 0, "density": 0.02 } },
"camera": { "preset": "perspective", "fov": 60, "position": [0, 2, 8] },
"postprocessing": [{ "type": "bloom", "strength": 0.8 }, { "type": "output" }],
"elements": [{ "type": "text", "id": "title", "content": "Hello", "position": "center", "font": { "size": 64, "color": "#fff" } }],
"setup": "async (ctx) => { ... return data }",
"createContent": "(ctx, setupData?) => { ... return { objects, refs, dispose } }",
"createTimeline": "(ctx, content, duration) => { ... return tl }"
}
完整欄位參考：references/schema-reference.md。每種主要類型的運作範例：references/examples.md。
關鍵規則
必須
- 函數必須是有效的 JavaScript 字串 — 不能使用 TypeScript（不能使用
as、型別註解） - 透過
ctx.THREE存取 Three.js，透過ctx.gsap存取 GSAP 方言，透過ctx.scene存取場景 createContent必須回傳{ objects: [...], refs: {...}, dispose: () => {...} }createTimeline必須回傳ctx.gsap.timeline({ paused: true })- 永遠包含能清理幾何體、材質、紋理的
dispose()方法 - 對著色器的
iResolution使用ctx.resolution.drawingBufferWidth/drawingBufferHeight - 為全螢幕著色器四邊形設定
mesh.frustumCulled = false - 在全螢幕 ShaderMaterial 上設定
depthWrite: false, depthTest: false - 使用後處理時，永遠將
{ "type": "output" }作為最後一個條目 - 將所有場景物件同時添加到
scene和回傳的objects陣列中 - 直接補間著色器參數：
tl.to(uniforms.iTime, { value: duration, duration, ease: 'none' }) - 對於逐影格邏輯（InstancedMesh 更新、攝影機計算），請使用補間上的
onUpdate回呼
禁止
- 函數字串中不能有
${}模板字面量 — 它們會在編譯時被求值。請使用字串串接。 - 不能有跳脫的反引號 — 將著色器撰寫為內聯字串，或使用單行串接
- 永遠不要在單個補間上使用
repeat: -1— 循環由播放器處理；這會破壞持續時間追蹤 - 不能有 CSS 風格的
style物件或元素上的textContent— 元素是 WebGL 平面 - 不能有外部匯入 — 所有東西都在
ctx上（THREE、gsap、載入器、工具函數） - 不能使用
requestAnimationFrame或setTimeout— 請使用onUpdate回呼 - 在影格路徑中不能使用
Date.now()/Math.random()— 確定性是合約；所有東西都應從時間軸的時間和ctx.data推導出來 - 新的配置中不能使用
onFrame— 將所有逐影格邏輯放在onUpdate中
參數與外觀（讓它可重混）
透過 config.params 宣告 2–4 個旋鈕 — 編輯器會將它們渲染為即時控制項，
其他 AI 代理可以在不接觸程式碼的情況下重新調整程式。每個參數都記錄了
程式會讀取的 ctx.data 鍵：
"params": [{ "key": "hue", "label": "色相", "kind": "number",
"min": 0, "max": 1, "default": 0.6,
"hint": "在色環上偏移每種顏色",
"unit": "°", "group": "顏色", "order": 1 }]
- kinds:
number(min/max/step) |color|select(options) |toggle hint：用一句話說明視覺上會改變什麼 — 請務必撰寫- 程式在其動畫邏輯中讀取它：
const d = ctx.data || {}; if (typeof d.hue === 'number') u.uHue.value = d.hue - 根據意圖命名旋鈕（
mood、drama、pace），永遠不要根據實作方式 （blurRadius）。每個旋鈕必須能明顯改變輸出 — 一個無效的旋鈕比沒有旋鈕更糟。
透過 config.presets 提供「外觀」 — 已命名的參數值組合（當程式有 4 個以上的參數時，提供 2–3 組）：
"presets": [{ "name": "鮮豔", "values": { "hue": 0.9, "speed": 2 } },
{ "name": "平靜", "values": { "hue": 0.3, "speed": 0.6 } }]
值必須引用已宣告的參數鍵，且型別須匹配。
伺服器端渲染注意事項
推送到 vos.so 的配置會在一個軟體 GL 叢集上進行預覽渲染：不能在傳輸材質上使用
THREE.DoubleSide（會導致硬體掛起），不能使用 dispersion（太慢），
且任何擷取的資源必須可存取且開放 CORS。這些限制僅適用於純本地端
且在真實 GPU 上的渲染。
設計原則
- 視覺衝擊：使用 bloom 產生發光效果（即使 0.3–0.5 也能提升質感）；發光材質 + bloom = 光源；exp2 霧（0.01–0.05）產生景深感；深色背景使色彩更突出；玻璃（傳輸 + HDR 環境貼圖）看起來高級；微妙的攝影機漂移增加生命力。
- 動畫品質：4–10 秒循環，10–30 秒敘事；
ease: 'none'用於恆定運動；power2.inOut/sine.inOut用於轉場；stagger 用於序列化揭示；在不同起始時間分層補間。 - 顏色：最多使用 2–3 種互補色；暖色主色調 + 冷色邊緣光；深色調（
0x0a0a1a、0x1a1a2e）用於背景。 - 效能：10 個以上相同物件使用
InstancedMesh；Points 使用 5k–20k，InstancedMesh 使用 100–500；清理所有資源。
分類選擇指南
| 概念 | 攝影機 | 技術 |
|---|---|---|
| 著色器藝術 / 碎形 | fullscreen | ShaderMaterial + 參數補間 |
| 3D 物件 | perspective | Mesh + Material + 燈光 |
| 等距/平面 | orthographic | InstancedMesh + 計算位置 |
| 文字展示 | perspective 或 fullscreen | TextGeometry (3D) 或 elements (2D) |
| 玻璃/折射 | perspective | MeshPhysicalMaterial + HDR 環境貼圖 |
| 粒子 | perspective | Points + 著色器或 InstancedMesh |
| 混合媒體 | perspective | 3D 場景 + elements 陣列 |