web3d-runtime

web3d-runtime — あらゆる GPU でシーンを実行し、その速さを証明できます

three.js の WebGPU 対応は急速に進化しています。r186 では、r180 で警告されていた箇所が例外を投げ、ポストプロセッシングのエントリポイントが改名され、Clock が非推奨になりました。それでも、同じ API の下には WebGL2 バックエンドが引き続き用意されています。ここでのバグの多くは目立ちません。シーンはレンダリングされますが、表示は正しくありません。そのため、このスキルではまず失敗例を取り上げ、それからパターンを説明します。

最初のアクション — 調査してから報告する

1. バージョン。 package.json から three、@react-three/fiber、@react-three/drei を確認します。ここに記載されている情報は r186 に固定されています。別のリリースを使用している場合は、名前をそのまま信頼する前に references/renderer-and-loop.md → Version notes を確認します。
2. レンダラー。 three/webgpu の WebGPURenderer ですか、それとも従来の WebGLRenderer ですか？ ShaderMaterial、RawShaderMaterial、onBeforeCompile をカスタムで使用している箇所はありますか？ これらは WebGPU では動作しません（注意点）。
3. ループ。 フレームを管理するのはどれですか？ setAnimationLoop、R3F の useFrame、それとも複数の requestAnimationFrame ですか（バグです。シーンごとにクロックは 1 つです）。
4. 速度の根拠。 Inspector、タイムスタンプ、最も性能の低い対象環境で負荷をかけた状態の FPS など、測定結果はありますか？ それとも、感覚だけですか？

領域 · 現状 · 問題 · 修正 の表を報告し、次のアクションを 1 つだけ示します。

機能の段階

シーンごとに上から適切な段階を選びます。どの段階でも、ページが正常に動作する必要があります。

1. WebGPU — new WebGPURenderer() を実行し、その後 await renderer.init() を呼び出します。
2. 同じレンダラーの WebGL2 バックエンド — WebGPU が利用できない場合は自動的に使用されます（running under WebGL2 backend とログに出力されます）。forceWebGL: true で強制できます。この場合、計算負荷の高い機能には軽量な経路が必要です。init() の後に renderer.backend.isWebGPUBackend で判定します。
3. 穏やかな表示 — WebGL がまったく使えない場合、モーションの軽減が有効な場合、または復旧できないデバイスロストが発生した場合は、静止画像または CSS／SVG で、文字が完全に読める状態を保ちます。これは sheleg-design の「穏やかな表示に切り替える」ルールを 3D シーンに適用したものです。

注意点 — r186、いずれも気づきにくいか、意外な挙動です

• await renderer.init() の前に render() を呼ぶと例外が発生します（そのため、clear()、hasFeature()、 initTexture() を実行してください）。setAnimationLoop は自ら初期化を待機します。renderAsync などは r181 以降、非推奨です。
• positionNode はスキニング、モーフィング、インスタンシングの後に位置を置き換えます。 positionLocal.add(offset) ならそれらを維持できますが、positionGeometry.add(...) や buffer.element(instanceIndex) だけでは、すべてのインスタンスが一点に潰れてしまいます。パーティクルでは 公式のパターンを使ってください。スプライトまたはポイントマテリアルで positionNode = buffer.toAttribute() を指定します。
• JS の再代入はシェーダーのストアではありません。Fn 内で a = a.add(1) としても、JS の名前が再束縛されるだけで 何も出力されません。.toVar() の後に .assign()／.addAssign() を使ってください。ノードに対する JS の if や 三項演算子も同じ問題があるため、If／select を使ってください。
• アトミック演算の前に storage(buf, 'uint', n).toAtomic() が必要です。
• **computeAsync() は GPU の処理完了を待ちません。**結果を CPU に読み戻すのは renderer.getArrayBufferAsync() だけです （r186 では再利用可能な THREE.ReadbackBuffer を使用できます）。
• ShaderMaterial、RawShaderMaterial、onBeforeCompile に WebGPU 対応のマッピングはありません — オブジェクトは 「互換性なし」エラーとともに、通常のノードマテリアルとしてレンダリングされます。TSL に移植してください。drei の約 20 個のコンポーネントはこれらを基盤としており、同じように動作しません。
• **アダプターは互換モードで要求されます。**互換モードしか提供しないデバイスでは、MSAA が通知なしに無効になります。
• WebGPURenderer では alpha のデフォルト値が true です（WebGLRenderer では false）。不透明なキャンバスを前提とした 移植では、ページがキャンバス越しに見えてしまいます。
• PostProcessing は RenderPipeline になりました。****Clock は非推奨です — Timer（core）を使ってください。 WebGPU では PCFSoftShadowMap が削除されました（r183 以降、PCFShadowMap がソフトシャドウです）。 renderer.dispose() は非同期です。
• デバイスロスト：renderer.onDeviceLost を使ってください（検証エラーやメモリ不足エラーには renderer.onError を使います）。 これは両方のバックエンドにあります。WebGPU デバイスに直接フックすると、WebGL2 へのフォールバック時に動作しなくなります。
• **R3F 9.8.1 のデフォルトは three.js と異なります。**ACES トーンマッピングが有効で、shadows={true} は削除済みの ソフトシャドウマップを選択します（shadows="percentage" を使ってください）。また、useFrame のデルタ値はクランプされません。

