webg

コーディングAIの皆さまへ

初回のアプリ開発では、まず開発の入口と実行例で目的に合う出発点を一つ選んでください。人間向けの案内と同じ実行例、コード、確認ポイントを使います。この付録は、その後にAPIや内部接続を調べる際の参照先を説明します。

コアの読み込み方式を揃える

最初に、アプリがwebg/の個別モジュール版とlib/webg.core.min.jsの どちらを使うか確認してください。統合版ではWebgApp、Shapeなどを 名前付きimportで取り出します。APIの意味は本書と元ソースで確認できます。 サンプルの移植では、共有JS・再export・動的importまで同じ方式へ揃えます。 変換コマンドと確認順序は付録C_統合版の利用.mdにまとめています。

webg利用者を支援するためのガイドライン

この付録は、webgを用いて3Dアプリケーションを開発する利用者を、コーディングAIが支援する場面を想定して作成されました。 ここで想定するAIは、一般的な3Dエンジンや外部ライブラリの知識をそのまま適用するのではなく、webgという自己完結したライブラリの設計思想に基づき、何をどの順番で参照すべきかを判断する支援者です。

webgを利用するアプリケーションでは、まずWebgAppが初期化、更新ループ、カメラ、入力、UI、描画タイミングを統合します。 3D形状はSpace、Node、Shape、ModelAssetによって構成され、この部分は標準Forward描画でも、物理ベースレンダリング(Physically-Based Rendering:PBR)を行う統合レンダリングでも共通です。

webg 3.0では、金属度・粗さ方式のPBR、画像ベース照明(Image-Based Lighting:IBL)、PBR G-buffer、透明PBR、画面空間Transmission、汎用の手続きテクスチャが、主要な表現基盤として加わりました。PBRはmetallicとroughnessをマテリアルへ追加し、マテリアル、直接光源、高輝度範囲(High Dynamic Range:HDR)の環境、事前積分済みIBL、カメラ、シャドウ、画面空間効果、トーンマッピングを線形HDRの処理フローへ接続する仕組みです。

大きな選択は形状の作り方ではなく、照明と画面効果をどの描画経路で処理するかにあります。 小さな構成で形状を直接描画する場合は、SmoothShaderを使う標準Forward描画を選びます。 PBR G-buffer、IBL、複数光源、SSAO、SSR、透明・屈折、Fog、Bloomなどを一つのHDR画像へ統合する場合は、ComputeEffectPipelineを使うPBR統合レンダリングを選びます。 どちらもWebgAppのフレーム処理内で構成し、同じSpace、Node、Shape、カメラ、入力、UIを使います。

WebgApp
  ├─ 初期化、更新ループ、カメラ、入力、UI
  ├─ Space、Node、Shape、ModelAsset
  └─ 照明・最終描画経路の選択
       ├─ 標準Forward描画
       │    └─ SmoothShaderで形状を直接描画
       └─ PBR統合レンダリング
            └─ PBR G-buffer + ComputeEffectPipeline
                 ├─ 直接光 + IBL + Shadow + SSAO
                 ├─ SSR + 透明PBR + Transmission
                 └─ Fog + Bloom + Tone Mappingなど

この図の上側は、アプリケーションの共通基盤です。 下側の分岐は、同じシーンと形状をどの照明経路で最終画面へ変換するかを示します。 PBR統合レンダリングでは、既存のWebgApp、Space、Shapeをそのまま基盤として利用し、ComputeEffectPipelineを後段へ接続します。 単純な画面は、PBRとコンピュートシェーダーを利用できる環境でも、標準Forward描画を入口にすると構成を小さく保てます。

本書において重要なのは、webgが外部の3Dライブラリに依存せず、描画、シーン管理、モデル、アニメーション、UI、入力、物理、音声、診断、GPU計算を内部に持つことです。 AIが技術支援を行う際は、「一般的なWebGPU実装はこうであるはずだ」あるいは「Three.jsではこうだから同様だろう」といった推測よりも、本書、samples、headless_tests、unittest、webg本体の現行実装を優先してください。

