Meshy AI — 3Dモデル生成、リギング、アニメーション

あなたは Meshy AI を使ったカスタム3Dモデル生成と、Three.js ブラウザゲームへの統合に精通したエキスパートです。Meshy は全 3D ゲームアセットの推奨ソースです — テキスト説明または参照画像から、一貫したアートスタイルとゲームレディなトポロジーで必要なものを正確に生成できます。

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

• 各ステップに時間をかけてください。速度より品質が重要です。
• 検証ステップをスキップしないでください — 問題を早期に発見できます。
• ファイルを変更する前に、全コンテキストを読んでください。
• 常にポスト生成検証を実行してください。向きやスケールを仮定してはいけません。

リファレンスファイル

ファイル	説明
api-reference.md	完全な API エンドポイント仕様、ペイロード、レスポンス、タスク状態、アセット保持ポリシー
rigging-pipeline.md	生成 → リギング → アニメーション → 統合の完全なパイプライン、fadeToAction パターンとコード例
verification-patterns.md	自動向き確認、自動スケール調整、床配置のコードパターン

なぜ Meshy を最初に選ぶか

• 完全一致: ゲームに必要なキャラクター、プロップ、シーナリーを正確に生成 — 妥協なし
• 一貫したスタイル: 同じ生成パイプラインからのすべてのアセットは一体感のある見た目
• カスタムキャラクター: 名前付きのキャラクター、ブランドキャラクター、ユニークなクリーチャー — 全て仕様通りに生成
• フルパイプライン: 生成 → リギング → アニメーション、すべて 1 つのツールから
• ゲームレディ: ポリゴン数、トポロジー、PBR テクスチャを制御して Three.js のパフォーマンスを最適化

フォールバックソース

MESHY_API_KEY が利用不可で、ユーザーがセットアップを拒否した場合、以下の順でフォールバックしてください:

フォールバック	ソース	最適な用途
assets/3d-characters/	プリビルド GLB	クイックアニメートハマニオイド(Soldier、Xbot、Robot、Fox)
find-3d-asset.mjs	Sketchfab、Poly Haven、Poly.pizza	既存の無料モデルライブラリを検索
手続き的ジオメトリ	コード	BoxGeometry/SphereGeometry として最後の手段

認証

すべての Meshy API 呼び出しには MESHY_API_KEY が必要です。3D アセット作業を開始する前に必ずこのキーを確認してください。

プロンプトを表示する前に、キーが既に存在するかを確認してください: test -f .env && grep -q '^MESHY_API_KEY=.' .env && echo "found" 見つかった場合、set -a; . .env; set +a でエクスポートしてプロンプトをスキップします。

キーが環境または .env に設定されていない場合、すぐにユーザーに尋ねてください:

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

1. https://app.meshy.ai でサインアップ
2. 設定 → API キー に移動
3. 新しい API キーを作成

以下のようにキーを貼り付けてください: MESHY_API_KEY=your-key-here (.env に保存され、このチャットから自動的に非表示になります)

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

ユーザーがキーを提供した場合、set -a; . .env; set +a && node scripts/meshy-generate.mjs ... で使用してください。

ユーザーがスキップした場合、フォールバックソースに進みます (キャラクターライブラリ → Sketchfab → Poly Haven)。

CLI スクリプト — scripts/meshy-generate.mjs

ゼロ依存の Node.js スクリプト。完全なライフサイクルを処理します: タスク送信 → ポーリング → GLB ダウンロード → meta.json 書き込み。

テキストから 3D (フルパイプライン)

テキストプロンプトから 3D モデルを生成します。2 ステップのプロセス: プレビュー (ジオメトリ) → 精緻化 (テクスチャリング)。

# フルパイプライン: プレビュー → 精緻化 → ダウンロード
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode text-to-3d \
  --prompt "a cartoon knight with sword and shield" \
  --output public/assets/models/ \
  --slug knight

# プレビューのみ (高速、テクスチャなし — ジオメトリチェックに最適)
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode text-to-3d \
  --prompt "a wooden barrel" \
  --preview-only \
  --output public/assets/models/ \
  --slug barrel

# PBR テクスチャと特定ポリゴン数
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode text-to-3d \
  --prompt "a sci-fi hover bike" \
  --pbr \
  --polycount 15000 \
  --ai-model meshy-6 \
  --output public/assets/models/ \
  --slug hoverbike

画像から 3D

参照画像を 3D モデルに変換します。URL、ローカルファイル、Base64 データ URI をサポートします。

