webg

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

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. 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.

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.

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.

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.

6. Adapt an Example to Your Application

  1. Run the example in place and compare its controls and checkpoints with what appears on screen.
  2. 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.
  3. 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.
  4. Change one feature or setting and describe the expected display or interaction. Add the next feature while keeping the working state.
  5. Adapt relative paths and DOM IDs for your HTML and hosting location. When replacing a model, check clip names, Node IDs, origin, and dimensions.
  6. 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. 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.