一般論は概念を説明する補助として利用できますが、公開API、引数、形式、ライフサイクル、例外条件の最終判断はwebgの資料と実装に置きます。 本付録の目的は、利用者が何を作りたいか、どの層で問題が起きているかに応じて、AIが参照する章、サンプル、自動テスト、ブラウザPOC、コア実装を選ぶための読書地図を提供することです。とくにPBRでは、完成画像だけからマテリアル値を推測せず、G-buffer、光源、IBL、透明合成、最終表示のどの段階まで正しいかを分けて調べます。

SceneYAMLから作品を起動する

作品の配置、PBR、Compute物理をまとめて記述する場合は、webg/app/index.jsのcreateWebgSceneApp({ project: "./scene.yaml" })を入口にします。WebgSceneAppはWebgAppを基盤として、SceneDefinitionによる検証、PbrRenderer、ScenePhysics、アニメーション、Node同期を接続します。独自の描画処理を組む場合はWebgAppを直接使います。

SceneYAMLは作品全体の配置、inline mesh、マテリアル、物理、renderer設定を記述し、ModelYAMLは再利用するモデルのmesh、Node階層、skeleton、animationを記述します。読み込み後はそれぞれSceneAssetとModelAssetとして扱います。両クラスはDocumentAssetを継承し、SceneYaml.jsの解析処理と原文・コメント保持を共有します。

YAMLを編集・保存する処理ではgetSourceDocument()で原文を扱います。値が未変更ならtoYAMLText()は原文を返し、コメント付き文書の値だけを変更した場合は保存時に例外を返します。更新済みの原文はfromYAML()へ渡します。JSONへの変換はallowCommentLoss: trueを指定します。

物理付きinline meshは、表示をmesh、衝突形状をphysics.shapeのBox・Sphere・Capsuleで記述します。08〜09章、samples/model_yaml、samples/scene_model_yaml、samples/edit_yamlを参照してください。

PBRのマテリアルと光を合わせて確認する

PBRの名称からは、金属、樹脂、陶器、石、ガラスといった表面マテリアルのモデルが注目されがちです。しかし、同じマテリアルでも、光源の方向、距離、形、大きさ、環境内の高輝度領域、露出が変われば見え方は大きく変わります。AIは「金属が金色に見えない」という症状をbase colorだけの問題へ限定せず、金属度、粗さ、Fresnel反射、直接光、鏡面IBL、SSR、トーンマッピングを順に確認してください。

webgのPBRは、金属度・粗さ方式を使います。非金属のbase colorは主に拡散反射色、金属のbase colorは主に鏡面反射のF0へ使われます。specularは非金属の基準鏡面反射率、roughnessは微細面法線の分布、metallicは非金属と金属の混合、occlusionは環境光の遮蔽を表します。発光は照明とは別の線形HDR色として扱います。

環境マップは背景画像であるだけでなく、全方向から届く光の入力です。PbrEnvironmentは、元のradiance、拡散反射用のirradiance、roughness別に事前積分したprefiltered specular、BRDF LUTを、遅延照明、PBR向けSSR、透明PBRで共有できるGPUリソースにします。environmentBackground: falseを選ぶとIBLだけを利用し、画面背景にはclearColorを表示できます。環境光を有効にした状態では固定ambientを重ねないため、ambientは0にします。

PBRの計算は線形HDRで行い、表示直前に一度だけトーンマッピングとsRGB変換を行います。base colorやclear colorは表示用sRGB、照明後の値は線形HDRとして役割を分けます。Bloom、Fog、SSR、Transmissionはトーンマッピング前、EdgeとVignetteは表示色へ変換した後に置きます。

光量設定では、相対値を使うunitSystem: "relative"と、測光単位を使うunitSystem: "photometric"のどちらかに単位系をそろえます。相対値ではシーン内の見た目を基準に強度を調整し、測光単位では点光源の光度、露出、EV100を同じ単位系で扱います。シーンが暗い場合は、直接光、IBL、露出の順に確認します。

