Performance Notes

• 時間をかけて丁寧に進める
• 速度よりも品質を優先
• 検証ステップをスキップしない

3D アセットの追加

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

手順

$ARGUMENTS のゲーム (またはパスが指定されていない場合はカレントディレクトリ) を分析します。

まず、game-3d-assets スキルと meshyai スキルをロードして、完全なモデルパイプライン、AssetLoader パターン、Meshy 生成、統合パターンを取得します。

ステップ 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 を使用 (推奨):

# キャラクターを生成
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

# キャラクターをアニメーション用にリギング
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

# 静的なプロップを生成
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 なし (フォールバック):

# キャラクター — ライブラリからコピー
cp <plugin-root>/assets/3d-characters/models/Soldier.glb public/assets/models/

# ワールドオブジェクト — 検索してダウンロード
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 に CHARACTER を追加 (path、scale、facingOffset、clipMap を含む)
3. 静的モデルの ASSET_PATHS と MODEL_CONFIG を追加
4. Player.js を更新:
   • THREE.Group を位置アンカーとして使用
   • loadAnimatedModel() + AnimationMixer
   • fadeToAction() で idle/walk/run をクロスフェード
   • カメラ相対 WASD は applyAxisAngle(_up, cameraAzimuth) 経由
   • モデルの向き: atan2(v.x, v.z) + CHARACTER.facingOffset
   • model.quaternion.rotateTowards(targetQuat, turnSpeed * delta)
5. Game.js を更新:
   • OrbitControls を追加 — プレイヤーの周りを回転するサードパーソンカメラ
   • カメラ追従: orbitControls.target と camera.position をプレイヤーのデルタ分移動
   • orbitControls.getAzimuthalAngle() をプレイヤーに渡してカメラ相対移動を実現
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) の代わりに SkeletonUtils.clone() を使用しないとアニメーション化された GLB モデルのスケルトンバインディングが破壊されます。 修正: アニメーションを持つモデルには必ず three/addons/utils/SkeletonUtils.js から SkeletonUtils.clone() を使用してください。通常の .clone() はメッシュをコピーしますがスケルトンバインディングはコピーしません。

Meshy AI 生成が失敗するか品質が低い

原因: 曖昧なプロンプトまたは間違った生成モードが選択されています。 修正: 具体的で説明的なプロンプトを使用 (例: "low-poly medieval wooden treasure chest, game asset" ではなく単に "chest")。キャラクターの場合はリファレンス画像付きで image-to-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 を調整してスケールと向きを微調整してください。