paprika3d (the three.js toolset for coding agents)

paprika3D：コーディングエージェントをより優れた three.js 開発者にするツールセット

paprika3D は Claude Code プラグイン兼 MCP サーバーです。コーディングエージェントが作成した three.js、React Three Fiber、WebGL のページを、完成したと伝える前に開いて確認し、操作し、計測して修正できます。シーンをデータとして把握し、正確なクロックでページを再生し、任意のメッシュや値を調査し、実際のジオメトリで形状を構築し、フレームを高速化します。

インストール

Google Chrome と Node 20.11 以降が必要です。

claude plugin marketplace add paprika3d/paprika3d
claude plugin install paprika3d@paprika3d

Chrome は通常の macOS のパスから検出されます。それ以外の環境では、PAPRIKA3D_CHROME に Chrome の実行ファイルを設定してください。他のエージェントについては、他のエージェントをご覧ください。

ドキュメント：https://paprika3d.com/docs。window.__game の規約：https://paprika3d.com/docs/convention。LLM 向け：https://paprika3d.com/docs/llms.txt。

ゲーム、製品ビューアーやコンフィギュレーター、シミュレーション、シェーダーやポストプロセッシングのデモなど、three.js、React Three Fiber、WebGL のあらゆるページで動作します。ページを開いて確認し、操作して調査するための変更は必要ありません。

エージェントが得られること

three.js のページはひとつの <canvas> です。外から見ると、それは一枚の画像です。paprika3D はその内側、つまり 3D シーンそのものを扱います。

エージェントからの質問	paprika3D の回答
画面には何が表示されていますか？	名前の付いた各オブジェクトが画像に占める割合とバウンディングボックスを示します。さらに、画面に一度も表示されないオブジェクトについても、それぞれのサイズと、カメラの後方、視野の外、描画には小さすぎるといった理由を示します
モデルは読み込まれましたか？	ページを開いたときに報告します。取得されたモデル、テクスチャ、サウンドファイルと、読み込みに失敗したすべてのファイルを示します
Space を押すと何が起きますか？	一時停止したシード固定クロックの正確なフレームでキー入力が行われます（1 フレームあたり 1/60 秒）。そのため、同じ入力なら実行のたびに同じフレームと状態になります
ゲームの状態はどうなっていますか？	各入力の前後の状態を JSON で示します
このメッシュの大きさは？閉じていますか？	ページを変更せずに確認できます。メッシュごとの三角形、境界、閉じたエッジまたは開いたエッジ、体積、種数に加え、scene、camera、renderer に対して実行された JavaScript も確認できます
十分な速度が出ていますか？	フレーム時間、ドローコール、三角形数、アセットサイズを、デスクトップ、モバイル、Quest の予算と比較します
どうすれば速くできますか？	game_optimize は解像度スケーリング、インスタンシング、LOD、破棄を試し、見た目を変えずに効果があるものだけを残します
ヒットに手応えはありますか？	イベント後のカメラシェイク、スケールのポップ、テレポートではなくイージングを使った移動、フラッシュ、オブジェクトの生成、サウンドを確認します
必要な形状を構築できますか？	プロジェクト内の geo.js で、ブーリアン、凸包、押し出し、回転体、シード固定の散布を利用できます。Manifold も組み込まれています

画面をキャプチャすることはありません。すべての画像は、paprika3D 自身のヘッドレスページを映したものです。

検出できること

仕様に「車のスケールを 0.8 にする」とあったのに、エージェントが作成したミニゴルフページで game_look を実行した例を示します。

On screen (14):
Mesh 17.4% [399, 240, 880, 771]
…
Never visible: ToyCar (0.0338 units, in view), Glass (0.0168 units, in view)

車は存在し、視野内にありますが、8 メートルのコース上で長さは 3 cm です。以下の実行では、2 つのエージェントがこのようなページを開いてスクリーンショットを確認したにもかかわらず、車を見落としました。この行がその車を特定します。

クリーンインストール環境で Sonnet 5.5 を使用し、glTF モデルが付属する、長く厳密な three.js の仕様を対象に測定しました。

	エージェント単独	paprika3D を使用
インポートしたモデルのスケールが誤ったまま、または未読み込み	11 回中 10 回	11 回中 2 回
読み込まれなかった Draco 圧縮モデル（「No DRACOLoader instance provided」）	3 回中 3 回	3 回中 0 回

