threejs-3d-generator

Three.js 3D ジェネレーター

ブラウザーゲーム向けに用意された、Three.js 用の本番品質の 3D アセットです。プロバイダー：Tripo。

実際に読み込まれたスキルファイルから <this-skill-dir> を解決します。まずその隣にあるスキルを探し、次にランナーが検出したパスを使用します。インストール済みのバージョンを混在させたり、特定のホームディレクトリを前提としたりしないでください。

リファレンス

ファイル	読むタイミング
references/api-notes.md	エンドポイントとタスクの判断、モデルのバージョン、ポーリング、後処理、変換、リギング、アニメーション、ダウンロード
references/threejs-integration.md	出力をブラウザーゲームに読み込む場合、GLB/FBX の読み込み、ルートモーション、アニメーションの接続
references/image-generator-workflows.md	コンセプト、テクスチャ、UI アート、画像から 3D への入力に threejs-image-generator を組み合わせる場合

API キー

スクリプトは --api-key または TRIPO_API_KEY を読み込みます。キーをスキルファイル、ゲームコード、レポートに記載しないでください。

python3 <this-skill-dir>/scripts/threejs_3d_asset.py probe   # TRIPO_API_KEY=SET|MISSING

シェルプロファイルでのみ定義されたキーは、プロセス環境変数に存在しない場合があります。単純なプローブの結果が予想外に MISSING と表示された場合は、threejs-game-director/scripts/probe_asset_credentials.sh を使用してください。プロファイルを読み込み、3 つのプロバイダーすべてを一度にプローブします。

ダウンロード URL はすぐに期限切れになります。タスクの成功後、ただちにダウンロードしてください。

コマンド

python3 <this-skill-dir>/scripts/threejs_3d_asset.py --help

プレミアムなヒーローモデルのデフォルトである、テキストから 3D への生成：

python3 <this-skill-dir>/scripts/threejs_3d_asset.py text \
  --prompt "game-ready sci-fi hover bike, sleek armored panels, strong readable silhouette, layered hard-surface detail, PBR materials, clean topology, centered pivot, front facing, no text" \
  --model-version v3.1-20260211 --texture-quality detailed --geometry-quality detailed \
  --checkpoint artifacts/hover-bike-job.json \
  --wait --download --out-dir assets/models/hover-bike

生成したコンセプト画像からの、画像から 3D への生成：

python3 <this-skill-dir>/scripts/threejs_3d_asset.py image \
  --image assets/concepts/hover-bike-front.png --model-version v3.1-20260211 \
  --enable-image-autofix --texture-alignment original_image --texture-quality detailed \
  --wait --download --out-dir assets/models/hover-bike

ステータス確認、ダウンロード、後処理（texture_model、animate_prerigcheck、animate_rig、animate_retarget、conversion、stylize_model）：

python3 <this-skill-dir>/scripts/threejs_3d_asset.py status TASK_ID
python3 <this-skill-dir>/scripts/threejs_3d_asset.py download TASK_ID --out-dir assets/models
python3 <this-skill-dir>/scripts/threejs_3d_asset.py postprocess --type conversion \
  --original-task-id TASK_ID --format GLTF --face-limit 20000 --wait --download --out-dir assets/models/gltf

アニメーションキャラクターのパイプライン：生成、事前リギングチェック、上限付きの再試行による検証済みリグ、リターゲット、ダウンロードを、ボディプランに応じて実行します。チェックポイントを使用し、依存する作業に費用をかける前に各段階で停止して確認してください：

python3 <this-skill-dir>/scripts/threejs_3d_asset.py character-pipeline \
  --prompt "stylized cyber runner character, T-pose, full body, game-ready outfit, readable silhouette" \
  --animations preset:idle,preset:walk,preset:run,preset:jump \
  --checkpoint artifacts/cyber-runner-job.json --stop-after model \
  --out-dir assets/models/cyber-runner

# After inspecting the downloaded model/preview:
python3 <this-skill-dir>/scripts/threejs_3d_asset.py resume artifacts/cyber-runner-job.json --stop-after rig
# After inspecting the validated rig:
python3 <this-skill-dir>/scripts/threejs_3d_asset.py resume artifacts/cyber-runner-job.json --stop-after animations

