Vos プログラムの作成

VosConfigJsonファイル（宣言的なアニメーション設定）を生成します。これはVosエンジン（github.com/vosjs/vos、MITライセンス）上でThree.js + GSAP方言のアニメーションにコンパイルされます。プレビューがそのままレンダリング結果となります：設定が同じであれば、すべてのマシンで同じフレームが生成されます。

ワークフロー

プロンプトを解析する：アニメーションのコンセプト、雰囲気、色、参照画像を特定します。
アプローチを設計する：カメラプリセット、マテリアル、エフェクト、アニメーション戦略を選択します（以下のカテゴリガイドを参照）。
設定を生成する：完全で有効なVosConfigJsonを作成し、<ケバブケース名>.jsonとしてプロジェクトの設定保存先に書き込みます。
ローカル検証する（下記参照）：その後レンダリングまたはプレビューします。

ユーザーが画像を提供した場合は、そのビジュアルスタイル（色、雰囲気、構図、照明）を分析し、それらの特性をシーンに反映させます。

ローカルでの検証とレンダリング

npm i @vosjs/core        # コンパイラ + リント
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('compiles clean') })"

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.studioでの微調整）を希望し、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以下、1ネットワークあたり1日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。

重要なルール

DO（必ず行うこと）

関数は有効な JavaScript 文字列 であること — TypeScriptは不可（as、型アノテーションは禁止）
Three.js には ctx.THREE、GSAP方言には ctx.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コールバックを使用する

DON'T（やってはいけないこと）

関数文字列内で ${} テンプレートリテラルは禁止 — コンパイル時に評価されるため。文字列連結を使用すること。
エスケープされたバッククォートは禁止 — シェーダーはインライン文字列または1行の連結で記述する
個々のトゥイーンに repeat: -1 は絶対に使用しない — ループはプレーヤーが処理するため；これにより持続時間の追跡が壊れる
要素にCSSスタイルの style オブジェクトや textContent を使用しない — 要素はWebGLプレーンです
外部インポートは禁止 — すべては ctx 上にあります（THREE、gsap、ローダー、ユーティリティ）
requestAnimationFrame や setTimeout は禁止 — onUpdate コールバックを使用する
フレームパスでの Date.now() / Math.random() は禁止 — 決定論性が契約です；すべてをタイムラインの時間と ctx.data から導出すること
新しい設定での onFrame は禁止 — すべてのフレームごとのロジックは onUpdate に記述する

パラメータとルックス（リミックス可能にする）

config.params で2〜4つのノブを宣言します — エディタはこれらをライブコントロールとしてレンダリングし、他のエージェントはコードに触れずにプログラムを再調整できます。各パラメータはプログラムが読み取る ctx.data キーを文書化します：

"params": [{ "key": "hue", "label": "色相", "kind": "number",
             "min": 0, "max": 1, "default": 0.6,
             "hint": "すべての色を色相環上でシフトします",
             "unit": "°", "group": "色", "order": 1 }]

kinds: number（最小/最大/ステップ） | color | select（オプション） | 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；5k〜20kのPoints、100〜500のInstancedMesh；すべてを破棄すること。

カテゴリ選択ガイド

コンセプト	カメラ	テクニック
シェーダーアート / フラクタル	`fullscreen`	ShaderMaterial + ユニフォームトゥイーン
3Dオブジェクト	`perspective`	メッシュ + マテリアル + ライト
アイソメトリック / フラット	`orthographic`	InstancedMesh + 計算された位置
テキストショーケース	`perspective` または `fullscreen`	TextGeometry（3D）または elements（2D）
ガラス / 屈折	`perspective`	MeshPhysicalMaterial + HDR環境マップ
パーティクル	`perspective`	Points + シェーダーまたは InstancedMesh
ミックスメディア	`perspective`	3Dシーン + elements配列

Vos アニメーションプログラム作成 (vos-authoring)