OpenScaleOrg/aseprite-live

ユーザーのAsepriteウィンドウでライブ作業を行う

aseprite MCPサーバーには、呼び出しごとに選択可能な2つのモードがあります。

• ライブ: Asepriteが起動しており、Aseprite MCP Live 拡張機能がサーバーに接続しています。すべてのツールはそのウィンドウ内で開いているスプライトに対してスクリプトを実行し、キャンバスはすぐに再描画されます。
• バッチ: 接続されたウィンドウはありません。各ツールは非表示のAsepriteを起動し、ディスク上のファイルを編集して終了します。開いているウィンドウは、ファイルが再度開かれるまで変更を表示しません。

すべてのセッションを live_status で開始する

結果	行うべきこと
connected; active tab: <path> + saved	そのパスをすべてのツールの filename として使用します。
... UNSAVED	保存場所を尋ね、save_active_sprite("<dir>/<name>.aseprite") を実行し、そのパスを使用します。
connected; no sprite is open	create_canvas でウィンドウに新しいタブを開きます。
Aseprite is not connected ...	ユーザーに伝えます。バッチモードで作業するのは、ユーザーが同意した場合のみです。

常にユーザーが開いているファイルに描画する（厳守）

すべての描画はユーザーの開いているタブ、つまり live_status によって報告されたアクティブなスプライトに対して行われます。作業を別のファイルに配置しないでください。

• 決して2つ目のスプライトを作成しないでください。 ユーザーがタブを開いている間は、create_canvas を呼び出したり、run_lua_script 内で Sprite(w, h) を呼び出したりしないでください。create_canvas は live_status がスプライトが開いていないと示した場合にのみ使用してください。Lua では app.activeSprite を編集します。
• キャンバスが小さすぎる場合は、同じファイルのサイズを変更します。 たとえば、開いているタブが 64×64 で、シーンに 160×112 が必要な場合は、そのファイルに対して resize_canvas(<open file>, 160, 112) を呼び出してから描画します。フレーム数についても同様に、add_frames を使用してそのファイルにフレームを追加します。
• 既にアートワークがあるキャンバスについては、最初に確認を求めます。 resize_canvas は既存のピクセルをスケーリングするため、空白のタブの場合は単にサイズ変更します。タブに既にアートがある場合は、サイズ変更前にユーザーに確認してください。
• タブが未保存の場合は、 save_active_sprite で保存し（保存場所を尋ねます）、その後そのファイルで作業を続けます。保存しても、別のファイルを開始する理由にはなりません。
• ライブモードが接続されていない場合は、 停止してユーザーに伝えてください。ユーザーが明示的にそうしない限り、ディスク上の新しいファイルにフォールバックしないでください。

この拡張機能は、サーバーが初めて起動したときに Aseprite に自身をインストールします。その後、Aseprite を一度再起動する必要があり、初回使用時にスクリプトがネットワークに接続したりファイルに書き込んだりすることを許可するかどうかを尋ねられます。ユーザーは Aseprite 内でこれを許可する必要があります。これらのプロンプトをユーザーに代わってクリックしないでください。

ライブ描画中の注意点

• 1回のツール呼び出しが1つのアンドゥステップになります。 ユーザーは Ctrl+Z を押すことで、あなたの手順を正確に1つ取り消すことができます。必要に応じてそのことをユーザーに伝えてください。
• 可視性の高いパスで作業します（シルエット、ベタ塗り、シェーディング、詳細、アニメーション）。そうすることで、ユーザーは作品が組み上がっていく様子を見ることができ、各パスが何を行うかを説明してください。
• 1回の呼び出しで1つの小さなことを行います。 ウィンドウは呼び出しが戻ったときにのみ再描画されるため、シーン全体を描画するスクリプトはすべて一度に表示されます。各呼び出しでは、1つのオブジェクト、1つのレイヤー、1つのシェーディングパス、または1つのフレームを追加してください。スクリプトを書き、実行し、次に次のスクリプトを書いてください。すべてのスクリプトを最初に書いて、最後にまとめて実行しないでください。
  • 専用ツール（draw_rows、draw_rectangle_at、draw_ellipse_at、fill_area_at ...）を優先してください。これらはそれぞれ単一の可視ステップです。
  • ライブモードでは、run_lua_script は40コード行を超えるスクリプトを拒否します。ヘルパー関数は短く保ってください。すべてのスクリプトが自身の関数を再定義する必要があるためです。
  • 64×64 のシーンでは、通常10～25回の呼び出しが必要です。これは想定内です。ユーザーはそれが構築されるのを見ています。
• 各ステップはファイルに保存され、view_sprite とエクスポートツールの同期が保たれます。それらは依然として非表示の Aseprite を通して保存されたファイルを読み取ります。
• ユーザーも編集することがあります。 領域を再描画する前に view_sprite または read_rows で確認し、確認なしにユーザーの変更を上書きしないでください。
• ユーザーの表示を変更しないでください。 タスクで必要がない限り、ウィンドウ内のタブ、フレーム、レイヤーを切り替えないでください。

トラブルシューティング

• ツールが「ダイアログが開いている可能性があります」というタイムアウトになる。 Aseprite が権限要求などのプロンプトを待っています。ユーザーに応答するよう依頼してください。
• ウィンドウに変更が表示されない。 live_status を実行してください。各呼び出しは最初に他の Claude セッションが保持しているライブリンクを要求するため、それでも接続されていないと表示される場合は、拡張機能がインストールされる前に Aseprite が開かれたため、再起動が必要です。停止してユーザーに伝えてください。ディスク上のファイルに描画を続けないでください。
• 自分で Aseprite を起動しないでください。 シェルコマンドで新しいウィンドウにファイルを開かないでください。同じファイルに対して2つのウィンドウがあると同期が取れなくなり、スクリプトは最後に接続したウィンドウにのみ送信されます。開いているタブが古い場合は、ユーザーに ファイル → 元に戻す を使用するよう依頼してください。
• スプライトのような名前のタブが表示されたり閉じたりする。 これは想定内です。一部の分析ツールは一時的なコピーで動作し、その後閉じられます。