EffectCraft — エージェント操作
EffectCraft はネイティブな Rust 製モーション・グラフィックス / VFX コンポジター（After Effects クラス）で、エージェント・インターフェースは組み込み済みです。すべての操作は、id を持つコマンドとして実行されます。GUI、メニュー、CLI、制御チャンネル、MCP サーバーはすべて同一のエンジンを駆動します。Windows 上の 0.17.0 で検証済みです。
マシンと環境のパス
| プラットフォーム | バイナリ | CLI | デフォルトデータディレクトリ |
|---|---|---|---|
| Windows | C:\Program Files\EffectCraft\effectcraft.exe | C:\Program Files\EffectCraft\effectcraft-cli.exe | %LOCALAPPDATA%\EffectCraft（ディスクキャッシュ） |
| Linux | /usr/bin/effectcraft | /usr/bin/effectcraft-cli | ~/.local/share/effectcraft |
- 制御ポート:
--control <port>またはEFFECTCRAFT_CONTROL_PORT（トークン不要 — FilmCraft と異なり、ブリッジは平文のループバック接続を受け入れます） - コマンド数: 55 の名前空間に 734 個（ヘッドレスコンテキスト初期状態で 439 個有効。残りは選択／アクティブコンポ／ツールモードが必要）
- エフェクト数: レジストリに 307 個（
list_effects）; 149 フォントファミリー（list_fonts）
メンタルモデル
- プロジェクト（
.ecproj）はアイテムを保持します:Composition,Folder,Solid,Footage。get_projectはアイテムツリー、ダーティフラグ、アクティブコンポを返します。1 つのコンポが アクティブ であり、ほとんどのコマンドはアクティブコンポに対して作用します。 - コンポ は
{width, height, frameRate, duration, startTime, background, renderer: classic3D|advanced3D}です。時刻は秒（浮動小数点数、ティックではありません — FilmCraft のようなティック演算はありません）。 - レイヤー は Text, Shape, Solid, Null, Composition（プリコンポ）, Adjustment, Light, Camera のいずれかです。レイヤーは上から 1 と積み重なります。レイヤーは
id,#n（スタックインデックス）,nameで指定します。 - すべてのレイヤーには プロパティツリー があります:
Transform（anchor, position, scale, rotation, opacity）に加えて、effects,masks, テキストまたはシェイプのcontents。プロパティパスはtransform.positionおよびTransform/Positionを受け付けますが、単独のposition（グループなし）は拒否されます。 - アニメーション = プロパティ上のキーフレーム（
prop.addKey）または エクスプレッション（prop.setExpression, AE JavaScript）。prop.get {time}は補間値、キーリスト、animatedフラグを返します。 - パラメータは厳密に検証されます: 未知のパラメータ名は、受け付け可能なキーのリストとともにコマンドを失敗させます。未知のコマンド id も同様です。これは、パラメータを静かに無視する FilmCraft とは逆です — エラーを読み、呼び出しを修正し、盲目的に再試行しないでください。
- 読み戻しで検証する（
get_state,get_project,get_comp,get_layer,get_property）か、レンダリング（render_frame— PNG は、読み戻しでは表示されない、誤った位置、不可視レイヤー、欠落エフェクトを捕捉します）で検証します。
2つの接続モード
| モード | 起動方法 | 用途 |
|---|---|---|
| ヘッドレス | effectcraft-cli mcp --demo（--project p.ecproj, --empty, --autosave） | ウィンドウなし、バッチビルド、レンダリング、スクリプト |
| アプリブリッジ | effectcraft --control 50052 + effectcraft-cli mcp --bridge 50052 | 実際のウィンドウ: UI 状態、スクリーンショット、クリック、キー入力、GUI 専用コマンド |
各 CLI 呼び出しは独立したセッションです。 1 回の run で構築した状態は、プロセス終了時に失われます — file.saveAs + --save-as で終了するか、すべて（ビルド→レンダリング）を 1 回の render/run 呼び出しで実行してください。
ユーザー要求による EffectCraft の起動（"起動して" / "start EffectCraft"）
- 既に実行中か確認:
Get-Process effectcraft/pgrep effectcraft。起動済みの場合、ポートをテスト:effectcraft-cli --bridge 50052 info。制御ポートなしで起動している場合は、--control付きで再起動するようユーザーに依頼してください（未保存の作業は失われます）。 --control <port>（デフォルト50052）で起動:- Windows — バックグラウンドセッションではなく、表示中のデスクトップにウィンドウを表示するために
scripts/launch.ps1を使用:powershell -File scripts/launch.ps1 -Port 50052 - Linux:
./scripts/launch.sh 50052
- Windows — バックグラウンドセッションではなく、表示中のデスクトップにウィンドウを表示するために
- 確認: 1～3 秒待ち、
effectcraft-cli --bridge 50052 infoを実行 — バージョン、コマンド/エフェクト数、開かれているプロジェクトが表示されます。
MCP ツール
ヘッドレスモードでは 27 のツールが公開され、ブリッジモードではさらに 9 つの UI ツール（ui_inspect, ui_elements, ui_click, ui_drag, ui_key, ui_set, ui_type, screenshot, control）と ScriptUI ダイアログ用の script_ui が追加され、合計 36 になります。
| ツール | 目的 |
|---|---|
command_list / list_commands | すべてのコマンド（--filter, --enabled） |
command_run / execute_command | 1 つの {id, params} を実行（アンドゥ可能） |
command_batch / batch | 複数コマンドを 1 つのアンドゥステップに（batch） |
describe_command | 1 つのコマンドのスキーマ |
doc_inspect / get_project | プロジェクトツリー + アクティブコンポを 1 回の呼び出しで |
get_comp | 1 つのコンポ: 設定、レイヤー、ワークエリア |
get_layer | レイヤーの完全なプロパティツリー |
get_property / set_property | 1 つのプロパティの読み取り / 書き込み（アニメーション時はキーを設定） |
add_keyframe | プロパティのキーフレーム（ストップウォッチをオンにする） |
add_effect / list_effects | エフェクトの適用（+パラメータを 1 回の呼び出しで）/ 307 個のエフェクトレジストリ |
list_fonts | テキストレイヤーで使用可能な 149 フォントファミリー |
run_script | After Effects スタイルの ExtendScript（app.project, comps, layers） |
render_frame / render_preview | （アクティブ）コンポの PNG を time で |
open_project / save_project | 開く（path, demo:true, empty:true）/ 保存（+名前を付けて保存） |
undo / redo / history | 分岐アンドゥ履歴 |
get_state | アクティブコンポ、現在時刻、選択、再生状態 |
script_ui | スクリプトが開いた ScriptUI ダイアログ/パレットを操作 |
リソース: effectcraft://document および effectcraft://commands。
標準ワークフロー
- プローブ。
get_state+get_project; ヘッドレスは--demo/--projectがなければ空で開始。ブリッジモードでは最初にui_inspect。 - ビルド。
comp.new {name,width,height,frameRate,duration}→layer.newText/newShape/newSolid/newNull（スタイリングパラメータはインライン）→ フッテージ用にfile.import {paths}→layer.addItemスタイルの配置。 - アニメート。 キーフレームごとに
prop.addKey {layer,path,time,value};keys.setEase,keys.interpolation,prop.setExpression。 - スタイル。
effect.apply {effect:"Gaussian Blur", layers:[id]}+effects/#1/...下のパラメータパス; マスク（mask.new）、テキストアニメーター、シェイプグラデーションストローク。 - 検証。 適切な時刻に
get_property; それらの時刻にrender_frameで PNG を確認（位置、イージング、ブラーがすべて視覚的に確認できます）。 - レンダリング。
render --out file.mp4 --format h264（CLI）、またはrenderQueue.add+renderQueue.render; RGBA にはrender-frame --transparent; テンプレートジョブにはrender --template t.ectemplate --values v.json。 - 保存。
file.saveAs {path}（または CLI の--save-as）;get_projectを再読み込み — 保存後にダーティフラグがクリアされます。
コマンドの探し方
command_list {filter:"mask"} は id、ラベル、メニューにマッチします。シェルからは: effectcraft-cli commands --filter mask、単一コマンドのスキーマは describe_command/describe。パラメータドキュメント付きの全 734 個の id は references/catalog/commands.md にあります。検証済みのステップバイステップ JSON は references/recipes.md にあります。
まずはこちらから: comp.new, comp.settings, comp.open, layer.newText, layer.newShape, layer.newSolid, layer.newNull, layer.select, layer.moveLater, layer.setTransform, layer.setText, prop.get, prop.set, prop.addKey, keys.setEase, keys.interpolation, prop.setExpression, effect.apply, mask.new, time.set, file.import, file.saveAs, renderQueue.add, renderQueue.render, app.quit。
時間を浪費する落とし穴
- あらゆる場所で厳密な検証。 未知のパラメータ →
invalid parameters … accepted: name, width, …（完全なキーリスト付き）; 未知のコマンド id →unknown command。エラーがドキュメントです — ただし、有効なパラメータでも誤った値の型の場合は誤動作する可能性があるため、状態を読み戻してください。 - レイヤー時刻とコンポ時刻の違い。 書き込みコマンド（
prop.addKey,keys.set,prop.set）はデフォルトでtimeを レイヤー秒（timeBase:"layer"|"comp"で切替）で受け取ります;prop.getはtimeを コンポ秒 で読み取ります。レイヤーが 0 から始まるときは一致しますが、layer.move後は一致しません。ベースを間違えると、キーがレイヤー開始時間分だけ静かにずれます。 - 多くのコマンドは選択が必要です。
prop.set,effect.apply,keys.easyEaseは何も選択されていないとenabled:falseを表示します（ヘッドレスは空で開始）。明示的にlayer/layersパラメータを渡すか、最初にlayer.selectを行ってください。 comp.newは{comp: id}を返し、そのコンポをアクティブにします（検証済み: 2 回のcomp.new呼び出しで、テキストレイヤーは 2 つ目のコンポに配置されます）。comp.open {comp: id|name}で切り替え、get_stateで確認 — "アクティブコンポ" をターゲットとするコマンドとレンダリングは、--emptyプロジェクトで最初のcomp.newの前に no active composition で失敗します。- プロパティパスにはグループが必要:
transform.position/Transform/Positionは動作しますが、単独のpositionは no property エラーになります。正確なパスはprops <comp> <layer> --flatまたはget_layerで確認してください。 - エフェクトパラメータはエフェクト下のパスです。例:
effects/#1/Blurriness（インデックス = 適用順序）。effect.applyはpaths:["effects/#1"]を返します — これを使用してください。 - 各 CLI 呼び出しは新しいセッションです（上記参照）。MCP セッションはサーバーが終了するまで状態を保持します。
renderの相対--outはプロセスのワーキングディレクトリに対して書き込まれます; 予測可能な出力のためには常に絶対パスを渡してください。- テキストレイヤーは作成時に完全なスタイリングを受け付けます（
layer.newText {size,fill,tracking,…}— 数十のパラメータ）。後からの再スタイリングはテキストソース/ドキュメントプロパティを通じて行います。正確なパスはget_layerを確認してください。 - GUI 専用サーフェス:
ui_*,screenshot,control,script_uiはブリッジモードでのみ存在します;window.*,view.*,help.*はほとんどが GUI を必要とします。 mcp --autosaveは終了時に未保存のヘッドレス編集を保持します。これがないと失われます（使い捨ての実行には期待通りですが、実際の作業には驚きです）。
リファレンスマップ
| ファイル | 内容 |
|---|---|
references/recipes.md | 検証済み JSON: ビルド、テキスト、シェイプ、キーフレーム、イージング、エクスプレッション、エフェクト、マスク、レンダリング、エクスポート、GUI |
references/catalog/commands.md | パラメータドキュメント付き、名前空間別にグループ化された全 734 コマンド |
references/mcp-and-control.md | 27+9 ツール、エラー形状、リソース、ブリッジの詳細 |
references/cli.md | effectcraft-cli サブコマンド、レンダリングフォーマット、テンプレート、ベンチマーク |
references/bugs-and-workarounds.md | 最小限の再現コードで再現された欠陥 |
references/maintenance.md | バージョンの再検証、コマンドのダンプ、このスキルの更新 |
scripts/probe.sh / .ps1 | MCP ハンドシェイク + ツール数 + バージョン |
scripts/dump-commands.sh / .ps1 | コマンドカタログの再生成 |
scripts/launch.sh / .ps1 | 制御ポート付きで GUI を起動（表示中のデスクトップ） |
scripts/smoke-test.sh / .ps1 | ビルド → キーフレーム → レンダリング → 検証 |
コミュニティ: https://discord.gg/artcraft · https://getartcraft.com/apps/effectcraft