When developing an application for the first time, choose one starting point that fits the goal in Development Entry Points and Runnable Examples. Use the same runnable pages, code, and checkpoints as a human reader. This appendix maps the references to use when investigating APIs and internal connections.
First determine whether the application uses individual webg/ modules or
lib/webg.core.min.js. The bundle provides named imports such as WebgApp and
Shape; consult the book and original source for their API behavior.
When adapting a sample, use the same loading method in shared helpers,
re-exports, and dynamic imports. Appendix C gives the
conversion commands and checks.
webg UsersThis appendix helps AI coding assistants support developers building 3D applications with webg. Use the library’s own design to decide what to read and in what order; do not directly transfer assumptions from another 3D engine or external library.
WebgApp coordinates initialization, the update loop, camera, input, UI, and drawing. Space, Node, Shape, and ModelAsset make up the 3D scene. These are shared by standard forward rendering and integrated physically based rendering (PBR).
webg 3.0 provides metallic-roughness PBR, image-based lighting (IBL), PBR G-buffers, transparent PBR, screen-space transmission, and general procedural textures. PBR connects material values, direct lights, high-dynamic-range (HDR) environments, pre-integrated IBL, camera state, shadows, screen-space effects, and tone mapping in a linear HDR pipeline.
The main rendering choice is how lighting and screen effects reach the final image, rather than how the geometry is constructed. Use standard forward rendering with SmoothShader for a small scene drawn directly. Use ComputeEffectPipeline when integrating a PBR G-buffer, IBL, multiple lights, SSAO, SSR, transparency and refraction, fog, bloom, and other effects into one HDR image. Both paths run within WebgApp and use the same Space, Node, Shape, camera, input, and UI.
WebgApp
├─ initialization, update loop, camera, input, UI
├─ Space, Node, Shape, ModelAsset
└─ choose lighting and final rendering path
├─ standard forward rendering
│ └─ draw Shapes directly with SmoothShader
└─ integrated PBR rendering
└─ PBR G-buffer + ComputeEffectPipeline
├─ direct light + IBL + shadows + SSAO
├─ SSR + transparent PBR + transmission
└─ fog + bloom + tone mapping, and more
The top of the diagram is the application foundation. The lower branch chooses how the same scene and geometry are converted to the final image. Integrated PBR keeps the existing WebgApp, Space, and Shape foundation and connects ComputeEffectPipeline afterward. For a simple view, standard forward rendering keeps the setup compact even on a device that supports PBR and compute shaders.
webg is self-contained: rendering, scene management, models, animation, UI, input, physics, audio, diagnostics, and GPU computing live in the library. Prefer the book, samples, headless_tests, unittest, and current webg implementation over guesses such as “a typical WebGPU implementation probably…” or “Three.js works this way, so webg probably does too.”
General concepts can help explain an idea, but use webg documentation and implementation as the authority for public APIs, parameters, formats, lifecycle, and exception conditions. This appendix is a reading map for choosing chapters, samples, automated tests, browser proofs of concept, and core implementation according to the user’s goal and the layer containing the issue. For PBR, determine how far the data is correct—from the G-buffer and lighting through IBL and transparency to final display—instead of guessing material values from the finished image alone.
For an application whose placement, PBR, and Compute physics are defined together, start with createWebgSceneApp({ project: "./scene.yaml" }) from webg/app/index.js. WebgSceneApp builds on WebgApp and connects SceneDefinition validation, PbrRenderer, ScenePhysics, animation, and Node synchronization. Use WebgApp directly when constructing a custom rendering path.
SceneYAML describes a complete application: placement, inline meshes, materials, physics, and renderer settings. ModelYAML describes a reusable model: meshes, Node hierarchy, skeleton, and animation. They load as SceneAsset and ModelAsset, which inherit from DocumentAsset and share parsing, source-document, and comment preservation in SceneYaml.js.
Use getSourceDocument() to handle original YAML when editing or saving. If values have not changed, toYAMLText() returns the source. If values are changed while comments remain attached to the source, saving throws so that comments cannot silently become misaligned. Pass updated YAML source to fromYAML(). For conversion to JSON, set allowCommentLoss: true to make the comment-loss decision explicit.
For a physics-enabled inline mesh, define display geometry in mesh and its Box, Sphere, or Capsule collider in physics.shape. See Chapters 8–9 and samples/model_yaml, samples/scene_model_yaml, and samples/edit_yaml.
PBR discussions often focus on material models for metals, plastic, ceramic, stone, and glass. The same material can look very different when light direction, distance, shape, size, environment highlights, or exposure changes. When gold appears gray, check metallic, roughness, Fresnel reflection, direct light, specular IBL, SSR, and tone mapping as well as base color.
webg uses the metallic-roughness workflow. A dielectric’s base color primarily drives diffuse reflection; a metal’s base color primarily supplies the color of specular F0. specular sets dielectric reflectance, roughness describes the distribution of microfacet normals, metallic blends dielectric and metal behavior, and occlusion describes environment visibility. Emission is a separate linear HDR color.
An environment map is both a background and input light from every direction. PbrEnvironment exposes the source radiance, diffuse irradiance, roughness-prefiltered specular environment, and BRDF LUT as GPU resources shared by deferred lighting, PBR SSR, and transparent PBR. With environmentBackground: false, IBL remains enabled while clearColor supplies the display background. Set fixed ambient to zero when environment light is active.
PBR calculations use linear HDR and apply tone mapping and sRGB conversion once immediately before display. Keep display sRGB values such as base color and clear color distinct from the linear HDR values after lighting. Place bloom, fog, SSR, and transmission before tone mapping; place edge and vignette effects after display conversion.
Use one light-unit system: unitSystem: "relative" for visual tuning within a scene, or unitSystem: "photometric" for photometric light output and EV100 exposure. When the image looks dark, inspect direct light, IBL, and exposure in that order.
GltfShape maps glTF 2.0 core inputs such as baseColorFactor, metallicFactor, roughnessFactor, Normal, Occlusion, Emissive textures, emissiveFactor, and alphaMode. Connecting KHR_materials_transmission, KHR_materials_ior, or KHR_materials_volume to screen-space transmission requires a separate mapping into webg’s transparent and refraction settings. Distinguish glTF core support from webg-specific features.
WebgApp at the CenterWebgApp brings Canvas initialization, Screen, GPU context, scene, standard shaders, camera, input, Message, HUD, Overlay Panel, DebugDock, and frame processing into one application structure.
Both standard forward rendering and integrated PBR use the same foundation:
await app.init().Space and Node.Shape, Primitive, and ModelAsset.EyeRig or the standard camera.onUpdate.InputController.Switching rendering paths does not change the established workflow for model loading, Node movement, animation, camera control, or UI. When proposing a different lighting path, retain the shared application foundation and change the rendering path alone.
Space manages the Node hierarchy. Shape holds vertices, normals, UVs, material slots, and per-triangle material indices. A model expanded from ModelAsset also enters the scene as Nodes and Shapes.
Standard forward rendering draws those Shapes with SmoothShader. Integrated PBR renders the same Space and Shapes to a PBR G-buffer with GeometryBufferPass, then evaluates lighting in later passes. The shader and output target change, while the model remains a Node and Shape in the same scene.
For integrated PBR, provide the surface material information expected by the G-buffer: base color, specular, roughness, metallic, occlusion, and emission. Missing values should surface as property-specific exceptions. Choose one emission input path: emissive_factor with optional emissive_texture, or the legacy scalar emissive.
In standard forward rendering, SmoothShader evaluates lighting while drawing a shape and outputs directly to the Canvas. Its advantage is a short path and a compact setup.
Consider this path when:
SmoothShader material controls can produce the intended appearanceWebgApp manages camera state and the command encoder in the standard path. ComputeEffectPipeline connects the stages in integrated PBR. Keep simple Space.draw(eye) rendering on the standard forward path and group PBR G-buffers and frame state in the integrated pipeline path.
Integrated PBR first stores opaque Shape surface data in a PBR G-buffer, then uses its textures for direct light, IBL, and screen effects. ComputeEffectPipeline connects G-buffer generation, shadows, SSAO, PBR deferred lighting, SSR, transparent PBR and transmission, fog, toon, DoF, bloom, tone mapping, edge, and vignette.
Material alpha_mode determines whether a surface is OPAQUE, MASK, or BLEND. If it is omitted, alpha < 1.0 implies BLEND. The renderer treats color[3] as a texture-mixing value and uses alpha for transparency. Even when opaque and transparent triangles share one Shape, transparent triangles are gathered across Shapes and sorted back to front. Do not add a separate transparent render pass in application code. Let the internal TransparencyPass handle background blur controlled by roughness, GGX reflection on transparent surfaces, and transmission refraction and absorption.
Consider integrated PBR when:
Integrated PBR also runs inside WebgApp. Call pipeline.renderScene() in onBeforeDraw and pipeline.encode() and final presentation in onAfterDraw3d. Pass the same cameraFrame to both:
WebgApp state update
-> onBeforeDraw: render shadow map and G-buffer
-> onAfterDraw3d: record lighting and screen effects
present final texture to Canvas
return to depth-enabled HUD drawing
ComputeEffectPipeline is the integrated PBR entry point. Choose explicitly at the application entry point between standard forward and integrated PBR.
The order keeps the meaning of each input consistent:
Shadow Map
-> PBR G-buffer
-> deferred lighting (direct light + IBL, linear HDR)
-> SSR replaces visible specular IBL
-> transparent PBR + transmission
-> fog -> toon -> DoF -> bloom
-> tone mapping + sRGB conversion
-> edge -> vignette
-> Canvas presentation -> HUD
In composer.mode: "pbr-ssr", SSR replaces only the specular IBL where an on-screen intersection is found; original IBL remains where there is no hit. Transparent surfaces draw forward after the opaque G-buffer. PbrForwardShader shares PbrBrdf.js with opaque PBR and evaluates direct lights, shadows, and IBL with the same GGX model.
Transmission refracts from air into the medium at the entry, searches for the exit surface, refracts back into air, and samples the background. Apply Beer-Lambert absorption along the internal path. Choose transmissionRayMissFallback as "auto", "environment", "clear", or "constant" for rays without a background hit. These modes define a visible fallback for data outside screen space.
"environment" requires environment radiance and reports a configuration error when it is missing. "constant" requires the display-sRGB transmissionRayMissColor. If no internal boundary is visible and an outward direction cannot be determined, use the clear color for modes other than "constant" rather than inferring an environment direction.
GPU particles, cloth, physics, and procedural textures update GPU state before rendering. This is a separate concern from selecting a lighting path. Use WebgApp with computeFrame: true and onComputeFrame:
WebgApp computeFrame
-> compute passes update state
-> render passes read the latest state
-> submit command buffer
This path updates large amounts of state on the GPU and renders it without copying each result to the CPU. Choose the lighting path and GPU-simulation path independently.
webg connects rendering, scenes, models, animation, UI, input, diagnostics, and GPU computing with a consistent set of rules. The camera hierarchy is cameraRig → cameraRod → eye; scene geometry is Space → Node → Shape. ModelAsset → build() → instantiate() separates shared resources from instances, while clip → pattern → action → state separates animation stages.
First learn webg’s own terms and the work assigned to each feature, then relate them to general 3D and WebGPU concepts. Applying general assumptions first can confuse the locations where depth rules, color spaces, camera state, and GPU resources are managed.
ProceduralTileSpec defines tile dimensions, pattern, grout, and surface appearance. ComputeProceduralTile generates Color, Height, and Normal on the GPU. ProceduralMaterials selects presets, retains generated data, configures PBR materials, applies them to Shapes, and disposes of resources.
ProceduralTileSpec
-> ComputeProceduralTile
-> Color texture
-> Height texture
-> Normal texture
-> ProceduralMaterial
-> real-scale UV mapping and PBR material on a Shape
For real-scale tiles, stone, wood, or vinyl on a cuboid, use Primitive.mapRealCuboid() to create meter-based UVs on each face. Primitive.mapCube() is for image atlases. The scale in createPreset() scales the displayed texture period: scale: 10 makes the pattern period ten times larger and reduces repetitions across a face to one tenth.
Call ProceduralMaterial.applyTo(shape) after applyPrimitiveAsset() and before endShape() uploads GPU data. Determine the meaning of the UVs first, then tune scale in real-scale mapping or the generated definition. Use CPU generation as a correctness reference, Compute generation for ordinary GPU use, and comparison/readback as verification operations.
Use “material” for the computer-graphics concept: Shape configuration, PBR surface properties, G-buffer inputs, glTF material, and material slot. Use “substance” or “physical material” only for real-world wall or floor composition when distinguishing it from a graphics material.
await screen.ready or await app.init() completes.app.space, app.eye, and app.getGPU() after app.init() completes.app.start({ onUpdate: ... }).onComputeFrame together with computeFrame: true.shape.endShape() after adding vertex data.Primitive.cube(), Primitive.mapCube(), and Primitive.mapRealCuboid() assign UVs with different meanings; choose the function for the intended mapping.Primitive.mapRealCuboid() to assign meter-based UVs to every face.ProceduralMaterial.applyTo(shape) after applyPrimitiveAsset() and before endShape().ProceduralMaterials.createPreset().scale sets the displayed size of one texture period.ModelAsset.build() to create runtime resources, then call instantiate() for as many placements as needed.+X = right, +Y = up.+Z from a standard camera’s local forward -Z.CoordinateSystem for yaw, pitch, and roll.CAMERA_REVERSE_Z, depth32float, clear 0, compare greater.SHADOW_STANDARD_Z, clear 1, compare less.CameraFrame freezes camera state for one render. Standard single-pass rendering uses WebgApp camera state; G-buffer and depth-dependent later passes share CameraFrame or renderFrameToken.CameraFrame to ComputeEffectPipeline.renderScene() and encode().renderScene() and encode().alpha_mode for transparency classification; when omitted, classify from alpha and triangle material-slot indices.TransparencyPass composites transparent surfaces into HDR after SSR and before fog, toon, DoF, and bloom.WebgApp or the shared CameraFrame.transmissionRayMissColor use display sRGB or linear lighting values.rgba16float range.metallic, IBL, direct light, and exposure as well as base color.lighting.environment, set ambient: 0.0 so there is one environment-light input.environmentRotationDegrees consistently to radiance, irradiance, and prefiltered specular.environmentBackground: false keeps environment illumination while displaying clearColor as the background.composer.mode: "pbr-ssr", replace specular IBL where SSR finds a hit; do not add another copy of the same reflection.For standard single-pass drawing, use clear → draw → present. For an integrated path that presents a completed texture to Canvas:
beginPresentPass()
-> FullscreenPass.draw()
-> clearDepthBuffer()
-> draw HUD or subsequent Canvas content
clearDepthBuffer() returns to the depth-enabled Canvas pass used by the HUD after presenting the completed image.
Use util.MersenneTwister for sequential particle values, audio noise, and probability decisions. It produces the same 32-bit output as mt19937ar.c from 2002. Use util.hashUint32(), based on lowbias32, for values derived from coordinates, part IDs, grid points, or arbitrary indices independently of call order.
Combine ordered integer values with util.hashUint32Sequence(). To map a hash to [0, 1) consistently in JavaScript and WGSL, use the same rule as util.uint32ToUnitFloat(), which takes the upper 24 bits. Since WGSL cannot call the JavaScript function, implement the same constants and 32-bit shifts in WGSL and verify known outputs.
Give separate uses independent MT19937 streams by hashing a use identifier from a base seed. For example, changing reverb generation should not change rests or modulations in the BGM. Use reproducible library randomness for simulations; use cryptographic randomness for secrets, tokens, or unpredictable identifiers.
Select the chapter, sample, and automated check that match the layer being investigated. Directory-only sample names below are under samples/.
low_level, high_levelhigh_levelhigh_level, eye_rigshapes, materialsSmoothShader, shapes, materialsbook/examples/33_01.html, pbr_reference, transmission, procedural_texture, texture_catalog, compute_jsongltf_loader, collada_loaderproject_app, scene_model_yaml, model_yaml, edit_yamlanimation_state, jankenOverlayPanel and CommandPaletteunittest/raycast, headless_tests/core/physics_spacephysics_bounce, headless_tests/core/physics_spacesamples/compute_physics, book/examples/27_02.html, book/examples/27_03.htmlcompute_particles, compute_cloth, compute_physics_bounce, compute_texturebook/examples/20_01.html, webg/ComputePass.jscompute_benchmarkTo understand integrated PBR, start with Chapter 30 for the meaning of materials, lights, IBL, and pre-integration, then use Chapters 31–33 and book/examples/33_01.html for the connection order. Chapter 29 covers procedural texture generation and real-world UV scale; Chapters 34–36 cover individual screen effects and performance. For transmission refraction, internal reflection, and ray-miss choices, see samples/transmission.
Samples with similar names can compare rendering paths or compute locations. bloom versus its Compute version, dof versus its Compute version, and physics_bounce versus compute_physics_bounce are separate examples for those comparisons. samples/README.en.md describes the purpose and maintenance rationale for public Compute samples.
When an API or usage pattern is unclear, search in this order rather than substituting an API from another library:
samples/<name>/README.md for the sample’s purpose.main.js and helper JavaScript for actual connections.headless_tests/core/<core_name> for automatically tested behavior.unittest.webg/*.js for the public API, errors, and resource management.Useful searches include:
rg -n "ClassName|methodName|feature keyword" book.en book/*.md
rg -n "methodName|feature keyword" samples headless_tests unittest webg
rg -n "^export |export default|methodName" webg/*.js
To search API catalog headings, use rg -n "^(##|###|####) " book.en/Appendix_D_API.md. Class and file names often correspond as webg/<ClassName>.js. Exceptions include formatJSON() in webg/JsonFormat.js, UI themes in webg/WebgUiTheme.js, and Help/error option builders in webg/OverlayPanelPresets.js.
Compute shaders connect GPU work to the WebgApp frame. They can replace part of standard rendering or update GPU state. Choose the entry point according to the data and passes that the application needs to own.
ComputeEffectPipelineUse it when PBR G-buffer data feeds PBR deferred lighting and several screen effects in the standard order. The Pipeline creates intermediate textures and coordinates pass connections, resizing, and disposal.
Use them to compare one effect, display intermediate output, or investigate a different order. The caller manages inputs, outputs, ordering, resizing, and disposal.
ComputePass or computeFrameUse these for custom WGSL, storage buffers, storage textures, and GPU simulation. ComputePass.encode() records work in a command encoder; the caller submits it with queue.submit(). The caller also creates the encoder and orders compute and rendering passes.
@workgroup_size and JavaScript workgroupSize consistent.rgba16float and apply display conversion once at the end.destroy().Headless tests verify CPU-side behavior. Launch the example in a browser to verify WGSL compilation, Pipeline validation, and actual WebGPU output. People should assess image quality and interaction feel.
app.showOverlayPanel(buildHelpPanelOptions(...))app.message.setLines("status", [...], options) or HUDOverlayPanel buttons/choices and application-side controlbuildErrorPanelOptions() or an Overlay Panel with format: "pre"CommandPaletteDebugDockKeep frequent controls in a HUD or fixed buttons and collect infrequent effect settings in CommandPalette.
Choose one owner for resource creation, resizing, updates, and disposal. For an application driven by a scene definition, consider WebgSceneApp. For direct rendering control, consider WebgApp, SmoothShader, and ComputeEffectPipeline. Keep the frame processing of an existing WebgApp, and maintain the resource ownership convention when using raw WebGPU or individual passes. Report incomplete input through an exception that names the property and expected format.
ModelAsset is the shared representation of one model’s meshes, skeleton, and animations. SceneAsset holds a SceneYAML or JSON application definition: placement, inline meshes, materials, physics, animation, renderer, and model references. Determine whether the task needs multiple placements of a model or save/restore of a full scene.
For animation issues, find whether the cause is in the clip, Action, AnimationState, or skeleton application. For rendering, inspect SmoothShader material settings in standard forward rendering; inspect G-buffer material, lights, environment, and Pipeline settings in integrated PBR. Change WGSL when existing configuration cannot express the required inputs or processing behavior.
Trace from the shared foundation toward final display:
await app.init() or await screen.ready completed.WebgApp frame mode matches registered callbacks.Space, Node, Shape, and camera state.specular, roughness, metallic, occlusion, and emission in the G-buffer.CameraFrame, depth convention, and texture formats.clearDepthBuffer() returns to the Canvas pass.compute_benchmark and timings by PBR pass rather than relying on CPU time alone.WebgApp at the center and preserve the shared scene, camera, input, and UI when adding advanced rendering or GPU work.WebgSceneApp and SceneYAML first, then use WebgApp, ModelAsset, or ComputeEffectPipeline when control requires it.webg keeps design, implementation, samples, automated checks, and documentation in one system centered on WebgApp. Use this book as the primary map, select the rendering and GPU paths that fit the goal, and make evidence available to the developer.
Start with From a PBR Scene to a Small Game and samples/fantasy/README.md. Run the existing game, then follow start() through scene setup, manually created Shapes, updates, selection, and disposal. Change material, movement allowance, walking time, and particle color one at a time to understand each function’s responsibility. When connecting focused examples, keep the frame loop, particle update, and GPU-resource release under one owner.