Rendering overview

meep renders through Shade, its own renderer. There is no WebGL path and no second backend. Shade is GPU-driven and visibility-buffer deferred, which changes what a game’s code is responsible for: you describe content, and the renderer decides what is drawn, in what order, and whether it is culled. This page is the map of that; the linked pages cover each piece in depth.

What Shade is

A GPU-driven, visibility-buffer deferred renderer on WebGPU. Geometry is clustered into meshlets ahead of time and lives GPU-resident in one large buffer. Culling runs on the GPU. The rasterizer writes a visibility buffer and a G-buffer rather than shading as it draws. Lights are binned into froxels and applied deferred. The result is temporally resolved (TAA, or the bundled NSS neural upscaler), tonemapped and presented.

Three consequences shape everything else:

• A mesh is a small GPU-resident record, not a draw call you own. You add a Mesh to a Scene, or a ShadedGeometry component to an entity, and that is the whole of your involvement in submission. There is no render layer to assign, no visibility list to maintain, no CPU frustum cull to configure, and no draw order to influence.
• Preparing geometry is a precompute. meshlet_geometry_build_from_geometry runs once per shape, when content is created or loaded - never per frame. Content whose vertices are rewritten every frame (trails, paths, debug lines, CPU particles) goes down a separate dynamic-mesh path instead.
• The frame is a closed sequence with declared injection points. You do not insert a pass wherever you like; you register a RenderExtension against one of six FramePhases. See Render extensions.

WebGPU, and the device floor

Shade requires a WebGPU device that meets a fixed floor. There is no feature detection past it, no fallback, and no branch that produces a lesser frame - hardware below the floor is told clearly that it cannot run this.

The adapter is requested with powerPreference: "high-performance". A fallback (software) adapter logs a warning and proceeds.

In practice there is one more requirement the floor cannot express: the engine’s shaders use the WGSL immediate_address_space extension, which shipped in Chrome 149/150. An older Chromium acquires a device that passes every check above and then fails to dispatch shaders.

How startup fails

Renderer.initialize() rejects, and not everything it rejects with is a ShadeDeviceFailure:

ShadeDeviceFailure (src/shade/device/ShadeDeviceFailure.js, named export) extends Error. Its message is written to be shown to a person rather than logged; detail holds the specific missing feature or limit for the log; reason is a ShadeDeviceFailureReason:

Two of those five reasons are enum members nothing constructs in 3.21.0. The no-WebGPU check is the first line of initialize() and predates the failure type, so it throws the plain Error above rather than a WebGPUUnavailable failure; and requestDevice is called without a try, so a refused device surfaces the browser’s own error rather than DeviceRequestFailed. Handle the plain-Error case too - a catch that only tests isShadeDeviceFailure misses the most common failure of all, an old browser.

Through the engine, this arrives as a signal. GraphicsEngine.start() raises on.contextFailed with the failure and then rethrows, so a caller that wants to handle it can and one that does not still fails loudly:

import { ShadeDeviceFailureReason } from "@woosh/meep-engine/src/shade/device/ShadeDeviceFailureReason.js";

engine.graphics.on.contextFailed.add(failure => {
    if (failure.isShadeDeviceFailure !== true) {
        // the no-WebGPU and no-canvas-context paths, which carry no `reason`
        suggestBrowserUpgrade(failure.message);
        return;
    }

    // failure.message is written for a player; failure.detail is for the log
    showBlockingMessage(failure.message);

    if (failure.reason === ShadeDeviceFailureReason.BelowFloor) {
        reportUnsupportedHardware(failure.detail);
    }
});

Engine subscribes to contextFailed itself: it pauses the simulation and adds GraphicsContextFailureView (src/view/graphics/GraphicsContextFailureView.js, named export) to the view stack, so an unhandled failure still puts the message on screen instead of burning cycles invisibly. Application state is left intact, which keeps a save-on-failure handler viable.

A lost device is not recovered

A device lost while running arrives on engine.graphics.on.contextLost, carrying a ShadeDeviceFailure with reason DeviceLost. Nothing renders after this. Every buffer, texture and pipeline lived on that device and went with it; the honest response is to say so and reload. on.contextRestored exists because the contract has it, but it never fires - a subscriber there is waiting for something that will not happen.