ツールをインストールしてもリマインダーがなければ、エージェントがページを開いたのは 6 回中 0 回でした。プラグインがセッションごとに 1 回表示するようになったリマインダーを使うと、11 回中 10 回です。これらのタスクでは、どの条件でもゲームロジックは正しかったため、改善したのは、見ることでしかわからないインポート済みアセット、スケール、フレーミング、読み込み失敗です。実行には、費用が約 1.5～2 倍、実時間が 2～7 倍かかります。これらは少数のサンプル（各タスクにつき 3～5 回、モデル 1 つ）に基づく結果です。

エージェント向け：ループ

プロンプトで依頼するには、use paprika3d to playtest と指定します。

three.js、React Three Fiber、または WebGL のページを書いたり変更したりしたら、完了を報告する前にこれらのツールを使ってください。

1. 開く： url: "index.html"（フォルダーが配信されます）または command: "bunx vite" を指定して game_open を呼び出します。Loaded: と Failed to load: の行を確認します。
2. 見る： game_look を呼び出します。Never visible: を確認します。幅が 8 単位のシーンで大きさが 0.07 単位のオブジェクトはスケールが不適切です。behind the camera または outside the view はフレーミングの問題です。保存された画像を開きます。
3. 操作する： 依頼で指定された各操作について、game_act を呼び出し、返される状態を確認します。時間を進めるには game_clock を使います。
4. シーンに問い合わせる： game_eval は、サイズ、マテリアル、位置に関する質問に答え、ソースに反映する前にページ上で変更を試すこともできます。
5. 修正してから、もう一度確認する。 パフォーマンスが重要な場合は game_perf を呼び出します。

スコア、衝突、ターン順、指定された数値など、厳密なルールがあるゲームでは、game_contract でゲームコントラクトを固定し、変更のたびに game_check を呼び出します。フックも各編集後にバックグラウンドでチェックを行います。threejs-game スキルには、プレーンな three.js、React Three Fiber、Rapier 向けの手順とテンプレートがすべて記載されています。

ツール

ツール	機能
game_open	一時停止されたシード付きクロックで、ヘッドレス Chrome 上にページ（ファイルまたはフォルダー、http URL、開発サーバーのコマンド）を開きます。ページが取得したモデル、テクスチャ、サウンドのファイルと、失敗したすべての取得を一覧表示します
game_look	画像、オブジェクトごとに 1 色を割り当てた ID 画像、画面上の名前付きオブジェクトの一覧、およびサイズと位置を含む、まだ表示されたことのない名前付きオブジェクトの一覧（カメラの後ろ、表示範囲外、または表示範囲内だがピクセルを描画していない）を返します。target を指定すると、1 つの名前付きオブジェクトを正面、右側、上側、斜め 45 度から 1 枚の画像に表示します
game_act	キー、マウス、タッチ、または __game.act アクションをフレームごとに送信し、前後の状態を返します
game_observe	ページの状態（__game.observe() または名前付きの three.js オブジェクト）、レンダラーのカウント、新しいコンソールエラー、前回の observe からの変更を返します
game_eval	scene、camera、renderer、find(name)、stats(target) をスコープ内で使ってページ内の JavaScript を実行し、戻り値を返します。stats は各メッシュの頂点、三角形、境界、属性、マテリアル、閉じたエッジまたは開いたエッジ、体積、種数を返します。応答は 2,048 文字までで、全文は実行フォルダーに保存されます
game_clock	フレームを進め、リアルタイム再生を一時停止または再開し、時間のスケールを設定します
game_feel	イベントを起こす手順を送信し、その後のフレームを監視して、カメラの揺れ、スケールの急変、イージングを伴う移動とテレポートの違い、色のフラッシュ、オブジェクトの生成、HUD テキストの変化、サウンドを確認します
game_perf	デスクトップ、モバイル、Quest、またはコントラクトの予算と照らし合わせて、フレーム時間、ドローコール、三角形、アセットサイズを確認します
game_optimize	チェックでフレームが予算を超えた場合、またはユーザーがパフォーマンスについて尋ねた場合にのみ使用します。計測し、ランタイムの設定を試し、重要なチェックポイントに失敗せず、画像も変わらない範囲で効果のある設定を適用し、game-runtime.json を書き込み、最後にチェックを実行します
game_contract	ユーザーのプロンプトを game-contract.json に変換します。ゲームコードを一切見ていない新しいサブエージェントがこれを書き込みます。ハッシュはプロジェクトの外部に保存されるため、手動編集したコントラクトは拒否されます
game_check	ページを新しく読み込むたびに、各チェックポイントのコントラクトを実行します。最後の行には、チェックポイントの実行時のフレーム時間と予算が表示されます

