Development Entry Points and Runnable Examples
This guide connects application goals to runnable pages, code, and book chapters. Use it with the browser guide, which provides the same entry points and checkpoints in a browsable form.
book/examples/ contains compact runnable code for understanding a chapter. samples/ contains comparisons, model loading, editing tools, games, and applications that combine multiple features. Use book examples to learn one feature, and samples to see how features work together in an application.
To use lib/webg.core.min.js, start with “Load the Bundled Library” in Chapter 2. Chapter 4 shows the import replacement for the same minimal example. Appendix C covers sample conversion. The class and method descriptions in this book apply to both loading methods.
1. Run One Example First
Serve the repository root over HTTP:
python3 -m http.server 8000
Open http://localhost:8000/book/examples/04_02.html. Check the cube, its rotation, orbiting by dragging, and zooming with the wheel. Chapter 2 explains serving requirements; Chapter 4 explains the full HTML and where it lives.
For shared prerequisites, read Chapter 2: Runtime, Chapter 3: Space Basics, and Chapter 4: Minimal Rendering. Then choose an entry point below.
For shared prerequisites, read Chapter 2: Runtime, Chapter 3: Space Basics, and Chapter 4: Minimal Rendering. Then choose an entry point below.
2. Choose an Entry Point for Your Application
- Place shapes and move them with input
- Runnable starting points:
04_02→high_level - Main entry point and first chapters:
WebgApp; Chapters 4–6; place updates inonUpdate
- Runnable starting points:
- Display a GLB model
- Runnable starting points:
gltf_loader→embedded_glb_viewer - Main entry point and first chapters:
WebgApp.loadModel(); Chapter 8; the second example supports file selection, model replacement, and embedding
- Runnable starting points:
- Define placement, PBR, and physics as documents
- Runnable starting points: Sphere and Plane →
scene_model_yaml - Main entry point and first chapters: SceneYAML and
createWebgSceneApp(); Chapter 9, then Chapter 8 for external models
- Runnable starting points: Sphere and Plane →
- Make a game with input, score, start, pause, and restart
- Runnable starting points:
breakout - Main entry point and first chapters:
WebgAppwith application-side game state; Chapters 5 and 12–16
- Runnable starting points:
- Combine PBR, physics, particles, and sound in a showcase
- Runnable starting points: Sphere and Plane →
compute_particle_emitter→lumen - Main entry point and first chapters:
WebgSceneApp; Chapters 9 and 26–30; repeated showcase motion is JavaScript-driven
- Runnable starting points: Sphere and Plane →
- Edit placement or models in a UI and save them
- Runnable starting points:
model_yaml→edit_yaml - Main entry point and first chapters:
ModelAsset,SceneAsset, andWebgSceneApp; Chapters 8–9; Chapter 15 for selection and editing
- Runnable starting points:
- Write custom shaders, rendering, or GPU computation
For a PBR game that moves and attacks on a map with elevation, begin at samples/fantasy/fantasy.html. The reading sequence is in From a PBR Scene to a Small Game and the sample guide.
Choose between defining scene placement, materials, physics, and rendering in SceneYAML or building them directly in JavaScript. Use WebgApp for a simple screen and WebgSceneApp to start a PBR application from SceneYAML. Use the same application entry point as you add features.
For PBR alone, start with SceneYAML renderer and materials. Read Chapters 31–33 when you need to control rendering order or individual passes with ComputeEffectPipeline.
To add water and caustics to PBR, use samples/water/index.en.html to reach samples/water/water.html, then read Chapter 35. It demonstrates WaterBody receiver registration, shared waves, independent surface and caustics toggles, and GPU-resource release. Chapter 35 also covers wave height, wavelength, speed, RGB absorption, and draw order for transparent surfaces, particles, and post-processing. To apply the feature to gameplay, open samples/fantasy/fantasy.html and connectWater() in samples/fantasy/main.js. Compare the caustics and surface toggles separately; the fantasy sample keeps the battlefield readable with underwater lighting and fog while its water surface is disabled.
3. Read the Starting Code
Build Directly with WebgApp
04_02 keeps initialization, shape creation, Node, and updates together in the page's example-source. The high_level source adds usage instructions and screenshots to startup and updates.
Begin by changing one value such as color, Node position, or rotation speed. Keep the working setup while adding cameras, input, and UI. Await init(), finish each shape with endShape(), attach it to a Node, and then start frame updates.
Start an Application from SceneYAML
Read the Sphere and Plane JavaScript alongside its SceneYAML.
- YAML
objectsdescribe objects and initial placement,materialsdescribe surfaces,physicssets simulation conditions, andrendererconfigures PBR. - JavaScript uses
createWebgSceneApp()and handles camera, buttons, and status display. - The example's Start/Stop buttons use
setPaused()for physics. This differs from the frame loop'sstart()andstop(). - Physics starts paused. Check that Start drops the sphere, Stop pauses it, and Reset restores its initial placement.
First change one value such as sphere color or starting position. If you change the displayed floor and collision plane, keep them aligned. Check physics.space.maxBodies when adding spheres. onUpdate receives deltaSec in seconds, as in WebgApp; high-level physics advances through its own step() as part of frame processing, while onUpdate handles application-specific updates.
For an external model hierarchy, continue to scene_model_yaml's code, scene.yaml, and model.yaml. ModelYAML describes internal shapes and Node hierarchy; SceneYAML describes application physics and rendering. The example also covers saving, resetting to a paused state, error reporting, and destroy() on shutdown.
Build Game Progression
Read the breakout guide for controls and states, then inspect main.js for state transitions, registerActionMap(), onUpdate, the HUD, and restart. It is a complete game with title, play, pause, and result states, and demonstrates combining 3D rendering with game rules.
GameStateManager is shared sample code for application-side game state. Inspect its imports and calls when adapting its state transitions to your application.
Go from a PBR Scene to a Small Game
Use samples/fantasy/ for a game that moves and attacks on a map with elevation. Run samples/fantasy/fantasy.html; find controls and reading order in samples/fantasy/README.en.md; use samples/fantasy/index.en.html for the browser overview.
From a PBR Scene to a Small Game maps direct Shape materials, updates to added Nodes, screen-space picking, resizing, and the lifetime of particles and resources to functions in the sample. Start at main.js's start(), then read scene.js, visuals.js, move() and updateMotion(), pickTile(), and FantasyApp.js.
First change only armor roughness, then one unit's movement allowance, step duration, and footstep particle color. This shows when each API updates application state. Movement and combat rules use grid coordinates, while visuals follow the same tile elevations.
4. Add Only the Features You Need
Each entry connects a focused example to an application sample and gives a concrete checkpoint for understanding.
- Parent-child transforms
- Orbit, follow, and first-person cameras
- Embed in a web page
- Small example → application example:
05_03→embedded_glb_viewer - Chapters and checkpoint: Ch. 5: page scrolling, Canvas input, and display after model replacement
- Small example → application example:
- Materials, textures, and normal maps
- Share a
ModelAssetacross placements- Small example → application example:
08_01→model_yaml - Chapters and checkpoint: Ch. 8: build once and place in separate Nodes; distinguish the source document from runtime instances
- Small example → application example:
- Load model formats
- Small example → application example:
gltf_loader,collada_loader,json_loader - Chapters and checkpoint: Ch. 8: read the needed format; check origin, scale, clips, and relative asset references
- Small example → application example:
- Select animation states
- Small example → application example:
10_01→animation_state→janken - Chapters and checkpoint: Chs. 10–11: separate Action playback from state selection; check independent playback per placement
- Small example → application example:
- Animate objects in SceneYAML
- Small example → application example:
scene_animation - Chapters and checkpoint: Chs. 9–11: distinguish Play, Pause, Seek, Reset, and stopping the frame loop
- Small example → application example:
- HUD, help panel, and theme
- Small example → application example:
12_01,12_02,13_01→com_palette - Chapters and checkpoint: Chs. 12–13: separate short status from DOM interaction and long text; connect UI to app state
- Small example → application example:
- Touch input
- Selection and collision queries
- Small example → application example:
15_01→collisions - Chapters and checkpoint: Ch. 15: distinguish raycast, broad-phase candidates, and detailed tests; queries are separate from collision response
- Small example → application example:
- Sound effects, BGM, and audio files
- Diagnostics and issue reports
- Small example → application example:
17_01 - Chapters and checkpoint: Ch. 17: preserve environment, failed stage, and application state in diagnostics
- Small example → application example:
- Add bloom and DoF to standard rendering
- Lightweight CPU particles
- Add standard Compute particles to PBR
- Small example → application example:
compute_particle_emitter→compute_particles - Chapters and checkpoint: Chs. 26 and 36: continuous/burst emission, stop, clear, and capacity; the second example connects directly in a Compute frame
- Small example → application example:
- CPU physics
- Small example → application example:
27_01→physics_bounce,physics_collider - Chapters and checkpoint: Chs. 27–28: physics runs on CPU and rendering on WebGPU;
PhysicsSpace.step()uses milliseconds
- Small example → application example:
- Render GPU physics with ordinary Nodes
- Small example → application example: Sphere and Plane →
27_02 - Chapters and checkpoint: Chs. 9 and 27–28: use the high-level path first; use 27_02 to inspect readback and Node synchronization
- Small example → application example: Sphere and Plane →
- Direct GPU physics rendering and comparison
- Small example → application example:
27_03→compute_physics,falling_box,joint - Chapters and checkpoint: Chs. 27–28 and 42: distinguish direct GPU state rendering from CPU readback; choose the Joint page by method
- Small example → application example:
- Procedural materials and real-world UV scale
- Small example → application example:
29_01→texture_catalog - Chapters and checkpoint: Ch. 29: compare object dimensions and pattern period, then export settings or images
- Small example → application example:
- Generate height and normal maps
- Small example → application example:
proctex→procedural_texture - Chapters and checkpoint: Chs. 7 and 29: distinguish height from normal; start real-world materials at 29_01
- Small example → application example:
- PBR materials and environment lighting
- Small example → application example:
30_01,30_02→pbr_reference - Chapters and checkpoint: Ch. 30: compare metallic/roughness, direct light, IBL, and exposure independently
- Small example → application example:
- Connect a PBR pipeline
- Transparency, refraction, and AO
- Small example → application example:
opacity,transmission, or34_01 - Chapters and checkpoint: Chs. 25 and 33–35: inspect opacity, material slots, refraction, and AO debug views separately
- Small example → application example:
- Measure GPU performance
- Small example → application example:
compute_benchmark - Chapters and checkpoint: Chs. 22 and 33: check timing support and which processing stage is measured
- Small example → application example:
- Custom meshes and terrain
- Small example → application example:
38_01→38_02,38_03→39_04,lowlevel_terrain - Chapters and checkpoint: Chs. 38–39: relate vertices, UVs, faces, and normals; use
WebgAppfor the application framework
- Small example → application example:
- Skinning internals
- Small example → application example:
40_01,40_02→skinning,bone_creature - Chapters and checkpoint: Ch. 40: for existing-model playback, start with Chapters 8 and 10–11
- Small example → application example:
5. Study Examples That Combine Features
Read a larger example after finding the minimal API for each feature. Choose one close to your application and inspect how scene configuration, application updates, input, and UI work together.
For water, use samples/water/index.en.html to compare settings and toggles, and samples/fantasy/index.en.html to see water added to an existing game. First understand receivers and waves in the water sample; then follow their connection to movement, particles, input locking, and restart in Fantasy.
breakout,cube4- What to study: Game states, input, score, HUD, restart; cube4 adds a 3D board and camera-relative controls
janken- What to study: Two placements share a model but have independent animation, connected to input and match results
circular_breaker,circular_breaker2- What to study: Directly assembled game versus SceneYAML/ModelYAML with PBR
maze,maze2- What to study: First-person movement, generated walls and collision, radar, lighting and screen effects; inspect game-side wall collision
lumen,neon_coaster,void_strike- What to study: High-level application use, repeated showcase motion, follow camera, shooting, and particles
project_app- What to study: Extend Sphere and Plane through joints, object sets, variants, and authoring scenes
edit_yaml,mmodeler,karakuri- What to study: Editing state, selection, undo/redo, save/load, and division between authoring and runtime
compute_json- What to study: Display an animated
ModelAssetJSON and connect screen effects manually
- What to study: Display an animated
compute_cloth,compute_texture- What to study: Update buffers and textures with custom WGSL; distinguish these from standard rigid-body physics and particles
6. Adapt an Example to Your Application
- Run the example in place and compare its controls and checkpoints with what appears on screen.
- Inspect the HTML, JavaScript imports, YAML/JSON, images, and model files it reads. Include shared helpers and assets from other samples in the dependency list.
- Choose one application entry point. Before adding another frame loop, physics step, or final display pass, identify the processing already performed by the high-level application.
- Change one feature or setting and describe the expected display or interaction. Add the next feature while keeping the working state.
- Adapt relative paths and DOM IDs for your HTML and hosting location. When replacing a model, check clip names, Node IDs, origin, and dimensions.
- Decide what to release on shutdown or replacement. Distinguish shared models from their instances, and follow the sample's
destroy()usage for high-level applications.
Read each sample's imports to identify which classes are application helpers and which are webg APIs. Samples such as compute_cloth, compute_texture, and compute_physics_bounce include custom GPU processing even when the result resembles a standard feature. For ordinary physics, start with Sphere and Plane or physics_bounce.
7. When an AI Agent Helps with Development
Start from the user's goal and choose one entry point in this guide. Briefly identify the runnable page and source to use, the feature to add, and how to check the result. People and AI agents can use the same examples and checkpoints.
Find a class in the API catalog, then read its chapter and runnable example. For each webg API, check its actual import, call, and return value, including when its name resembles an API from another 3D library. If a unit, default, or automatic update scope is unclear, inspect the current implementation and tests.
Use headless_tests/ for API contracts and calculations, and unittest/ for small browser checks. Static link/import presence, absence of runtime exceptions, and the intended visible result are separate checks. Report only the checks that were actually completed.
The overall indexes are book examples and samples.