add-3d-assets

パフォーマンスに関する注意事項

• 時間をかけて、丁寧に作業してください
• 速度よりも品質を重視してください
• 検証手順を省略しないでください

3D アセットの追加

基本的な幾何学形状（BoxGeometry、SphereGeometry）を実際の 3D モデルに置き換えます。キャラクターには、リギングとアニメーションを施した Meshy AI 生成のカスタムモデルを使用します。ワールド内のオブジェクトには、生成したモデルまたは無料ライブラリから入手したモデルを使用します。

手順

$ARGUMENTS に指定されたゲームを分析します（パスが指定されていない場合は、現在のディレクトリを使用します）。

まず、モデルのパイプライン全体、AssetLoader パターン、Meshy による生成、統合パターンを確認するために、game-3d-assets スキルと meshyai スキルを読み込みます。

ステップ 1：Meshy API キーの取得

MESHY_API_KEY が設定されているか確認します。最初に .env を確認します。 test -f .env && grep -q '^MESHY_API_KEY=.' .env && echo "found" 見つかった場合は、set -a; . .env; set +a でエクスポートし、プロンプトを省略します。

設定されていない場合は、ユーザーに尋ねます。

最良の結果を得るために、Meshy AI でカスタム 3D モデルを生成します。無料の API キーは 30 秒で取得できます。

1. https://app.meshy.ai で登録します
2. Settings → API Keys に移動します
3. 新しい API キーを作成します

以下の形式でキーを貼り付けてください：MESHY_API_KEY=your-key-here （キーは .env に保存され、この会話から自動的に伏せ字になります。）

または、「skip」と入力して、無料のモデルライブラリを使用します。

ステップ 2：監査

