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.
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.
04_02 → high_levelWebgApp; Chapters 4–6; place updates in onUpdategltf_loader → embedded_glb_viewerWebgApp.loadModel(); Chapter 8; the second example supports file selection, model replacement, and embeddingscene_model_yamlcreateWebgSceneApp(); Chapter 9, then Chapter 8 for external modelsbreakoutWebgApp with application-side game state; Chapters 5 and 12–16compute_particle_emitter → lumenWebgSceneApp; Chapters 9 and 26–30; repeated showcase motion is JavaScript-drivenmodel_yaml → edit_yamlModelAsset, SceneAsset, and WebgSceneApp; Chapters 8–9; Chapter 15 for selection and editingFor 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. Connect added features to the same application’s update, rendering, and resource-management flow.
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.
WebgApp04_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.
Read the Sphere and Plane JavaScript alongside its SceneYAML.
objects describe objects and initial placement, materials describe surfaces, physics sets simulation conditions, and renderer configures PBR.createWebgSceneApp() and handles camera, buttons, and status display.setPaused() for physics. This differs from the frame loop’s start() and stop().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.
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.
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.
Each entry connects a focused example to an application sample and gives a concrete checkpoint for understanding.
05_03 → embedded_glb_viewerModelAsset across placements
08_01 → model_yamlgltf_loader, collada_loader, json_loader10_01 → animation_state → jankenscene_animation12_01, 12_02, 13_01 → com_palette15_01 → collisions17_01compute_particle_emitter → compute_particles27_01 → physics_bounce, physics_colliderPhysicsSpace.step() uses milliseconds27_0227_03 → compute_physics, falling_box, joint29_01 → texture_catalogproctex → procedural_texture30_01, 30_02 → pbr_referenceopacity, transmission, or 34_01compute_benchmark38_01 → 38_02, 38_03 → 39_04, lowlevel_terrainWebgApp for the application framework40_01, 40_02 → skinning, bone_creatureRead 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
janken
circular_breaker, circular_breaker2
maze, maze2
lumen, neon_coaster, void_strike
project_app
edit_yaml, mmodeler, karakuri
compute_json
ModelAsset JSON and connect screen effects manuallycompute_cloth, compute_texture
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.
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. Check each webg API through 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.