three-webgl-game

Three WebGL ゲーム

概要

このスキルは、プラグインにおけるデフォルトの非 React 向け 3D パスに使用します。一般的な WebGL のアドバイスではなく、ブラウザー向け 3D 開発のための、明確な方針を持つスタックです。

• three
• TypeScript
• Vite
• GLB または glTF 2.0 アセット
• GLTFLoader、DRACOLoader、KTX2Loader などの Three.js ローダー
• 物理演算用の Rapier JS
• GPU とフレームのデバッグ用の SpectorJS
• HUD、メニュー、設定用の DOM オーバーレイ

シーン、カメラ、レンダラー、ゲームループを直接制御したいプロジェクトで、このスキルを使用してください。アプリがすでに React で構成されている場合は、代わりに ../react-three-fiber-game/SKILL.md を参照してください。

このスキルを使用する場合

• アプリが React を中心とせず、プレーンな TypeScript または Vite で構成されている
• プロジェクトでレンダーループを命令的に直接制御したい
• ユーザーが Three.js を明示的に求めている
• 実行環境で、シーン、カメラ、ローダー、物理演算をエンジンのように制御する必要がある

このスキルを使用しない場合

• 3D シーンが既存の React アプリ内にある
• 主な課題が実行時コードではなく、配布アセットの最適化である
• ユーザーが Babylon.js または PlayCanvas を明示的に選択している

基本ルール

1. シミュレーションの状態は Three.js オブジェクトの外部に保持します。
   • ゲームルール、AI、クエストの状態、タイマー、進行状況をメッシュやマテリアル内に持たせないでください。
2. レンダーグラフはアダプターとして扱います。
   • シーングラフ、カメラ、マテリアル、ローダー、ポストプロセスは、シミュレーションの状態の上に重ねる表示上の要素です。
3. カメラの動作を明確にします。
   • オービット、追従、チェイス、レール、一人称視点の各スタイルには、それぞれ固有の制御境界が必要です。
4. 表現上どうしても必要な場合を除き、UI を WebGL の外に置きます。
   • メニュー、HUD、インベントリ、設定には、デフォルトで DOM を使用してください。
5. 配布モデルの形式には、デフォルトで GLB または glTF 2.0 を使用します。
   • 実行環境を DCC ネイティブ形式に依存させないでください。
6. ゲームに本格的な 3D 物理演算や衝突応答がある場合は、その場しのぎの衝突コードではなく Rapier を使用します。
7. 最初にプレイできる画面は、装飾を控えたシンプルなものにします。
   • コンパクトな目標またはステータス表示を 1 つと、一時的なプロンプトを基本にします。
   • 長いメモ、背景設定、操作方法の説明は、求められるまで折りたたんでおきます。
   • 通常のプレイ中に、同じ比重のカードを複数並べてシーンを囲まないでください。

初期スキャフォールドの UX

探索、移動、キャラクター操作のプロトタイプでは、要素を絞ったシェルから始めます。

• 画面の端に沿った目標チップを 1 つ
• 一時的な操作ヒントを 1 つ
• 任意で、コンパクトなステータスバーを 1 つ

ゲームループで本当に必要な場合に限り、大きな UI 領域を追加してください。ジャーナル、クエストログ、コーデックス、マップ、設定の画面は、デフォルトでビューポートを占有せず、必要に応じて開くようにします。

推奨構成

../../references/three-webgl-architecture.md のモジュール構成を使用し、次の境界を明確に保ちます。

• simulation/：ルール、進行状況、状態、AI
• render/app/：レンダラー、シーン、カメラ、リサイズ、コンテキストのライフサイクル
• render/loaders/：GLTF、Draco、KTX2、テクスチャ、環境の読み込み
• render/objects/：メッシュのインスタンス化と破棄
• render/materials/：マテリアルの設定とシェーダーの境界
• physics/：Rapier のワールド、ボディ、コライダー、シミュレーションのブリッジ
• ui/：DOM オーバーレイとメニュー
• diagnostics/：デバッグ切り替え、パフォーマンス計測、キャプチャ用フック

適したシナリオ

• 探索デモ
• 軽量な 3D 戦闘プロトタイプ
• 乗り物や移動のプロトタイプ
• ゲームプレイ要素を含む、シーン主導の商品またはワールドのショーケース
• マテリアル、ライティング、ポストプロセスを主軸とする体験
• カメラの移動と奥行きの把握が中心となる 3D ゲーム

ローダー、アセット、ポストプロセス

• 配布する3Dコンテンツには、まず GLTFLoader を使用します。
• DRACOLoader または Meshopt 対応の最適化は、場当たり的な実行時パッチではなく、アセットパイプラインの一部として導入します。
• アセットパイプラインで圧縮テクスチャを提供する場合は、KTX2Loader を使用します。
• まず Three.js 組み込みのレンダリング機能とポストプロセスユーティリティを使用します。プロジェクトで実際に必要になる場合にのみ、より重い抽象化を追加します。
• ポストプロセスは任意にし、効果を測定できるようにします。ブルームや色のエフェクトによって、ゲームプレイの視認性を損なわないようにします。

シェーダーとマテリアルに関するガイダンス

• カスタムシェーダーを使う前に、まず標準の Three.js マテリアルと適切なライティングを使用します。
• カスタムシェーダーは、目標とするビジュアルを実現するために本当に必要な場合にのみ使用します。
• シェーダーのパラメーターは、偶発的なシーンの変更ではなく、ゲームの状態に基づいて設定します。
• マテリアルスタックが複雑になった場合は、シーンコード内にシェーダーの設定を散在させず、マテリアルファクトリーの内部にまとめます。

ブラウザーの安全性

• リサイズを明示的に処理します。
• WebGL コンテキストの喪失と復旧を想定します。
• 不安定な GPU 処理に備えて、フォールバックまたは機能を制限したモードを検討します。
• テクスチャサイズ、ジオメトリ数、ドローコールの増加、ポストプロセスのコストに注意します。
• シーンが正しく動作しない場合や、フレームコストが不明な場合は SpectorJS を使用します。

対応範囲に関する注意

このプラグインが Phaser トラックと同等の3D対応範囲を提供すると主張しないでください。本格的な3D実装に対応していますが、プラグイン全体としては2Dを優先しています。

参考資料

• 共通アーキテクチャ：../web-game-foundations/SKILL.md
• フロントエンドの方針：../game-ui-frontend/SKILL.md
• 3D HUD レイアウトパターン：../../references/three-hud-layout-patterns.md
• Three.js エコシステム：../../references/threejs-stack.md
• Three.js の構成：../../references/three-webgl-architecture.md
• Vanilla のスターター：../../references/threejs-vanilla-starter.md
• GLB ローダーのスターター：../../references/gltf-loading-starter.md
• Rapier のスターター：../../references/rapier-integration-starter.md
• 3D アセットパイプライン：../../references/web-3d-asset-pipeline.md
• WebGL のデバッグとパフォーマンス：../../references/webgl-debugging-and-performance.md