ゲームをチェック可能にする

どのページも開いて、確認し、操作できます。ルールをチェックするには、ゲームのページ読み込み後に window.__game を公開します。

window.__game = {
  describe(),        // a short description: name, controls, units
  observe(),         // the state, exactly the keys of game-contract.json's schema, as plain JSON
  act(input),        // performs one input object: { key, down? } or { action, ...args }
  setState(partial), // sets any of the schema's keys at once; keys left out keep their values
};
// Starts playing on load: no title screen, no click to start.
// Time comes only from requestAnimationFrame / performance.now (faked, 1/60 s per frame, never more than 0.1 s a frame).
// Randomness comes only from Math.random (seeded). Keys listen on window and match event.key.

ルールの全容は skills/threejs-game/SKILL.md と https://paprika3d.com/docs/convention に記載されています。

ランタイムのインポート

ゲームで必要になるのは、チェックでフレームが予算を超過していると判定された場合だけです。その後、ランタイムがないゲームで game_optimize を実行すると、ビルド済みのランタイムが three-runtime.js としてプロジェクトに追加され、インポートを求められます。エントリーファイルの先頭、レンダラーを作成する前に一度だけ追加し、ゲームを開き直してください。

import { install } from "./three-runtime.js";
install();

game_optimize が game-runtime.json を書き込むまでは何も行いません（vite は public/ のみをコピーするため、プロジェクトに public/ がある場合はそこにも書き込みます）。その後、そこに保存された resolution、defaults、instancing、lod、dispose の各スイッチを実行します。

プロシージャルジオメトリ

game_open は geo.js をプロジェクトに追加します。このファイルには Manifold が組み込まれており、ブーリアン演算、ハル、押し出し、回転体のほか、シード指定可能な scatter を利用できます。import { geo, scatter } from "./geo.js"; でインポートしてください（vite プロジェクトの src/ からは "../geo.js" を使用します）。レシピは skills/threejs-game/references/geometry.md にあります。

その他のエージェント

MCP サーバーは Node 20.11 以降と Google Chrome で動作し、インストール手順は不要です。このリポジトリをクローンし、MCP クライアントで src/cli.js serve を指定してください。

git clone https://github.com/paprika3d/paprika3d.git

{
  "mcpServers": {
    "paprika3d": {
      "command": "node",
      "args": ["/path/to/paprika3d/src/cli.js", "serve"]
    }
  }
}

各ツールには、cwd としてプロジェクトフォルダーを指定します。編集後のフックと threejs-game スキルは Claude Code の機能です。他のエージェントは AGENTS.md と skills/threejs-game/SKILL.md を参照することで、同じ手順を利用できます。

実行データの保存先

• <project>/paprika3d/runs/<time>/：各実行の画像と run.json が保存されます。<project>/paprika3d/state.json には、反復回数、直近 200 件の実行、フックが実行中のサーバーに接続する方法が保存されます。プロジェクトの .gitignore に paprika3d/ を追加してください。
• ~/.paprika3d/issued.json（または $PAPRIKA3D_HOME）：発行された各コントラクトのハッシュが保存されます。
• Paprika アプリ：インストールされている場合、各チェック、パフォーマンス、最適化の実行は、その結果、実時間、反復回数、実行のきっかけとなった編集とともに、~/.paprika/spool/（または $PAPRIKA_HOME）にアクション行として記録されます。

ライセンス

Apache License 2.0（LICENSE）。各パッケージにバンドルされているビルド成果物には、それぞれのライセンスが適用されます。ライセンスは THIRD_PARTY_NOTICES.md に記載されています。「paprika3D」と「paprika3d」は Keeno Corp の商標です（NOTICE）。フォークは、それぞれ独自の名前を使用する限り、ライセンスに基づいて歓迎されます。問題の報告も歓迎します。コードへの貢献については CONTRIBUTING.md をご覧ください。