Engine tolerates the outage for two seconds and then pauses the simulation, on the assumption that a player who cannot see anything should not have the world run on without them. It does not install a failure view on this path, so telling the player is yours to do.

How the ECS binds to Shade

engine.graphics is a GraphicsEngine (src/engine/graphics3/GraphicsEngine.js, named export). Engine constructs it; you never do. It is deliberately a narrow facade rather than a renderer handle: the seam Engine needs in order to boot, plus a short list of things let through by name.

Five signals sit on engine.graphics.on:

The lifecycle is symmetric. GraphicsEngine starts from Engine.start() and stops from Engine.stop(), so start -> stop -> start returns a working renderer.

The scene, and the black-frame trap

There is one Shade Scene per engine and EngineHarness.shadeScene(engine) hands it out - built on first ask and cached against the engine. Every system that needs a scene should ask for it here rather than constructing its own, or entities end up in scenes nobody draws.

Only three systems call set_scene themselves: LightSystem, MeshSystem and ParticipatingMediaSystem. An app that registers ShadedGeometrySystem alone and never calls set_scene gets a black frame - the renderer is running, the meshes exist, and nothing has told the facade what to draw. There is no warning; the picture is simply empty.

import { EngineHarness } from "@woosh/meep-engine/src/engine/EngineHarness.js";
import { LightSystem } from "@woosh/meep-engine/src/engine/graphics3/LightSystem.js";
import { ShadedGeometrySystem } from "@woosh/meep-engine/src/engine/graphics3/ShadedGeometrySystem.js";

const engine = await EngineHarness.bootstrap({
    configuration(config, engine) {
        const scene = EngineHarness.shadeScene(engine);

        // LightSystem calls set_scene, so this wiring is complete
        config.addSystem(new LightSystem(engine.graphics, scene));
        config.addSystem(new ShadedGeometrySystem(engine.graphics, scene));

        // without a LightSystem / MeshSystem, say it yourself:
        // engine.graphics.set_scene(scene);
    }
});

The frame

Six phases, in the order they occur. Each names a moment where a specific set of frame records exists and is stable.

The upscale is a phase boundary and it is the one thing about the frame you cannot assume away. AfterGBuffer, AfterLighting and AfterTransparency run at the internal render resolution; BeforePresent and Overlay are on the far side of TAA/NSS at output resolution. With feature_taa_enabled === false there is no upscale at all and the two sides match. Never state a resolution as a constant - ask frame.resolution, which is derived from the live handle.

SceneColor is deliberately not carried at Overlay: the canvas is written there and a texture cannot be a render attachment and a sampled source in the same pass. Render extensions covers the mechanism - the records, ordering, and the extensions that ship.

The rendering systems

Rendering systems live in src/engine/graphics3/, are named exports, and take explicit collaborators rather than the engine. Most register a render extension at startup and remove it at shutdown. Several have deprecated <Name>3 aliases (MeshSystem3, LightSystem3, …); use the unsuffixed name.

Import as @woosh/meep-engine/src/engine/graphics3/<Module>.

Engine registers none of these; it only constructs GraphicsEngine. EngineHarness.buildBasics registers CameraSystem and LightSystem, plus TerrainSystem and WaterSystem when terrain is enabled - but never a mesh system, which is why a harness app that wants to draw models registers MeshSystem or ShadedGeometrySystem itself.

What is deliberately absent

Where to go next

The rest of this section, in reading order:

• Meshes & materials - ShadedGeometry, geometry vs meshlet geometry, StandardShadeMaterial, textures.
• Lights & shadows - the Light component, photometric units, froxel binning, cascades.
• Sky & environment - the one octahedral texture that is both the IBL source and the background, and volumetric fog.
• Global illumination - indirect_lighting_mode, the Brick4 bake, and the VolumetricLightMap component.
• Effects - decals, outlines, camera shake, and the dynamic-mesh path.
• Particles & VFX - Particular’s CPU simulation and the one Shade billboard pass.
• Trails - Trail3D, and why Trail2D renders nothing.
• Virtual texturing - material.vt_stack, streamed pages, and the residency loop.
• Picking - PickingSystem, the async batched ray query.
• Render extensions - the frame records, phase ordering, and putting your own pass in the frame.
• Frame settings & post-processing - the renderer.feature_* switches, upscaling, and the post-process sub-objects.

Terrain and water are rendering systems too, but they are documented with the rest of the world content: Terrain and Water & overlays.