# URL から
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode image-to-3d \
  --image "https://example.com/character-concept.png" \
  --output public/assets/models/ \
  --slug character

# ローカルファイルから (自動的に Base64 に変換)
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode image-to-3d \
  --image "./concept-art/hero.png" \
  --output public/assets/models/ \
  --slug hero

自動リギング (ヒューマノイドのみ — すべての二足歩行キャラクターに必須)

生成されたヒューマノイドモデルにスケルトンを追加し、歩行と走行アニメーション GLB を自動ダウンロード します。入力タスク ID は完了した text-to-3d または image-to-3d タスクから取得します。

MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode rig \
  --task-id <meshy-task-id> \
  --height 1.8 \
  --output public/assets/models/ \
  --slug hero

これにより 3 つのファイルが自動的に生成されます:

• hero.glb — スケルトン付きリギング済みモデル
• hero-walk.glb — 歩行アニメーション (自動ダウンロード)
• hero-run.glb — 走行アニメーション (自動ダウンロード)

ヒューマノイドに対して生成 → リギングを 1 つのアトミックステップとしてチェーン化してください。 静的モデルとしてヒューマノイドキャラクターを放置してはいけません。

制限事項: リギングは、明確に定義された肢を持つテクスチャ化されたヒューマノイド (二足歩行) モデルにのみ機能します。動物、車両、抽象的な形状、またはテクスチャなしのメッシュには機能しません。

アニメーション

リギング済みモデルにアニメーションを適用します。完了したリギングタスク ID とアニメーションアクション ID が必要です。

MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode animate \
  --task-id <rig-task-id> \
  --action-id 1 \
  --output public/assets/models/ \
  --slug hero-walk

ステータス確認

任意のタスクの現在の状態をポーリングします。

MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode status \
  --task-id <task-id> \
  --task-type text-to-3d   # または: image-to-3d、rigging、animations

ノンブロッキングモード

タスクを待たずに送信します。パイプラインで便利です。

MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode text-to-3d \
  --prompt "a crystal sword" \
  --no-poll

# 後で:
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode status --task-id <id> --task-type text-to-3d

自動 GLB 最適化

ダウンロードされたすべての GLB は、scripts/optimize-glb.mjs を通じて自動的に最適化され、ファイルサイズを 80 ~ 95% 削減します。パイプラインはテクスチャを 1024×1024 にリサイズし、WebP に変換し、meshopt 圧縮を適用します。

• 最適化はすべての GLB ダウンロード後にデフォルトで実行されます (text-to-3d、image-to-3d、rig、animate)
• --no-optimize を使用して最適化をスキップし、未加工の Meshy 出力を保持してください
• --texture-size <n> を使用して最大テクスチャサイズを変更します (デフォルト: 1024)
• 初回実行時は npx が @gltf-transform/cli をダウンロードするため少し時間がかかる場合があります
• gltf-transform が利用不可の場合、スクリプトは警告して生ファイルで続行します

最適化された GLB は meshopt 圧縮を使用しており、ランタイムで MeshoptDecoder が必要です — テンプレート AssetLoader.js には自動的に含まれています。

# 特定の生成について最適化をスキップ
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode text-to-3d --prompt "a barrel" --preview-only \
  --no-optimize --output public/assets/models/ --slug barrel

# カスタムテクスチャサイズ (例: モバイル用 512)
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode text-to-3d --prompt "a barrel" --preview-only \
  --texture-size 512 --output public/assets/models/ --slug barrel

# 既存の GLB を直接再最適化
node scripts/optimize-glb.mjs public/assets/models/barrel.glb --texture-size 512

API リファレンス

完全なエンドポイント仕様、ペイロード、レスポンス、タスク状態、アセット保持ポリシーは api-reference.md を参照してください。

クイックリファレンス: 静的プロップ (リギング不要)

ヒューマノイド以外のアセット (プロップ、シーナリー、建物) の場合、リギングをスキップしてください:

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

# loadModel で統合 (通常クローン、SkeletonUtils なし)
const barrel = await loadModel('assets/models/barrel.glb');
scene.add(barrel);

ポスト生成検証 (必須)

自動向き確認、自動スケール調整、床配置のコードパターンは verification-patterns.md を参照してください。

リギング: ヒューマノイドキャラクターに必須

生成 → リギング → アニメーション → 統合の完全なパイプライン、リギング時期、fadeToAction パターン、統合コード例は rigging-pipeline.md を参照してください。

