react-three-start

react-three-start

@react-three/start は React Three Fiber 用のクライアントファーストなアプリシェルです。Vite／React のブートストラップ、ルート要素、フルスクリーンの Canvas、シーンの検出、DOM オーバーレイ、ラッパーの合成を担います。アプリの作成者は、主に src/ 以下にファイルを追加します。

プロジェクト構成

src/
  cube.scene.tsx      # rendered inside <Canvas>
  lights.scene.tsx    # rendered inside <Canvas>
  hud.dom.tsx         # rendered in the DOM overlay
start.config.ts       # optional framework config

react-three-start dev、react-three-start build、react-three-start preview を使用します。短縮エイリアスは r3s です。npx @react-three/start create my-app でアプリを作成します。

エントリーファイル

• src/**/*.scene.tsx ファイルは 3D レイヤーです。R3F のオブジェクト、ライト、カメラ、コントロール、物理ボディ、プロバイダーをデフォルトエクスポートします。
• src/**/*.dom.tsx ファイルは DOM オーバーレイレイヤーです。通常の React DOM UI をデフォルトエクスポートします。
• エントリーは自動的に検出され、パス順に並べられます。通常のアプリ構成では、手動でシーンレジストリーを作成しないでください。
• DOM オーバーレイのコンテンツはビューポート上に固定されます。デフォルトで挿入される Canvas では、オーバーレイコンテナーの pointer-events は none です。そのため、操作可能な DOM コントロールには pointerEvents: 'auto' を設定してください。

スロットとラッパー

@react-three/start から Scene または Dom をインポートするのは、検出対象の *.scene.tsx および *.dom.tsx エントリーファイル内だけにしてください。Vite プラグインがそれらのインポートを継続コンポーネントに書き換えます。

<Scene /> をインポートしてレンダリングするシーンファイルは、シーンラッパーになります。3D シーンの残りの部分を囲む必要があるプロバイダーには、ラッパーを使用してください。例：XR、物理演算、Suspense、コントロール、環境設定。ファイル名を並べた順序でネストの順序が決まります。

// src/00-xr.scene.tsx
import { Scene } from '@react-three/start'
import { Physics } from '@react-three/rapier'

export default function PhysicsWrapper() {
  return (
    <Physics>
      <Scene />
    </Physics>
  )
}

00-xr.scene.tsx       # outer wrapper
10-physics.scene.tsx  # inner wrapper
cube.scene.tsx        # leaf scene entry

<Dom /> をインポートしてレンダリングする DOM ファイルは、DOM ラッパーになります。Canvas を手動で管理する場合は、DOM ファイルから <Scene /> をインポートすることもできます。

Canvas の手動設定

デフォルトでは、react-three-start がフルスクリーンの Canvas を挿入し、その内部で <Scene /> をレンダリングします。レイアウト、シャドウ、カメラのプロパティ、XR ボタン、複数のパネルを自分で管理する必要がある場合は、挿入を無効にし、DOM エントリーから Canvas をレンダリングします。

// start.config.ts
export default {
  injectCanvas: false,
  title: 'My R3F app'
}

// src/app.dom.tsx
import { Canvas } from '@react-three/fiber'
import { Scene } from '@react-three/start'

export default function App() {
  return (
    <Canvas shadows camera={{ position: [0, 2, 6], fov: 45 }}>
      <Scene />
    </Canvas>
  )
}

start.config.ts では、injectCanvas、title、ネストされた vite 設定オブジェクトをエクスポートできます。CLI は vite を生成された Vite 設定とマージし、残りのオプションを reactThreeStart() に渡します。start.config.ts を優先してください。通常の Vite 設定を自分で管理する必要がある場合に限り、vite.config.ts を追加します。

エージェント向けの基本方針

• 他のシーンエントリーを囲む必要がない限り、新しいビジュアルコンテンツは小さな *.scene.tsx のリーフとして追加します。
• UI は *.dom.tsx として追加し、操作可能なオーバーレイ要素ではポインターイベントを明示的に有効にします。
• ラッパーの順序にはインポート順ではなく、数値のファイル名プレフィックスを使用します。
• Scene と Dom のインポートはエントリーファイル内だけにし、通常の React コンポーネントは通常のインポートで渡します。
• デフォルトのフルスクリーン Canvas では制約が大きすぎる場合に限り、Canvas を手動で設定します。