開発の入口と実行例
更新日:2026年10月25日
初めてwebgを使う人と、開発を支援するAIのための案内です。作りたいアプリに近い既存例を一つ選び、動作を確認してから機能を追加します。最初は選んだ例と関連する章を読み、必要な機能に合わせて参照範囲を広げます。
book/examples/は章の説明を小さな実行コードで確認する場所です。samples/には、機能の比較、モデルの読込み、編集ツール、ゲーム、複数機能を組み合わせた作品があります。同じ機能の例でも、短い仕組みの説明と、アプリでの運用という役割を使い分けます。
統合版を使う場合は、02章の「統合版を読み込む」から始めてください。
04章には個別モジュール版と同じ例のimportの置き換えがあり、
付録C_統合版の利用.mdにはサンプル変換の手順があります。
lib/webg.core.min.jsを利用する場合も、本書のクラスとメソッドの説明を使えます。
1. 最初に一つ動かす
リポジトリのルートでHTTPサーバーを起動します。
python3 -m http.server 8000
http://localhost:8000/book/examples/04_02.htmlを開きます。立方体の表示と回転、ドラッグによる周回、ホイールによるズームを確認します。詳しい実行条件は02章、HTML全体と保存場所は04章です。
リンク先の実行ページも、このサーバーを経由して開きます。JavaScriptだけを別フォルダーへコピーすると、HTMLの要素、相対import、モデル、画像などが欠ける場合があります。まず元の配置で実行し、自作コードは例えばuser/my_app/へ置きます。この配置からコアのimportは../../webg/になります。
初回に読む共通範囲は、02章の実行環境、03章の座標、04章の最小描画です。その後は次の目的別の案内で入口を選びます。
2. 作りたいアプリから入口を選ぶ
形状を配置し、入力で動かすアプリ
出発点となる実行例:04_02 → high_level
主な入口と先に読む章:WebgApp。04〜06章。更新処理はonUpdateへ置く
GLBモデルを表示するビューア
出発点となる実行例:gltf_loader → embedded_glb_viewer
主な入口と先に読む章:WebgApp.loadModel()。08章。後者はファイル選択、モデル差し替え、埋込み表示を扱う
配置、PBR、物理を文書で定義する作品
出発点となる実行例:球と床 → scene_model_yaml
主な入口と先に読む章:SceneYAML+createWebgSceneApp()。09章。外部モデルを使う段階で08章
入力、得点、開始・停止・再開始を持つゲーム
出発点となる実行例:breakout
主な入口と先に読む章:WebgApp+アプリ側のゲーム状態管理。05・12〜16章
PBR、物理、粒子、音を組み合わせた展示
出発点となる実行例:球と床 → compute_particle_emitter → lumen
主な入口と先に読む章:WebgSceneApp。09・26〜30章。展示の反復動作はJavaScript
画面で配置やモデルを編集して保存するツール
出発点となる実行例:model_yaml → edit_yaml
主な入口と先に読む章:ModelAsset/SceneAssetとWebgSceneApp。08〜09章。選択・編集操作は15章
独自シェーダー、独自の描画・GPU計算
出発点となる実行例:19_01、20_01、21_01から必要なものを選ぶ
主な入口と先に読む章:WebgApp+個別API。18〜22章。描画基盤そのものを調べる場合は37章
PBRで高低差のあるマスを移動して戦うゲームには、
samples/fantasy/fantasy.htmlを出発点にします。
小さな統合例の読む順序は、下の「PBRのシーンから小さなゲームへ進む」と
PBRシーンから小さなゲームへ.mdにあります。
選択の基準は、作品の配置・材質・物理・描画設定をSceneYAMLとして管理するか、JavaScriptで直接組み立てるかです。単純な画面にはWebgApp、SceneYAMLからPBR作品を起動する場合にはWebgSceneAppを使います。機能の追加は、選んだ入口の更新・描画・リソース管理へ接続して進めます。
PBRの最初の作品は、SceneYAMLのrendererとmaterialsから始められます。描画の処理順や個別パスを自分で制御する必要が生じたら31〜33章へ進みます。
水面と集光をPBRに加える場合は、samples/water/index.htmlから
samples/water/water.htmlへ進みます。35章の「水面とコースティクス」と併せて、
WaterBodyの対象登録、共通の波、独立ON/OFF、GPU資源の解放を確認できます。
波の高さ・波長・速度、RGB吸収、透明面・粒子と画面効果の描画順も35章で扱います。
ゲームへの適用はsamples/fantasy/fantasy.htmlと、
samples/fantasy/main.jsのconnectWater()へ進みます。
水面表示をOFFにした集光・フォグの演出と、水面越しの反射・屈折を区別して選びます。
3. 出発点のコードを読む
WebgAppで直接組み立てる
04_02はHTML内のexample-sourceを読むだけで初期化、形状、Node、更新のつながりを追えます。high_levelのコードでは、起動と更新に加えて操作案内やスクリーンショットを確認できます。
最初の変更は、色、Nodeの位置、回転速度のうち一つにします。表示できた構成を保ったまま、カメラ、入力、UIを追加します。init()の完了を待ち、形状をendShape()で確定し、Nodeへ取り付けてからフレーム更新を始めます。
SceneYAMLから作品を起動する
球と床のJavaScriptとSceneYAMLを対にして読みます。
- YAMLの
objectsは物体と初期配置、materialsは材質、physicsは物理条件、rendererはPBRの設定です - JavaScriptは
createWebgSceneApp()、カメラ、ボタン、状態表示を担当します - この例のStart/Stopボタンは
setPaused()で物理を操作します。フレームループのstart()/stop()とは別の操作です - 起動時は物理が停止しています。Startで落下、Stopで停止、Resetで初期配置へ戻ることを確認します
初めは球の色か開始位置を一つ変更します。床の表示形状と衝突Planeを変更する場合は、両者の位置をそろえます。球を増やす場合にはphysics.space.maxBodiesも確認します。
onUpdateのdeltaSecはWebgAppと同じ秒単位です。高水準アプリの物理更新は内部のフレーム処理が担当し、利用側は作品固有の更新を接続します。
外部のモデル階層を使う段階でscene_model_yamlのコード、scene.yaml、model.yamlへ進みます。モデル内部の形状とNode階層はModelYAML、作品側の物理と描画設定はSceneYAMLです。この例は保存、停止状態へのリセット、エラー表示、終了時のdestroy()も含みます。
ゲームの進行を組み立てる
breakoutの説明で操作と状態を確認し、main.jsの状態遷移、registerActionMap()、onUpdate、HUD、再開始処理を読みます。title/play/pause/resultを持つ既存の完成ゲームです。3D描画とゲームルールを組み合わせる参考にできます。
GameStateManagerはsamples共通のアプリ側コードです。webgコアのAPIとは区別します。大きな例をそのまま複製する前に、自分の作品に必要な状態と操作を絞ります。
PBRのシーンから小さなゲームへ進む
高低差のあるマップで移動・攻撃するゲームには、samples/fantasy/を使います。
実行はsamples/fantasy/fantasy.html、操作と読む順序は
samples/fantasy/README.md、ブラウザの説明はsamples/fantasy/index.htmlです。
PBRシーンから小さなゲームへ.mdでは、直接Shapeへ渡す材質、
追加したNodeの更新、画面からの選択、リサイズ、粒子と資源の寿命を、
この例の関数へ対応させています。
main.jsのstart()から入り、scene.js、visuals.js、
move()とupdateMotion()、pickTile()、FantasyApp.jsの順に読みます。
最初は鎧の粗さだけを変え、次に一人の移動力、歩く表示時間、足元の粒子色を 一つずつ変えます。単機能の例で覚えたAPIが、ゲームのどの状態をいつ更新するかを 確認できます。移動と戦闘はマスの規則で決め、ルールと表示を分けた小さな統合例です。
4. 必要な機能だけ追加する
各項目は、短い例で機能を理解し、その後に操作や運用を持つ例へ進む順序です。「章と確認ポイント」に示した変更と動作を説明できれば、次の機能へ進めます。
親子構造・座標変換
小さく理解する例 → アプリでの利用例:03_01 → detouch
章と確認ポイント:03章。親の変換が子へ伝わること、親の付け替えでワールド配置を保つこと
周回・追従・主観カメラ
小さく理解する例 → アプリでの利用例:06_01、06_02 → eye_rig
章と確認ポイント:06章。カメラの位置追従と、対象へ視線を向ける追従を区別する
ページへの埋込み
小さく理解する例 → アプリでの利用例:05_03 → embedded_glb_viewer
章と確認ポイント:05章。ページのスクロールとCanvas内の入力、モデル差し替え後の表示
標準材質・テクスチャ・法線マップ
小さく理解する例 → アプリでの利用例:07_01、07_02 → shapes
章と確認ポイント:07章。色、テクスチャ、法線マップ、ワイヤーフレームを同じ形で比較する
ModelAssetの共有と複数配置
小さく理解する例 → アプリでの利用例:08_01 → model_yaml
章と確認ポイント:08章。一度構築し、個別Nodeへ複数配置する。元の文書と動作中の配置を区別する
モデル形式の読込み
小さく理解する例 → アプリでの利用例:gltf_loader、collada_loader、json_loader
章と確認ポイント:08章。使用形式の例だけ読む。モデルの原点、サイズ、clip、相対アセット参照を確認する
アニメーションの状態選択
小さく理解する例 → アプリでの利用例:10_01 → animation_state → janken
章と確認ポイント:10〜11章。Actionの再生と状態選択を分ける。複数配置の再生状態が独立していること
SceneYAMLの物体アニメーション
小さく理解する例 → アプリでの利用例:scene_animation
章と確認ポイント:09〜11章。Play、Pause、Seek、Resetとフレームループの停止を区別する
HUD・説明パネル・テーマ
小さく理解する例 → アプリでの利用例:12_01、12_02、13_01 → com_palette
章と確認ポイント:12〜13章。短い状態表示とDOMの操作・長文を分け、UIとアプリ状態を接続する
タッチ入力
小さく理解する例 → アプリでの利用例:14_01 → breakout
章と確認ポイント:14章。ジェスチャー検出と、同じアクションへのキー/タッチ接続
選択・衝突クエリ
小さく理解する例 → アプリでの利用例:15_01 → collisions
章と確認ポイント:15章。raycast、広域候補、詳細判定を区別する。クエリは物理の衝突応答とは別
効果音・BGM・音声ファイル
小さく理解する例 → アプリでの利用例:16_02、16_03、16_04、16_05 → sound
章と確認ポイント:16章。ユーザー操作後に音声を開始する。単音の設計は16_01とtone
診断・不具合の共有
小さく理解する例 → アプリでの利用例:17_01
章と確認ポイント:17章。環境、失敗した段階、アプリ状態を診断として残す
標準描画へBloom/DoFを追加
小さく理解する例 → アプリでの利用例:23_01 → bloom、dof
章と確認ポイント:23〜25章。元画像と効果後を比較し、深度を使う効果は焦点位置も確認する
軽量なCPU粒子
小さく理解する例 → アプリでの利用例:26_01 → billboard
章と確認ポイント:26章。発生条件と表示を確認する。GPU粒子とは更新方式が異なる
PBRへ標準Compute粒子を追加
小さく理解する例 → アプリでの利用例:compute_particle_emitter → compute_particles
章と確認ポイント:26・36章。連続/一括発生、停止、消去、容量を確認する。後者はCompute frameでの直接接続を調べる段階
CPU物理
小さく理解する例 → アプリでの利用例:27_01 → physics_bounce、physics_collider
章と確認ポイント:27〜28章。物理はCPU、描画はWebGPU。PhysicsSpace.step()はミリ秒
GPU物理を通常Nodeで描画
小さく理解する例 → アプリでの利用例:球と床 → 27_02
章と確認ポイント:09・27〜28章。高水準の接続を先に使い、readbackとNode同期を調べる場合に27_02へ進む
GPU物理の直接描画・方式比較
小さく理解する例 → アプリでの利用例:27_03 → compute_physics、falling_box、joint
章と確認ポイント:27〜28・42章。GPU状態の直接描画とCPUへの読戻しを区別する。Jointは方式別ページを選ぶ
手続き材質と実寸UV
小さく理解する例 → アプリでの利用例:29_01 → texture_catalog
章と確認ポイント:29章。形状の寸法と模様の周期を確認し、設定や画像を出力する
Height/Normal mapの生成
小さく理解する例 → アプリでの利用例:proctex → procedural_texture
章と確認ポイント:07・29章。HeightとNormalを区別する。実寸材質の入口は29_01
PBR材質と環境光
小さく理解する例 → アプリでの利用例:30_01、30_02 → pbr_reference
章と確認ポイント:30章。metallic/roughness、直接光、IBL、露出を分けて比較する
PBRの処理順を自分で接続
小さく理解する例 → アプリでの利用例:31_01 → 32_01 → 33_01
章と確認ポイント:31〜33章。同じ基準シーンで比較し、同一フレームのカメラ情報を各処理へ渡す
透明材質・屈折・AO
小さく理解する例 → アプリでの利用例:opacity、transmission、34_01から目的のものを選ぶ
章と確認ポイント:25・33〜35章。透明度、material slot、屈折、AO単体表示を分けて調べる
GPU性能の計測
小さく理解する例 → アプリでの利用例:compute_benchmark
章と確認ポイント:22・33章。GPU計測の対応状況と、測定する処理段階を確認する
独自メッシュ・地形
小さく理解する例 → アプリでの利用例:38_01 → 38_02、38_03 → 39_04、lowlevel_terrain
章と確認ポイント:38〜39章。頂点・UV・面・法線の対応。アプリ基盤はWebgAppを利用できる
スキニングの内部
小さく理解する例 → アプリでの利用例:40_01、40_02 → skinning、bone_creature
章と確認ポイント:40章。既存モデルの再生だけなら先に08・10〜11章を使う
5. 複数機能を組み合わせるときの参考
大きな例は、各機能の最小APIを探す段階の後で読みます。作品に近いものを一つ選び、シーン設定、作品固有の更新、入力、UIの分担を確認します。
水の表現には、設定とON/OFFを比較するsamples/water/index.htmlと、
既存ゲームへ追加するsamples/fantasy/index.htmlがあります。
前者で対象と波を理解してから、後者で移動、粒子、入力停止、再開始への接続を読みます。
breakout、cube4
組合せを読む目的:ゲーム状態、入力、得点、HUD、再開始。cube4は3D盤面とカメラ方向に対応した操作
janken
説明ページ:janken
組合せを読む目的:共有モデルから独立したアニメーションを持つ二つの配置を作り、入力と勝敗へ接続
circular_breaker、circular_breaker2
説明ページ:circular_breaker、circular_breaker2
組合せを読む目的:前者は直接構成するゲーム、後者はSceneYAML/ModelYAMLとPBRを利用する構成
maze、maze2
組合せを読む目的:主観移動、生成した壁と衝突、レーダー、照明・画面効果。壁の衝突処理は作品側の実装も読む
lumen、neon_coaster、void_strike
説明ページ:lumen、neon_coaster、void_strike
組合せを読む目的:高水準アプリの利用・拡張。展示の反復動作、追従カメラ、シューティングと粒子の接続
project_app
説明ページ:project_app
組合せを読む目的:球と床からJoint、objectSets、variants、制作シーンへ段階的に拡張
edit_yaml、mmodeler、karakuri
説明ページ:edit_yaml、mmodeler、karakuri
組合せを読む目的:編集状態、選択、Undo/Redo、保存と読込み、制作と実行の分担
compute_json
説明ページ:compute_json
組合せを読む目的:アニメーション付きModelAsset JSONの表示と手動接続する画面効果
compute_cloth、compute_texture
説明ページ:compute_cloth、compute_texture
組合せを読む目的:独自WGSLとbuffer/textureの更新。一般的な剛体や標準粒子の利用例とは分ける
6. 例を自分のアプリへ移すとき
- 選んだ例を元の場所で実行し、READMEの確認ポイントと表示・操作を対応させます
- HTMLが読むJavaScript、import先、YAML/JSON、画像、モデルを確認します。別サンプルのアセットや共通helperも参照先に含めます
- 入口を一つ決めます。高水準アプリへ、別の例のフレームループ、物理step、最終表示処理を重ねる前に、すでに自動実行されている処理を確認します
- 一つの機能・設定を変更し、期待する表示や操作を言葉にして確認します。動く状態を保ちながら次の機能を追加します
- 自分のHTMLと配信先に合わせて相対パスとDOMのIDを変更します。モデル差し替えではclip名、Node ID、原点、寸法も確認します
- 終了や差し替えで何を破棄するかを決めます。共有モデルは配置と共有資源を区別し、高水準アプリでは既存例の
destroy()の使い方を参照します
samples/固有のクラス・helperは、コアAPIとして推測して呼ばず、実際のimport先を読みます。標準機能と同じ見た目でも、compute_cloth、compute_texture、compute_physics_bounceなどには独自GPU処理があります。通常の物理を使う出発点には、球と床やphysics_bounceを選びます。
7. AIが開発を支援するとき
まず利用者の目的から、この文書の出発点を一つ選びます。選んだ入口、元にする実行ページとコード、追加する機能、表示・操作の確認ポイントを短く説明します。AIも人も、同じ例と同じ確認ポイントを使えます。
API名が分からなければAPI一覧で所属クラスを探し、対応する章と実行例を読みます。webgの実際のimport、呼出し、戻り値を読み、目的に対応するAPIを確認します。単位、既定値、自動更新の範囲を詳しく調べるときは、該当APIの現行実装とテストを照合します。
headless_tests/はAPI契約や計算の確認、unittest/は小さな機能のブラウザ確認に使います。静的にリンクやimportが存在すること、実行時に例外がないこと、意図した画面・操作になることは別々に確認します。確認記録には、実行した条件と観察した結果を対応付けます。
全体一覧はbook examplesとsamplesで確認できます。