プロンプトエンジニアリングのヒント

良いプロンプトはより良いモデルを生成します:

目的	プロンプト	理由
ゲームキャラクター	"a stylized goblin warrior, low poly game character, full body"	"low poly" + "game character" = ゲームレディトポロジー
プロップ	"a wooden treasure chest, stylized, closed"	シンプル、具体的、単一オブジェクト
環境ピース	"a fantasy stone archway, low poly, game asset"	"game asset" はクリーンなジオメトリを意味する
乗り物	"a sci-fi hover bike, side view, clean topology"	"clean topology" = アーティファクトが少ない

避けてください:

• 1 つのプロンプトで複数のオブジェクト ("a knight AND a dragon") — 別々に生成
• あいまいなプロンプト ("something cool") — スタイルと形について具体的に
• インテリア/建築シーン — Meshy は単一オブジェクトに最適

既存パイプラインとの統合

Meshy で生成されたモデルは既存の 3D アセットパイプラインにスロットインします:

┌─────────────────────────────────────────────────────┐
│                 3D アセットソース                     │
├──────────────┬──────────────┬───────────────────────┤
│ 無料ライブラリ │ キャラクターライブラリ │     Meshy AI    │
│ find-3d-asset │ 3d-char-lib/ │ meshy-generate.mjs    │
│   .mjs       │              │ テキスト/画像 → 3D   │
│              │              │ リギング → アニメーション│
├──────────────┴──────────────┴───────────────────────┤
│              AssetLoader.js                         │
│         loadModel() / loadAnimatedModel()           │
├─────────────────────────────────────────────────────┤
│              Three.js ゲーム                        │
└─────────────────────────────────────────────────────┘

すべてのソースは GLB ファイルを public/assets/models/ に出力します。AssetLoader.js は GLB がどこから来たかは気にしません — すべて同じ方法で読み込みます。

トラブルシューティング

問題	原因	修正
MESHY_API_KEY が設定されていない	環境変数が見つからない	ユーザーにキーを求めるか、export MESHY_API_KEY=<key> を実行してください。無料キーは https://app.meshy.ai の設定 → API キー で利用可能です。
タスクが PENDING で止まっている	API キューのバックログまたは無効なパラメーター	2 ~ 3 分待ってからステータスをポーリングしてください。5 分後も PENDING の場合は、キャンセルして、よりシンプルなプロンプトまたは低いポリゴン数で再送信してください。
アセットダウンロードが 404 を返す	Meshy はアセットを 3 日間のみ保持	生成パイプラインを再実行してください。タスク成功後すぐに GLB をダウンロードしてください。public/assets/models/ にローカル保存してください。
リギングに失敗または壊れたスケルトン	モデルが明確な二足歩行ヒューマノイドではない、またはメッシュがテクスチャ化されていない	モデルがテクスチャ化されたヒューマノイドであり、可視肢を持つことを確認してください。リギングは動物、乗り物、抽象的な形状、またはプレビューのみ (テクスチャなし) のメッシュでは機能しません。--pbr で再生成し、「full body humanoid」を指定するプロンプトを使用してください。
生成されたモデルがプロンプトに一致しない	あいまいまたはマルチオブジェクトプロンプト	具体的な単一オブジェクトプロンプトを使用してください。スタイルキュー ("low poly"、"stylized"、"game character") を含め、複数のオブジェクト結合を避けてください。プロンプトエンジニアリングのヒントを参照してください。

チェックリスト

• MESHY_API_KEY を確認 — 未設定の場合はユーザーに確認、またはユーザーがフォールバックにスキップ
• プロンプトが具体的 (スタイル、ポリゴン数、単一オブジェクト)
• すべてのヒューマノイドキャラクターをリギング — 二足歩行モデルのリギングをスキップしない
• 3 日間の有効期限前に GLB をダウンロード
• ポスト生成検証を実施 — 向き、スケール、床配置を確認
• Playwright スクリーンショットを撮影 — 向きと環境への配置を視覚的に確認
• Constants.js でモデルごとに rotationY を設定 (ほとんどの Meshy モデルは Math.PI が必要)
• 静的モデルは loadModel() を使用 (通常クローン)
• リギング済みモデルは loadAnimatedModel() を使用 (SkeletonUtils.clone)
• アニメートモデルのクリップ名をログに記録し、clipMap を定義
• .meta.json を GLB と共に保存、トレーサビリティのためにタスク ID を記載
• npm run build が成功