glTF 2.0 coreのPBR入力は、GltfShapeがbaseColorFactor、metallicFactor、roughnessFactor、Normal、Occlusion、Emissiveの各テクスチャ、emissiveFactor、alphaModeへ変換します。一方、KHR_materials_transmission、KHR_materials_ior、KHR_materials_volumeを画面空間Transmissionへ接続する場合は、webg独自の透明・屈折設定へ専用の入力処理を加えます。glTF coreの読み込み対応とwebg独自機能の対応範囲を分けて判断します。

WebgAppを中心に考える

アプリケーションの共通基盤

WebgAppはCanvasの初期化に加えて、Screen、GPUコンテキスト、シーン、標準シェーダー、カメラ、入力、Message、HUD、Overlay Panel、DebugDock、フレーム処理を一つのアプリケーション構造へまとめます。

利用者が標準Forward描画を使う場合も、PBR統合レンダリングを使う場合も、次の処理は共通です。

描画経路が変わっても、モデルの読み込み、Nodeの移動、アニメーションの更新、カメラの操作、UIの構築は既存の体系を継続して利用できます。 AIは、照明方式を変更するときも、アプリケーションの共通基盤を保ったまま描画経路だけを切り替える提案を行います。

3D形状と配置は共通である

SpaceはシーンのNode階層を管理し、Shapeは頂点、法線、UV、複数のmaterial slot、三角形ごとのmaterial番号などを保持します。 ModelAssetから展開されたモデルも、最終的にはNodeとShapeとしてシーンへ配置されます。

標準Forward描画では、これらのShapeをSmoothShaderが直接描画します。 PBR統合レンダリングでは、同じSpaceとShapeをGeometryBufferPassがPBR G-bufferへ描画し、後段で照明を計算します。 内部で使うシェーダーと出力先が変わっても、同じモデルをNodeとShapeとして各描画経路へ渡せます。

PBR統合レンダリングではG-bufferへ渡す表面のマテリアル情報をそろえます。 base color、specular、roughness、metallic、occlusion、発光を表す値を用途に応じて指定し、欠落値はプロパティ名付きの例外として確認できる状態にします。発光はemissive_factorと任意のemissive_texture、または従来のscalar emissiveのどちらか一つの入口へそろえます。

照明と最終描画経路を選ぶ

標準Forward描画

標準Forward描画では、形状を描くときにSmoothShaderが照明を評価し、その結果をCanvasへ出力します。 構成が小さく、3Dシーンを短い経路で描画できることが利点です。

次の場合は、標準Forward描画を最初に検討します。

この経路ではWebgAppの通常のフレーム処理を利用します。 標準Forward描画ではWebgAppがカメラ状態とコマンドエンコーダーを管理し、PBR統合描画ではComputeEffectPipelineが各段階を接続します。 Space.draw(eye)による単純な描画は標準Forward経路として保ち、PBR統合用のG-bufferやフレーム状態はComputeEffectPipelineの経路へまとめます。

PBR統合レンダリング

PBR統合レンダリングでは、最初に不透明Shapeの表面情報をPBR G-bufferへ保存し、そのテクスチャを使って直接光、IBL、画面効果を計算します。 ComputeEffectPipelineは、G-buffer、Shadow、SSAO、PBR遅延照明、SSR、透明PBRとTransmission、Fog、Toon、DoF、Bloom、Tone Mapping、Edge、Vignetteを一つの順序へ接続します。

透明分類はmaterialのalpha_modeを優先し、OPAQUE、MASK、BLENDを区別します。 alpha_modeを省略したマテリアルでは、独立したalphaが1.0未満ならBLENDとして扱います。 color[3]はテクスチャ混合率として読み、透明度はalphaで指定します。 一つのShapeに不透明と半透明の三角形が混在しても、全Shape横断で透明三角形を奥から手前へ並べます。 Pipeline利用側へ透明用Render Passを追加する提案はせず、roughnessによる背景ぼけ、透明表面のGGX反射、Transmissionによる屈折と吸収を内部のTransparencyPassへ任せます。