python3 <this-skill-dir>/scripts/threejs_3d_asset.py character-pipeline \
  --prompt "stylized wolf, quadrupedal stance, all four legs planted and separated, full body" \
  --rig-type quadruped --animations preset:quadruped:walk \
  --checkpoint artifacts/wolf-job.json --stop-after model --out-dir assets/models/wolf

再開と復旧

--checkpoint PATH は text、image、postprocess、character-pipeline で任意に指定できます。タスク ID の受理直後に記録し、ステージのステータスとダウンロードファイルのフィンガープリントも記録します。API キーや署名付き出力 URL はチェックポイントに保存されません。ジョブごとに別のチェックポイントを使用してください。既存のチェックポイントは上書きせず、再開してください。また、同時使用はロックされます。

バックグラウンドで単一タスクを生成する場合は --wait を省略し、表示されたタスク ID／チェックポイントを保持して、後から resume CHECKPOINT を実行します。単一タスクの再開では、そのタスクのみを待機してダウンロードし、リギングは追加しません。キャラクターの再開では完了済みのステージを再利用し、--stop-after model|rig|animations で今回の実行を制限しない限り、アニメーションの処理まで続行します。認証情報は引き続き現在の環境から取得されます。チェックポイントには絶対ローカルパスが記録されるため、参照先のファイルは移動しないでください。

ヘルパーは、安全なステータス確認とダウンロードの読み取りを、上限付きのバックオフで再試行します。有料タスクの送信は再試行しません。認証情報の不足、クレジットの枯渇、無効な入力、一時的なエラー、送信結果が不確かな場合は、それぞれ区別して報告されます。処理が中断された場合は、最初からやり直さず、既存のジョブを再開してください。POST が成功した可能性があるもののタスク ID を受け取れなかった場合は、プロバイダーの履歴から ID を探し、resume CHECKPOINT --task-id RECOVERED_ID を使用してください。ID を捏造したり、確認せずに代わりのタスクを送信したりしないでください。復旧可能な ID がない場合は、重複課金の可能性がある操作を行う前に、不確実な状況を報告してください。

ディレクターを使用するゲームでは、ディレクターの references/asset-recovery.md に従ってください。生成の実行中も、独立して進められる実装を続けます。明示的にプロシージャル生成を指定するリクエストや外部サービスを使用しないリクエストは、生成アセットのデフォルト設定より優先されます。保留中のジョブとユーザーによる修正内容をプロジェクトノートに記録し、生成を繰り返すのではなく、完成済みのアセットを保持してください。

リギングとアニメーション

以下のルールに従うことで、コストのかかる失敗のほとんどを防げます。完全なパラメータ表と、その根拠となる測定値は references/api-notes.md にあります。

