# はじめに `webg` は、Chrome、Safari、Firefoxといったブラウザが標準で持っている JavaScript、WebGPU API、WebAudio API を利用して 3D アプリケーションを構築するためのライブラリです。PC やスマートフォンのブラウザ上で高速に動作する 3D アプリの作成を目的として設計されており、キー入力、タッチジェスチャー、マウス操作、ピンチ操作、効果音や BGM の再生、GLB アニメーションのインポート、パーティクル、被写界深度、フォグ、物理演算に加えて、G-buffer、SSAO、Shadow Map、SSR、Toon、Edge のような Compute Shader を使った画面効果まで、3D 表現に必要となる機能を網羅しています。 外部ライブラリや複雑なビルドツールを導入する必要はなく、実装に必要なコードと詳細な解説はすべて `webg` 自身に含まれています。そのため、学習目的での利用はもちろん、AI を活用した効率的なアプリ開発にも適しています。また、WebGPU による 3D 開発で不可欠な座標計算や GPU 制御といったローレベル（低レイヤー）なプログラミングから、多くの機能が抽象化された `WebgApp` クラスによる高水準（高レイヤー）なプログラミングまで、柔軟に使い分けることが可能です。 ![circular_breaker](fig01_01_circular_breaker.jpg) `webg` では、低レイヤーと高レイヤーの両方を扱うことができます。学習の初期段階で重要なのは、個別のメソッド名を暗記することではなく、「どのような用途に向いたライブラリなのか」「どの文書から読み進めれば理解が早いのか」「サンプルと unittest をどう使い分ければよいのか」といった、学習の指針をつかむことです。 本章では、`webg` の全体像、設計思想、プロジェクト内のファイル配置、そして学習のロードマップについて解説します。 ## `webg` が提供する価値と設計思想 WebGPU を用いた 3D 実装では、描画処理が完成した後、アプリケーションの規模が大きくなるにつれて、シーングラフ、アセット管理、カメラ制御、入力処理、診断情報、音声再生といった周辺機能が必要になります。特に AI と共同で実装を進める場合、「どの機能がどこに定義されているか」「現在の挙動を理解するために何を読めばよいか」が曖昧であると、調査や修正の効率が著しく低下します。 `webg` はこの問題を解決するため、3D アプリケーションを構成する各レイヤーをリポジトリ内で明確に分離し、サンプルコードと解説文書を対にして読める構造を採用しています。巨大なエンジンをブラックボックスとして利用するのではなく、プロジェクトに必要な部分を順に読み解き、組み上げていくスタイルを重視しています。 入力については、スマートフォン向けの操作を別系統として扱うのではなく、タッチ、マウス、ペンを Pointer Events として同じ処理フローへ集めます。これにより、スマートフォンで使う tap、double tap、long press、flick のような gesture を PC ブラウザ上でも同じ条件で確認でき、3D ビューアや編集ツールに対して、デバイスをまたいだ直接操作の UI を設計しやすくなります。 具体的に、`webg` は以下のような場面で真価を発揮します。 * WebGPU を使った 3D アプリケーションの内部構造を理解しながら構築したいとき * サンプル実装とドキュメントを往復しながら効率的に学びたいとき * 診断情報、HUD、タッチ入力、音声処理までを単一のリポジトリで完結させたいとき * スマートフォン向け gesture UI を PC ブラウザ上でも確認しながら調整したいとき * コーディング AI に 3D アプリ開発の支援をさせたいとき ## 本書の構成 `webg` の最大の特徴は、3D の基礎からアプリケーション構成までが一つのリポジトリで完結している点です。本書では、まず実行環境を整備し、3D の基礎と最小限の描画フローを押さえた後、`WebgApp`、アセット、アニメーション、UI、診断情報、ポストプロセス、ローレベルAPI、物理エンジン、そして Compute Shader を使った空間表現の構築と統合へと段階的に進む構成をとっています。 ### 導入と3Dの基礎（第1章 〜 第3章） まずは環境構築と、3D空間における共通概念を学びます。 - 環境構築： WebGPUが動作するブラウザの準備とローカルサーバーの起動（第2章）。 - 3D数学の基礎： 座標系（EUS）、UVマップ、行列（Matrix）とクォータニオン（Quat）の基本概念（第3章）。 ### webgのコア機能と基本実装（第4章 〜 第6章） `webg`の基本構造を理解し、簡単なシーンを表示させます。 - 低レベルAPI： `Screen`, `Space`, `Shape` を用いた描画ループの構築（第4章）。 - WebgApp（高レベルAPI）： アプリケーション全体を管理する`WebgApp`クラスの使い方と、HUD/UIの基本（第5章）。 - カメラ制御（EyeRig）： Orbit, First-person, Followといった多様なカメラ挙動の実装（第6章）。 ### シェーダーとアセットの活用（第7章 〜 第13章） 見た目の質を向上させ、外部モデルを導入します。 - マテリアルとシェーダー： `SmoothShader`によるPhong反射モデルとフォグ効果（第7章）。 - WGSL入門： WebGPUのシェーディング言語WGSLの基本とTBN行列（第8章）。 - カスタムシェーダー： NormPhongやBonePhongなど、独自のシェーダー実装（第9章）。 - モデル読み込み： glTF/GLB形式のモデルを`ModelAsset`として扱う方法（第10章）。 - シーン定義： JSON形式でシーンを記述する`Scene JSON`の活用（第11章）。 - アニメーション： Clip $\rightarrow$ Action $\rightarrow$ Stateへと至るアニメーション状態遷移の構築（第12〜13章）。 ### 応用機能と高度な実装（第14章 〜 第26章） インタラクティブな機能と高度な視覚効果を追加します。 - ユーザーインターフェース： HUD、OverlayPanel、タッチ操作の実装（第14〜16章）。 - 空間判定： レイキャスト（Raycast）と衝突判定（Picking）（第17章）。 - オーディオ： `ToneSynth`、`AudioSynth`、`GameAudioSynth` による単音、BGM、SEの制御（第18章）。 - デバッグと最適化： `DebugDock`とDiagnosticsによる実行時解析（第19章）。 - ポストプロセス： Bloom, DOF（被写界深度）, Vignetteなどの画面効果（第20章）。 - パーティクル： `ParticleEmitter`によるエフェクト実装（第21章）。 - 詳細APIと高度な形状： 形状生成API、手続き的形状（Icosphere等）の構築（第22〜24章）。 - スキニング： ボーンウェイトとスケルトンアニメーションの内部構造（第25章）。 - 物理演算： `PhysicsSpace`による剛体物理と衝突応答（第26章）。 ### Compute Shader と空間表現の統合（第27章 〜 第29章） 本書の集大成として、Compute Shaderを用いて高品質な空間表現を構築し、それらを一つのパイプラインへと統合します。 - **コンピュートシェーダーの基礎（第27章）**: `ComputePass` を基礎に、ストレージバッファやワークグループ、データ同期などの実行モデルを学びます。 - **個別パスの実装（第28章）**: `GeometryBufferPass`、`SsaoPass`、`ShadowMapPass`、`ComputeSsrPass` など、空間情報を扱う個別パスの構成と処理フローを理解します。 - **リアルタイム3D表現の統合（第29章）**: `ComputeEffectPipeline` を用い、SSAO、Shadow Map、SSR、Toon、DoF、Bloom、Edge を標準 `Space` と `Shape` に効率的に重ね合わせる、実用的かつ高水準な統合手法を学びます。 ## プロジェクトの構成 `webg` を読み解く際は、まずファイル配置と役割を把握してください。 * `webg/`（コアライブラリ）: `Screen`、`Space`、`Node`、`Shape`、`WebgApp` など、ライブラリの本体となる実装が含まれています。 * `samples/`（教材サンプル）: 機能確認とデモを兼ねたサンプル群です。各サンプルは `main.js`（実装）と `*.txt`（解説）で構成されており、`samples/index.html` がその目次となっています。 * `unittest/`（単体テスト）: 特定の機能を切り出して検証するためのテストアプリ集です。問題の切り分けや最小単位での動作確認に適しています。 * `book/examples/`（本書のコード例）: 本書で出てくるコードを実行可能な形にしたサンプルです。 ## `webg` で実現できること `webg` は、WebGPU 上で 3D アプリケーションを構築するための基盤を包括的に備えています。 * 描画基盤: `Screen`、`Shader`、`Shape`、`Space`、`Node`、`RenderTarget` * アプリ入口: `WebgApp` * アセット・ローダー: `ModelAsset`、`ModelLoader`、`ModelBuilder`、`SceneAsset`、`SceneLoader` * アニメーション: `Animation`、`Action`、`AnimationState`、`Skeleton` * カメラ・入力: `EyeRig`、`Touch`、`InputController` * UI・診断情報: `Message`、`OverlayPanel`、`Diagnostics`、`DebugDock`、`DebugProbe` * 音声: `ToneSynth`、`AudioSynth`、`GameAudioSynth` * ポストプロセス: `FullscreenPass`、`BloomPass`、`DofPass`、`VignettePass` など * Compute Shader 系効果: `GeometryBufferPass`、`SsaoPass`、`ShadowMapPass`、`SpotShadowMapPass`、`ComputeShadowPass`、`ComputeSpotShadowPass`、`ComputeSsrPass`、`ComputeToonPass`、`ComputeDofPass`、`ComputeBloomPass`、`ComputeEdgePass`、`ComputeEffectPipeline` * 物理: `PhysicsNode`、`PhysicsSpace`、`Collider` など ## コーディング AI に作ってもらう この本と `webg` のリポジトリは、コーディング用のAI（コーディングエージェント）も読者として意識して設計されています。人間にとっての読みやすさと、AIにとっての解析しやすさの両立を追求しています。 コーディングエージェントに `webg` をプロジェクトフォルダーとして読み込ませ、「`book/付録A_コーディングAIの皆さまへ.md` を読んで、my_webg (例) フォルダー以下に XXXX を作成して」と指示することで、効率的にアプリケーションを構築させることが可能です。 ## 問題調査の考え方 3D アプリケーションの開発では、単なるコンソール出力だけでなく、「なぜその結果になったか」を画面上で可視化して追跡することが重要です。`webg` では、HUD やパネルに情報を表示させ、必要に応じて診断情報レポートや probe を出力する手法を標準としています。後の章で解説する `Diagnostics` や `DebugDock` は、この「可視化によるデバッグ」という思想に基づいています。 ## まとめ 本章で最も重要な点は、`webg` を単なる API 集としてではなく、WebGPU の低レイヤーな描画から `WebgApp` による高レイヤーな構成、さらに Compute Shader を使った空間表現の統合までを体系的に学べるフレームワークとして捉えることです。 まずは第2章で環境を整え、第3章で基礎を学び、第4章で最初の描画に挑戦してください。本書が、WebGPU を用いた 3D アプリケーション開発の地図として役立つことを願っています。