react-three-fiber-game

React Three Fiber ゲーム

概要

3D ランタイムが React アプリケーション内にある場合は、このスキルを使用してください。これはプラグインにおけるデフォルトの React ネイティブな 3D の選択肢です。アプリのシェル、設定、ストアフロント、エディター画面、または周辺のプロダクトで既に React を使用している場合は、バニラの Three.js よりも優先してください。

推奨スタック：

• @react-three/fiber
• three
• @react-three/drei
• @react-three/rapier
• @react-three/postprocessing
• アクセシビリティに配慮した操作が重要な場合は @react-three/a11y
• 通常の React ツリー内の DOM オーバーレイ

このスキルを使う場合

• プロジェクトで既に React を使用している
• 3D シーンがアプリの他の部分と状態を共有する必要がある
• 宣言的なシーン構成によって明確なメリットが得られる
• チームがすべてのヘルパーレイヤーを手作業で構築する代わりに、pmndrs のヘルパーを使いたい

このスキルを使わない場合

• アプリが React ベースではない
• プロジェクトが React との連携を最小限に抑えた、よりシンプルな命令型ランタイムを求めている
• 問題がランタイム構成ではなく、アセットのパッケージングに関するものである

最適な用途

• 3D コンフィギュレーターや、ツールを多用するブラウザプロダクト
• ゲームやシーンを埋め込んだ React アプリ
• 既存の React アプリ内の 3D メニュー、エディター、ワールドマップ
• 共有アプリ状態と Canvas 以外のシェルに依存する 3D ゲーム UI

基本ルール

1. シミュレーションの状態はレンダーコンポーネントの外部に保持します。
   • React コンポーネントはシーン構成を記述するものであり、ゲームプレイルールの信頼できる情報源にはしないでください。
2. React の状態とシーンの状態は意図的に使い分けます。
   • 共有 UI 状態はアプリの状態として保持できます。
   • 高頻度のシミュレーションによって、不要な React の更新がアプリ全体に発生しないようにします。
3. pmndrs のヘルパーを意図的に使います。
   • コントロール、ローダー、ヘルパー、環境、一般的なシーンプリミティブには Drei を使用します。
   • 物理演算の統合には @react-three/rapier を使用します。
   • オプションのエフェクトには @react-three/postprocessing を使用します。
   • 操作モデルにアクセシブルなシーンのセマンティクスが有効な場合は @react-three/a11y を使用します。
4. HUD、設定、メニューはデフォルトで DOM 内に配置します。
5. スターターの足場は視覚的に控えめにします。
   • コンパクトな目標またはステータス表示を 1 つと、一時的なプロンプトから始めます。
   • メモ、マップ、複数ステップのチェックリストは、開くまで折りたたんでおきます。
   • Canvas の周囲を、同じくらい目立つガラス風カードで囲まないでください。

アーキテクチャの指針

• Canvas を所有する専用のシーンルートコンポーネントを使用します。
• カメラリグとコントロールコンポーネントは、ゲームプレイシステムから分離します。
• ローダーとアセットのラッパーは予測しやすい構成にします。
• 明示的な状態境界を通じて、DOM オーバーレイと 3D シーンを連携させます。
• システムに厳密な命令型制御が必要な場合は、すべてを宣言的なパターンに無理に押し込まず、分離します。
• シーンをすぐにプレイできる場合は、初期オーバーレイを最小限に抑え、オンボーディングの多くをワールドに任せます。

アンチパターン

• React コンポーネントをゲームプレイ状態のストアとして扱う
• アプリ全体の状態を通じて、フレームごとの重い変更を伝播させる
• プロジェクトによりシンプルな命令型ランタイムが必要なのに、React が使えるという理由だけで R3F を使用する
• デフォルトで HUD やインベントリ UI を 3D シーン内に構築する
• ビューポートのあらゆる端を大きなカードで占める初期の足場を提供する

参考資料

• 共通アーキテクチャ：../web-game-foundations/SKILL.md
• フロントエンドの方針：../game-ui-frontend/SKILL.md
• 3D HUD レイアウトパターン：../../references/three-hud-layout-patterns.md
• React Three Fiber スタック：../../references/react-three-fiber-stack.md
• React スターター：../../references/react-three-fiber-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