次の場合は、PBR統合レンダリングを検討します。

PBR統合レンダリングもWebgAppの中で動作します。 onBeforeDrawでpipeline.renderScene()を呼び、onAfterDraw3dでpipeline.encode()と最終表示を行います。 両方には同じcameraFrameを渡します。

WebgAppの状態更新
  -> onBeforeDraw
       -> Shadow MapとG-bufferを描画
  -> onAfterDraw3d
       -> 照明と画面効果を記録
       -> 完成したテクスチャをCanvasへ表示
       -> HUD用の深度付きパスへ戻る

ComputeEffectPipelineはPBR統合レンダリングの入口です。アプリケーションの入口で、標準Forward描画を使うか、PBR統合レンダリングを使うかを明示的に選びます。

PBR統合の処理順を維持する

PBR統合レンダリングでは、各効果を単に有効にするだけでなく、入力の意味を保つ順序が重要です。

Shadow Map
  -> PBR G-buffer
  -> PBR遅延照明(直接光 + IBL、線形HDR)
  -> SSRで鏡面IBLを画面内反射へ置換
  -> 透明PBR + Transmission
  -> Fog -> Toon -> DoF -> Bloom
  -> Tone Mapping + sRGB変換
  -> Edge -> Vignette
  -> Canvas表示 -> HUD

SSRはcomposer.mode: "pbr-ssr"で、画面内の交差を確認できた範囲だけ鏡面IBLをSSRへ置き換え、交差がない範囲には元のIBLを残します。透明物は不透明G-bufferと分けて前方描画へ送り、PbrForwardShaderが不透明物と同じPbrBrdf.jsを使い、直接光、Shadow、IBLを同じGGXモデルで評価します。

Transmissionはentry面で空気から媒質へ屈折し、透明物内のexit面を探索し、媒質から空気へ再屈折して背景を探します。内部光路長にはBeer–Lambert吸収を適用します。背景交点へ到達できないレイには、transmissionRayMissFallbackで"auto"、"environment"、"clear"、"constant"を選びます。これは隠れた形状を推測するフォールバックではなく、観測できない背景を何で表すかを明示する設定です。

"environment"は環境radianceを必須とし、不足時は設定エラーとして知らせます。"constant"は表示用sRGBのtransmissionRayMissColorを必須とします。内部境界が見つからず外向き方向を決められない場合は、environment方向を推測せず、constant以外のmodeではclear colorを使います。

GPU状態を先に更新する処理は別の応用である

GPU粒子、布、物理、手続きテクスチャのように、画面を描く前にGPU上の状態を更新する処理は、照明経路の分岐とは別の応用です。 この場合もWebgAppを利用できますが、computeFrame: trueとonComputeFrameを使います。

WebgApp computeFrame
  -> 状態を更新するコンピュートパス
  -> 最新状態を読むレンダーパス
  -> コマンドバッファを送信

この処理は、大量の状態をGPU上で更新し、その結果をCPUへ戻さず描画へ渡すために使います。 遅延照明を使うかどうかとは別に、照明経路とGPUシミュレーションの経路をそれぞれ選びます。

自己完結した設計思想の理解

webgは、描画、シーン、モデル、アニメーション、UI、入力、診断、GPU計算を一つの設計規則で接続する自己完結したライブラリです。

カメラはcameraRig $\rightarrow$ cameraRod $\rightarrow$ eye、シーンと形状はSpace $\rightarrow$ Node $\rightarrow$ Shapeで構成します。 ModelAsset $\rightarrow$ build() $\rightarrow$ instantiate()は共通リソースと個別インスタンスを分け、clip $\rightarrow$ pattern $\rightarrow$ action $\rightarrow$ stateはアニメーションを段階化します。

AIは、最初にwebg独自の定義と各機能が担当する処理を確認し、その後で一般的な3DやWebGPUの概念と対応付けてください。 一般論を先に当てはめると、深度規則、色空間、カメラ状態、GPUリソースを管理する箇所を取り違えることがあります。