• キャラクターは1つに統合されたメッシュとして生成します。--quad と --generate-parts はオフにします（generate_parts を有効にするとテクスチャリングが無効になり、quad を有効にすると FBX 出力が強制されます）。
• 全身の T ポーズまたは A ポーズを必須とし、腕を胴体から離して左右対称にし、シルエットに小道具を融合させないようにします。リギングの前に、レンダリングプレビューで本当にそのポーズになっているか確認してください。そうでなければ再生成します。
• 最初に animate_prerigcheck を実行します（モデルのバージョン指定は不要で、費用もかかりません）。検出された rig_type を使用してください。riggable=false の場合は、無理にリギングせず、より明確なポーズで再生成します。
• リグのバージョンは体型に応じて選びます。 ヒューマノイドには、ツイストボーンと豊富な preset:biped:* ライブラリを備えた解剖学的スケルトンの v1.0-20240301 を使用します。v2.x の肢チェーンリガーは、装甲の有無にかかわらず、ヒューマノイドメッシュでは 16 回中 0 回の成功で、毎回非対称なチェーンを生成しました。クリーチャーには v2.5-20260210 を使用します。character-pipeline がこれを自動的に振り分けます。
• riggable=true でも、使用可能なリグが保証されるわけではありません。リターゲティングの前に、validate-rig rig-model.glb --rig-type biped を実行し、ボーンの有無とチェーンの深さの両方を確認してください。脚が1ボーンだけだと、すべてのクリップが歪みます。--force-rig を指定した場合も、リグ GLB がない、または不正な形式である場合は失敗です。自動リギングは非決定的です。失敗した場合は、モデルを再生成する前に、選択した予算の範囲内でリグタスク（約25クレジット）を再試行してください。装甲付きのハードサーフェスキャラクターでは、最も多くの再試行が必要です。
• animate_retarget には、生成タスク ID ではなくリグタスク ID を指定します。非二足歩行リグでは、1タスクにつき最大5つのプリセットをまとめて処理できます。まとめて処理したクリップは、リクエスト順に NlaTrack、NlaTrack.001、… として返されるため、インデックスで対応付け、インポート後に名前を変更してください。
• v1.0 リグのリターゲティングでは --model-version default を指定します。列挙型は明示的な v1.0-20240301 を HTTP 400 コード 2017 で拒否しますが、サーバーのデフォルト値なら処理できます。
• v1.0 のリターゲティングでは、必ず --out-format fbx を使用します（スクリプトで強制されます）。この経路で Tripo が生成する GLB のベイクでは、ツイストボーンのトランスフォームが誤った座標空間に書き込まれ、四肢が胴体に潰れてしまいます。v2.5 のクリーチャーのリターゲティングでは GLB で問題ありません。
• --animate-in-place は絶対に指定しないでください。 ベイクが破損します。v1.0 では四肢が反転して交差し、v2.5 ではスキニングが破綻します。ルートモーションはベイクしたままにし、インポート時に取り除いてください。エンジンのコード例は references/threejs-integration.md にあります。
• クリーチャーにはそれぞれ移動用プリセットを1つ割り当てます。また、preset:attack はありません（preset:slash または preset:shoot を使用してください）。クリーチャーのメッシュの姿勢によって、プリセットの見え方が変わります。直立したドラゴンに四足歩行の歩行アニメーションを適用すると、人が歩いているように見えるため、アニメーションが想定する姿勢でクリーチャーを生成してください。
• 地上を這い、飛行もするドラゴンのような複数の動作モードを持つクリーチャーには、同じモデルを2回リギングする必要があります。移動には地上用のリグタイプを、翼のチェーンには avian を使用します。
• Tripo のプリセットをリターゲティングする場合は --spec tripo（デフォルト）を使用します。--spec mixamo のリグは Tripo でリターゲティングできず、外部パイプライン専用です。
• ダウンロード後、validate-animation clip.glb を実行します（スケールトラック、四肢を引き伸ばすトランスレーション、極端な回転、クリップごとの長さとチャンネルの網羅率を検出します）。その後、gltf.animations の名前と数を確認してから、AnimationMixer に接続してください。

品質

マテリアル、シルエット、カメラからの見やすさ、スケール、ゲームでの使用上の制約を盛り込み、ユーザーのプロンプトを改善します。パフォーマンス予算に合わせた面数制限とテクスチャ品質で、GLB/PBR をリクエストします。モバイルでは、smart_low_poly、face_limit、または後処理によるローポリ化を優先します。生成した 3D モデルは主役となるコンテンツに使用し、周囲の小道具一式はプロシージャルに構築します。

組み込み後、ゲームを一時停止せずに動作を確認します。クリップの遷移、変形、ルートモーション、足の滑り、攻撃や接触のタイミングを確認してください。アニメーション作業では QA のモーション確認を行います。ダウンロードの成功やスケルトンの確認だけでは、アニメーションの品質が良いとは判断できません。

タスク ID、チェックポイントと出力のパス、モデルのバージョン、テクスチャとジオメトリの設定、アニメーション、変換設定、Three.js のインポートに関する注意事項、インポート前後のレンダラー診断、プレイ中のスクリーンショット、確認した動作、失敗した項目を報告してください。リードが統合レポートを作成できるよう、詳細な証拠をプロジェクトの成果物に記録してください。