• package.json を読み、このゲームが Three.js ゲームであることを確認します（Phaser ではありません。2D ゲームには /add-assets を使用してください）
• src/core/Constants.js を読み、エンティティの種類、サイズ、色を確認します
• エンティティのファイル（src/gameplay/*.js、src/entities/*.js）を読み、BoxGeometry、SphereGeometry などを探します
• src/level/LevelBuilder.js を読み、環境内のプリミティブを確認します
• 幾何学形状を使用しているエンティティをすべてリストアップします
• アニメーションモデルが必要なプレイヤーキャラクターを特定します

ステップ 3：計画

エンティティを次の 2 つのカテゴリに分けます。

アニメーション付きキャラクター（プレイヤー、AI を持つ敵）— Meshy AI で生成します。

エンティティ	Meshy プロンプト	備考
プレイヤー	"a heroic knight, low poly game character, full body, t-pose"	生成 → リギング → アニメーション
敵	"a goblin warrior with a club, low poly game character"	生成 → リギング → アニメーション

Meshy を利用できない場合は、assets/3d-characters/ にあるモデルを使用します。

• Soldier — リアルな軍人（Idle、Walk、Run）— デフォルトとして最適
• Xbot — スタイライズされたマネキン（idle、walk、run ＋ 加算ポーズ）
• RobotExpressive — カートゥーン調のロボット（Idle、Walking、Running、Dance、Jump ＋ ほか 8 種類）
• Fox — ローポリの動物（Survey、Walk、Run）— スケール 0.02

ワールドオブジェクト（建物、小道具、景観、収集アイテム）— Meshy で生成するか、無料ライブラリを検索します。

エンティティ	Meshy プロンプト	代替ソース
木	"a low poly stylized tree, game asset"	Poly Haven
家	"a medieval house, low poly game asset"	Poly Haven
樽	"a wooden barrel, low poly game asset"	Poly Haven
コイン	"a gold coin, game collectible item"	Sketchfab

ステップ 4：生成／ダウンロード

Meshy を使用する場合（推奨）：

# Generate characters
MESHY_API_KEY=<key> node <plugin-root>/scripts/meshy-generate.mjs \
  --mode text-to-3d \
  --prompt "a heroic knight, low poly game character, full body" \
  --polycount 15000 --pbr \
  --output public/assets/models/ --slug player

# Rig characters for animation
MESHY_API_KEY=<key> node <plugin-root>/scripts/meshy-generate.mjs \
  --mode rig --task-id <refine-task-id> --height 1.7 \
  --output public/assets/models/ --slug player-rigged

# Generate static props
MESHY_API_KEY=<key> node <plugin-root>/scripts/meshy-generate.mjs \
  --mode text-to-3d \
  --prompt "a wooden barrel, low poly game asset" \
  --polycount 5000 \
  --output public/assets/models/ --slug barrel

Meshy を使用しない場合（代替手段）：

# Characters — copy from library
cp <plugin-root>/assets/3d-characters/models/Soldier.glb public/assets/models/

# World objects — search and download
node <plugin-root>/scripts/find-3d-asset.mjs --query "barrel" --source polyhaven \
  --output public/assets/models/ --slug barrel

ステップ 5：統合

1. src/level/AssetLoader.js を作成します — アニメーションモデルには SkeletonUtils.clone() を使用してください（three/addons/utils/SkeletonUtils.js からインポートします）。通常の .clone() ではスケルトンが壊れ、T ポーズになります。
2. Constants.js に path、scale、facingOffset、clipMap を含む CHARACTER を追加します
3. 静的モデル用に ASSET_PATHS と MODEL_CONFIG を追加します
4. Player.js を更新します：
   • 位置アンカーとして THREE.Group を使用します
   • loadAnimatedModel() と AnimationMixer を追加します
   • 待機／歩行／走行のクロスフェード用に fadeToAction() を追加します
   • applyAxisAngle(_up, cameraAzimuth) によるカメラ相対の WASD 移動
   • モデルの向き：atan2(v.x, v.z) + CHARACTER.facingOffset
   • model.quaternion.rotateTowards(targetQuat, turnSpeed * delta)
5. Game.js を更新します：
   • OrbitControls を追加し、プレイヤーを中心にサードパーソンカメラを回転させます
   • カメラの追従：プレイヤーの移動量分だけ orbitControls.target と camera.position を移動します
   • カメラ相対の移動のため、orbitControls.getAzimuthalAngle() を Player に渡します
6. 環境プリミティブを loadModel() の呼び出しと .catch() によるフォールバックに置き換えます
7. 移動の目安を表示するため、THREE.GridHelper を追加します
8. 起動時に preloadAll() ですべてのモデルをプリロードし、即座に読み込めるようにします

ステップ 6：調整と確認

• npm run dev を実行し、WASD で歩き回り、マウスでカメラを回転させます
• キャラクターがアニメーションすることを確認します（停止中は Idle、移動中は Walk、Shift キーを押すと Run）
• モデルごとに MODEL_CONFIG の値（scale、rotationY、offsetY）を調整します
• npm run build を実行し、エラーがないことを確認します
• .meta.json ファイルから ATTRIBUTION.md を生成します

使用例

Meshy AI を使用する場合

/add-3d-assets examples/space-explorer

結果：Meshy を使ってカスタムの騎士モデルを生成し、リギングとアニメーション（Idle／Walk／Run）を適用して、BoxGeometry のプレイヤーをアニメーション付き GLB に置き換え、OrbitControls カメラを追加し、無料ライブラリのワールド用オブジェクトを配置します。

Meshy を使用しない場合（フォールバック）

/add-3d-assets examples/3d-platformer

結果：キャラクターライブラリから Soldier.glb をコピーし、SkeletonUtils.clone() を設定して、fadeToAction によるアニメーションのクロスフェードを適用し、すべてのプリミティブをライブラリまたはダウンロードしたモデルに置き換えます。

トラブルシューティング

モデルが T ポーズのまま（アニメーションしない）

原因： .clone(true) を使用すると、アニメーション付き GLB モデルのスケルトンバインディングが壊れます。 修正方法： アニメーションを含むモデルには必ず three/addons/utils/SkeletonUtils.js の SkeletonUtils.clone() を使用してください。通常の .clone() はメッシュをコピーしますが、スケルトンバインディングはコピーしません。

Meshy AI の生成に失敗する、または品質が低い

原因： プロンプトが曖昧、または誤った生成モードが選択されています。 修正方法： 具体的で詳しいプロンプトを使用します（例：「chest」ではなく「ゲームアセット用のローポリ中世風木製宝箱」）。キャラクターの場合は、参照画像を使った画像から 3D へのモードを使用します。ゲームへの統合を容易にするため、アートスタイルを「game-asset」または「low-poly」に設定します。

生成モデルのリギングに失敗する

原因： モデルのジオメトリが自動リギングに適していません（複雑すぎる、非多様体、または人型ではない）。 修正方法： プロンプトを簡潔にし、よりクリーンなジオメトリを生成します。モデルが人型のポーズを取った、単一の接続されたメッシュであることを確認します。人型ではないモデル（小道具、乗り物）はリギングせず、静的アセットとして使用してください。

読み込み時に meshopt デコーダーエラーが発生する

原因： 一部の GLB ファイルは meshopt 圧縮を使用しており、デフォルトでは読み込まれないデコーダーが必要です。 修正方法： 読み込み前に meshopt デコーダーを追加します：import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js'; loader.setMeshoptDecoder(MeshoptDecoder);

モデルの向きが間違っている

原因： モデルの提供元によって前方の向きが異なります。Mixamo のモデルは -Z 方向を向いていますが、それ以外のモデルの中には +Z 方向を向いているものもあります。 修正方法： キャラクターモデルごとに facingOffset を保存します。これを model.rotation.y = facingOffset + movementAngle として適用します。一般的な値：Soldier／Xbot には +Math.PI、Robot／Fox には +0 を設定します。

次のステップ

ユーザーに次のように伝えます。

3Dゲームにカスタムモデルが追加されました！キャラクターはMeshy AIで生成（またはモデルライブラリから取得）し、リギングとアニメーションを行いました。ワールドオブジェクトはGLBファイルから読み込まれます。

作成されたファイル：

• src/level/AssetLoader.js — SkeletonUtilsを使用したモデルローダー
• public/assets/models/ — 生成およびダウンロードしたGLBモデル
• OrbitControlsの三人称カメラ

操作方法： WASDで移動、Shiftで走行、マウスドラッグでカメラを回転、スクロールでズームします。 ゲームを実行して、すべての動作を確認してください。Constants.jsのMODEL_CONFIGを調整して、スケールと向きを微調整します。