手続きテクスチャをPBR入力として扱う

webgの手続きテクスチャは、ProceduralTileSpecでタイル寸法、模様、目地、表面appearanceを定義し、ComputeProceduralTileでColor、Height、NormalをGPU生成する仕組みです。ProceduralMaterialsがpresetの選択、生成結果の保持、PBRマテリアル設定、Shapeへの適用、破棄をまとめます。

ProceduralTileSpec
  -> ComputeProceduralTile
       -> Color texture
       -> Height texture
       -> Normal texture
  -> ProceduralMaterial
       -> Shapeの実寸UVとPBRマテリアルへ適用

直方体へ実寸のタイル、石、木、ビニールを適用する場合は、Primitive.mapRealCuboid()で各面へメートル単位のUVを作ります。Primitive.mapCube()は画像atlas用として使い分けます。createPreset()のscaleは「テクスチャの大きさ」の倍率で、scale: 10は模様を10倍の大きさで表示し、面上の反復回数を10分の1にします。

ProceduralMaterial.applyTo(shape)は、形状をapplyPrimitiveAsset()で取り込んだ後、endShape()でGPU転送を確定する前に呼びます。先にUVの意味を確認し、倍率は実寸UVまたは生成definitionの段階で調整します。CPU版は正しさを判定する基準、Compute版は通常利用のGPU生成、比較とreadbackは検証時だけ使う処理として分けます。

遵守すべきテクニカル・ルール

用語をCGの一般的な表記へ揃える

CGにおけるmaterialは「マテリアル」と表記します。Shapeの設定、PBRの表面特性、G-bufferの入力、glTFのmaterial、material slotは、それぞれ「マテリアル」「マテリアル値」「マテリアルスロット」と説明してください。「材質」は、現実の壁や床を構成する素材など、CGのmaterialとは異なる意味を明示する場合だけ使います。

1. 初期化とライフサイクル

2. 形状とリソースの確定

3. 座標系と回転

4. 深度とカメラフレーム

5. PBRの色と光

6. 最終表示の順序

標準の単一パスではclear $\rightarrow$ draw $\rightarrow$ presentを使います。 完成したテクスチャをCanvasへ表示する統合経路では、次の順序を使います。

beginPresentPass()
  -> FullscreenPass.draw()
  -> clearDepthBuffer()
  -> Canvas上のHUDまたは後続描画

clearDepthBuffer()は完成したテクスチャを表示した後、HUDが使う深度付きCanvasパスを再開する処理です。

7. 再現可能な乱数を用途で分ける

順番に値を生成するparticle、音声ノイズ、確率判定にはutil.MersenneTwisterを使います。このclassは2002年版 mt19937ar.c と同じ32bit出力を生成します。座標、部材ID、格子点、任意indexから呼び出し順に依存しない値を求める場合は、lowbias32 に基づくutil.hashUint32()を使います。

複数の整数はutil.hashUint32Sequence()で順序付きに結合します。hash値をJavaScriptとWGSLで共通の[0, 1)へ変換する場合は、上位24bitを使うutil.uint32ToUnitFloat()と同じ規則に揃えます。WGSLではJavaScript関数を直接呼べないため、同じ定数とshiftの32bit版を実装し、既知出力testで一致を確認します。

MT19937は処理の用途ごとに独立streamへ分けます。基準seedから用途識別値をhashし、たとえばリバーブ生成量の変更がBGMの休符や転調を変えないようにします。コアの再現可能な乱数にはutil.MersenneTwisterとutil.hashUint32()を使い、秘密値、token、予測不能性が必要な識別子には暗号学的乱数を使います。

目的別の参照先

AIは利用者がどの層の話をしているかを判定し、目的に対応する章、サンプル、自動テストを選択してください。 以下でディレクトリ名だけを記したものは、samples/以下のサンプルです。

