開発の入口と実行例

更新日: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を対にして読みます。

初めは球の色か開始位置を一つ変更します。床の表示形状と衝突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

説明ページ:breakout、cube4

組合せを読む目的:ゲーム状態、入力、得点、HUD、再開始。cube4は3D盤面とカメラ方向に対応した操作

janken

説明ページ:janken

組合せを読む目的:共有モデルから独立したアニメーションを持つ二つの配置を作り、入力と勝敗へ接続

circular_breaker、circular_breaker2

説明ページ:circular_breaker、circular_breaker2

組合せを読む目的:前者は直接構成するゲーム、後者はSceneYAML/ModelYAMLとPBRを利用する構成

maze、maze2

説明ページ: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. 例を自分のアプリへ移すとき

  1. 選んだ例を元の場所で実行し、READMEの確認ポイントと表示・操作を対応させます
  2. HTMLが読むJavaScript、import先、YAML/JSON、画像、モデルを確認します。別サンプルのアセットや共通helperも参照先に含めます
  3. 入口を一つ決めます。高水準アプリへ、別の例のフレームループ、物理step、最終表示処理を重ねる前に、すでに自動実行されている処理を確認します
  4. 一つの機能・設定を変更し、期待する表示や操作を言葉にして確認します。動く状態を保ちながら次の機能を追加します
  5. 自分のHTMLと配信先に合わせて相対パスとDOMのIDを変更します。モデル差し替えではclip名、Node ID、原点、寸法も確認します
  6. 終了や差し替えで何を破棄するかを決めます。共有モデルは配置と共有資源を区別し、高水準アプリでは既存例の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で確認できます。