手順

1. レンダラーとループ — レンダラーは 1 つ、await init()、setAnimationLoop は 1 つ、Timer も 1 つです （references/renderer-and-loop.md）。
2. マテリアルとシェーダー は TSL で記述し、パーティクル単位またはインスタンス単位の処理にはコンピュートを使います （references/tsl-and-compute.md）。
3. **事前ウォームアップ：**最初に表示されるフレームの前に await renderer.compileAsync(scene, camera) を実行し （コンピュートには compileComputeAsync も実行）、最初の操作で引っかからないようにします。
4. 最も性能の低い対象で計測し、Inspector またはタイムスタンプクエリを使ってから、予算を割り当てます （references/performance-and-r3f.md）。
5. **段階的に機能を落とす：**モーション低減、WebGPU 非対応、デバイスロスト、タブ非表示にはそれぞれ明記された 分岐があり、各分岐の動作を確認済みです。
6. **後片付け：**ジオメトリ、マテリアル、テクスチャ、レンダーターゲットを破棄します。 await renderer.dispose() を実行します。

必要なものがない場合

• このホストにツールがまったくない場合 → コマンドとコードを記述し、実行結果は記述しません。計測していないサイズ、 パス、フレーム時間、「完了」は捏造された証拠です。そのようなチェックにはそれぞれ NOT_RUN と記し、人が実行すべき内容を説明します。
• このホストにブラウザーや GPU がない場合 → ビルド、型チェック、レビューを行います。視覚的な確認とフレーム時間の判定には NOT_RUN と記し、人が使うべきページとデバイスを示します。コードを読んだだけで「滑らか」と報告してはいけません。
• プロジェクトが古い three.js を使っている場合 → リリース間の差を明記します。r186 の名前をそのまま適用せず、 オペレーターの許可なしに依存関係をアップグレードしてはいけません。
• R3F プロジェクトで WebGPU を使う場合 → references/performance-and-r3f.md にある非同期 gl ファクトリーパターンを使います。 切り替え前に、シーンで使われている WebGPU では動作しない drei コンポーネントを列挙します。

参考資料

読む項目	読むタイミング
references/renderer-and-loop.md	レンダラー、フォールバック、ループとクロック、色とトーンマッピング、ポストプロセッシング、デバイスロスト、破棄処理を作成するとき
references/tsl-and-compute.md	TSL マテリアルやシェーダー、コンピュートパス、パーティクル、アトミック操作、読み戻しを作成するとき、または GLSL を移植するとき
references/performance-and-r3f.md	フレーム時間、ドローコール、メモリの計測や修正を行うとき、WebGPU で React Three Fiber を実行するとき、WebGPU で drei を使うとき

アセットファイルと予算については web3d-assets、アニメーションの作成については web3d-animation を参照してください。公開されている webgpu-threejs-tsl スキル（dgreenheck）は、このスキルの落とし穴を先に示す構成の参考になりました。 r186 に照らしてサンプルを再検証した際に見つかった誤りは、上記の落とし穴に含まれています。

トリガー

このスキルに誘導するその他のフレーズ：「WGSL」、「compute shader」／「コンピュートシェーダー」、「particles collapsed」／「パーティクルがつぶれた」、「device lost」／「デバイスロスト」、「React Three Fiber」、「post-processing」／「ポストプロセッシング」、「WebGL fallback」。

0.2.4 の説明からこちらに移動しました：「three.js WebGPU」、「3D シーンが遅い」。