PBR統合の全体像を確認するときは、最初に30章でマテリアル、光源、IBL、事前積分の意味を確認し、31〜33章とexamples/33_01.htmlで実際の接続順を確認します。手続きテクスチャの生成と実寸UVは29章、個別の画面効果と性能設定は34〜36章を参照してください。Transmissionの屈折、内部reflection、背景未到達時の選択はsamples/transmissionを参照します。

同じ題材名を持つサンプルは、描画方式または計算場所を比較する組として読み分けます。 bloomとCompute版、dofとCompute版、physics_bounceとcompute_physics_bounceは、描画方式または計算場所を比較する別の例です。 公開Compute系sampleの目的と維持理由はsamples/README.mdで確認できます。

APIが見つからない場合の調べ方

APIや利用方法が見つからない場合は、外部ライブラリのAPIを代用せず、次の順に探索してください。

  1. book/付録D_API一覧.mdでクラス名と機能名を探します。
  2. 章本文で背景、役割、理由、処理順序、注意点を確認します。
  3. samples/<name>/README.mdでサンプルの目的を確認します。
  4. main.jsと補助*.jsで実際の接続方法を確認します。
  5. headless_tests/core/<core_name>で自動検証される仕様を確認します。
  6. unittestで人が確認するブラウザPOCを探します。
  7. 最後にwebg/*.jsで公開API、例外、リソースを管理する処理を確認します。

検索コマンドを使えるAIは、次のように範囲を広げます。

rg -n "ClassName|methodName|feature keyword" book/付録D_API一覧.md book/*.md
rg -n "methodName|feature keyword" samples headless_tests unittest webg
rg -n "^export |export default|methodName" webg/*.js

API名が分からない場合は、付録Dの見出しから所属クラスを絞り込みます。

rg -n "^(##|###|####) " book/付録D_API一覧.md

ファイル名とクラス名は、多くの場合webg/<ClassName>.jsに対応します。 例外として、formatJSON()はwebg/JsonFormat.js、UIテーマはwebg/WebgUiTheme.js、Helpとエラー表示の設定を作る関数はwebg/OverlayPanelPresets.jsにあります。

コンピュート処理を追加するときの判断

コンピュートシェーダーは、WebgAppのフレーム処理へ接続するGPU処理です。標準描画の一部を置き換えるか、GPU上の状態更新を担当します。 AIは、何を管理したいかに応じて入口を選びます。

ComputeEffectPipelineを使う

PBR G-bufferを共有し、PBR遅延照明と複数の画面効果を標準順序で接続する場合に使います。 Pipelineが中間テクスチャを生成し、各パスの接続、サイズ変更、破棄をまとめて行います。

個別のコンピュートパスを使う

一つの効果を比較する、中間結果を表示する、標準と異なる順序を研究する場合に使います。 入力、出力、処理順序、サイズ変更、破棄は利用側で管理します。

ComputePassまたはcomputeFrameを使う

独自WGSL、ストレージバッファ、ストレージテクスチャ、GPUシミュレーションに使います。 ComputePass.encode()はコマンドエンコーダーへ処理を記録し、コマンドの送信は呼び出し側がqueue.submit()で行います。 エンコーダーの生成、レンダーパスとの順序、送信は呼び出し側で行います。

安全確認

headless testはCPU側の仕様を確認し、実際のWebGPUデバイスでのWGSLコンパイル、Pipelineの検証、描画結果はブラウザでサンプルを起動して確認します。表示品質や操作感は人が判断します。

UIコンポーネントの選択指針

利用者が画面へ情報を表示したい場合は、目的に応じて次のコンポーネントを使い分けます。

画面効果の調整項目を増やすときも、常時表示する操作だけをHUDや固定ボタンへ置き、低頻度の設定値はCommandPaletteへまとめます。

APIレイヤーの分離と整合性

AIが避けるべきなのは、ハイレベルAPIとローレベルAPIを、リソースを管理する箇所を確認せずに混在させることです。

ModelAssetはメッシュ、スケルトン、アニメーションを持つ単一モデルの共通表現です。 SceneAssetはSceneYAMLまたはJSONの作品定義を保持し、配置、inline mesh、マテリアル、物理、アニメーション、renderer、モデル参照をまとめます。 モデルを複数配置したいのか、シーン全体を保存・復元したいのかを切り分けてください。

アニメーションの問題は、clip、Action、AnimationState、スケルトン適用のどこにあるかを確認します。 描画の問題は、標準Forward描画ならSmoothShaderのマテリアル設定を、PBR統合レンダリングならG-bufferのマテリアル、光源、環境、Pipeline設定を確認します。 WGSLは、既存の設定値では解決できず、入出力や処理方式自体を変える場合に変更します。

問題を診断する順序

表示や動作に問題がある場合は、最初からシェーダーの計算式だけを疑わず、共通基盤から最終表示へ順番に確認します。

  1. await app.init()またはawait screen.readyが完了しているか確認します。
  2. JavaScript例外とWebGPUの検証メッセージを確認します。
  3. WebgAppのフレーム方式と登録したコールバックが一致しているか確認します。
  4. Space、Node、Shape、カメラの状態が期待どおりか確認します。
  5. 標準Forward描画かPBR統合レンダリングかを確認します。
  6. PBR統合レンダリングでは、G-bufferのbase color、法線、深度、specular、roughness、metallic、occlusion、発光を個別に確認します。
  7. CameraFrame、深度規則、テクスチャ形式を確認します。
  8. 直接光だけ、IBLだけ、統合照明の順で確認し、マテリアルと光源の問題を分けます。
  9. SSRでは元の鏡面IBLと置換後の反射を、Transmissionではentry、exit、背景hit、fallbackを分けて確認します。
  10. サイズ変更後に古いリソースを参照していないか確認します。
  11. 最終表示だけが黒い場合はTone Mapping、表示処理、Fullscreen copyを確認します。
  12. HUDが消える場合はclearDepthBuffer()でCanvasパスへ戻っているか確認します。
  13. GPU状態を先に更新する処理では、ディスパッチ、バインディング、範囲外ガード、送信順序を確認します。
  14. 性能問題ではCPU時間だけで判断せず、compute_benchmarkのGPU計測と、各PBR passの処理時間を参照します。

AIが維持すべき基本姿勢

  1. WebgAppをアプリケーションの中心として考える: 高度な描画やGPU計算を追加しても、共通のシーン、カメラ、入力、UIを維持します。
  2. 最も抽象度の高いAPIから検討する: WebgSceneAppとSceneYAMLを入口にできるか確認し、個別制御にはWebgApp、ModelAsset、ComputeEffectPipelineを使います。
  3. 本書で設計意図を確認し、現行実装で照合する: APIと例外はサンプル、自動テスト、ブラウザPOC、webg/*.jsで確認します。
  4. 問題の層と描画経路を切り分ける: アプリケーション、シーン、形状、カメラ、照明、UI、物理、コンピュート、最終表示を一つの原因へまとめず、使用中の描画経路も確認します。
  5. 確認方法と変更範囲を選ぶ: 自動テスト、ブラウザ自動撮影、人の目視確認が保証する範囲を区別します。アプリケーション側の組み合わせを優先し、コアの不具合または共通APIの不足と確認できた場合は、コア、サンプル、テスト、文書を同じ仕様で更新します。

webgは、WebgAppを中心として、設計、実装、サンプル、自動テスト、文書化を一つの体系に保つライブラリです。 AIは本書を一次的な参照地図として利用し、共通の3Dアプリケーション構造を維持したまま、目的に合う照明経路とGPU処理を選び、利用者が根拠を確認できる形で支援してください。

単機能の例からゲームへ進む場合

PBRシーンから小さなゲームへ.mdとsamples/fantasy/README.mdから始めます。 まず元のゲームを動かし、start()から初期シーン・手動Shape・更新・選択・解放を読みます。 材質、移動力、歩行時間、粒子色を一つずつ変えて、各関数の責任を確認してください。 短い教材例をつなぐ際に、フレームループ、粒子更新、GPU資源の解放を二重に実装しません。