Light, space,
and the machinery between.

A place to begin, whatever your background.

You do not need to know how a GPU works to explore the lab. Start with a room, a sunlit patch and a shaded surface. Change one thing and watch what happens. This manual connects those observations to the code that produces them.

What you are looking at

A scene is an arrangement of surfaces. A renderer decides the colour of each visible pixel using those surfaces, the camera, materials and lights. FMVisual coordinates those pieces and supplies original procedural architecture. Three.js supplies the current GPU lighting algorithms.

The architecture is inspired by the qualities of great atrium and Sponza demonstrations: layered arches, deep shade, textured surfaces and sunlight entering sheltered space. These are original generated scenes. Running them requires no downloaded Sponza model, cloud machine or account.

Run locally

cd ~/FMVisual
npm ci
make app PORT=4173
# Open http://127.0.0.1:4173/framework.html

Use the dependencies in the lockfile and the Node version required by the installed Vite package. Tracker Desk launches the same local application. The manual itself does not start a renderer; the lab and runnable tutorial do.

The room you see and the light it remembers.

Follow a sunbeam

1. Direct light: sunlight reaches the floor through the roof. A shadow map estimates whether something blocks the sun.
2. Indirect light: some light leaves that floor and reaches a shaded column. A red wall can tint nearby stone. This is the diffuse light transfer the voxel representation approximates.
3. Material response: the receiver’s base colour, roughness and other material properties affect the final appearance. Raising exposure makes the image brighter; it does not create a missing bounce.
4. Display: the renderer stabilizes samples, optionally adds atmosphere and bloom, then maps bright scene values into the display’s range.

Two resolutions, two kinds of detail

Screen resolution controls the visible image. Voxel spacing controls how finely the lighting representation distinguishes surfaces. More screen pixels will not make a thin wall survive a coarse voxel grid. More geometric carving will not automatically improve light transport. Design both scales deliberately.

Why frames remember earlier frames

Tracing a small number of cones is affordable but produces an imperfect estimate. Temporal filtering combines evidence across frames, using depth and motion to find the previous location of a surface. Stable views gain smoothness. Newly revealed areas must reject old information or they can smear. History resets are essential after camera cuts, output changes and changes to lighting.

The combined view uses temporal resolve when enabled. Diagnostic views deliberately use stationary cones and bypass the final temporal resolve. Treat those views as instruments for a specific representation rather than a photograph of the finished room.

One runtime. Clear responsibilities.

The application supplies scenes, settings and a container. The framework owns the camera, controls, animation loop, resize handling and rendering lifecycle. Each scene owns its geometry, materials and textures.

Six stages to inspect and factor.

Select a stage to see its inputs, outputs and current implementation. The independent algorithm replacements remain planned work.

Actual frame composition: depth / normals / motion → voxel irradiance & visibility → material lighting → optional shadowed air → temporal resolve → restrained bloom. Reflection uses an additional clipped scene camera.

What actually happens in a frame.

Once at startup

The runtime initializes a renderer, tries WebGPU and falls back to WebGL when necessary. It creates the camera, controls, directional sun and ambient light. A scene factory returns fresh resources. Bounds are supplied or inferred, the camera is placed, budgets are resolved and the chosen backend creates its passes. A resize observer fits the canvas to the container.

1. Move the camera. The loop advances an authored tour or applies the selected navigation controller. Walk uses elapsed time, smooth velocity and a planar heading. A camera cut explicitly clears rendering history.
2. Render surface evidence. The WebGPU backend produces depth, packed normals and velocity. Depth answers which surface is visible; velocity helps match it to previous frames.
3. Estimate indirect light. Upstream VXGI manages the world’s voxel representation, injected lighting, directional hierarchy and cone integration. These are conceptual transport stages inside the backend, not six independent FMVisual plugins.
4. Shade and compose. A scene pass applies material lighting and, for the combined output, indirect illumination. Optional atmosphere samples the sun’s shadow map at half resolution and blends against depth. A declared pool can use a separate clipped reflection camera.
5. Resolve and present. Combined output optionally passes through TRAA, then restrained bloom. Other selected outputs route their diagnostic textures instead. The renderer applies exposure and tone mapping.
6. Report periodically. Every 30 frames the host receives average frame interval and FPS. These include scheduling and other delays; they are not isolated GPU execution timings.

When something changes

Current capabilities, without the guesswork.

The same controls in every scene.

Owned resources. Authored places.

Factories return fresh scene objects with a group, camera position, target and a disposal function. Optional metadata adds camera studies, a slow rail, scene lighting, a planar pool and a reference span for quality-preserving growth.

The first extension keeps the original atrium geometry as an exact fixture. The lantern passage and sun court belong to one continuous world, not a loading transition.

Preserve detail before adding radius.

Your first room, from eight boxes.

A floor, three walls, two roof pieces and two neutral blocks make a useful lighting experiment. The left wall is red. The central roof slot admits direct sun; surrounding surfaces let you inspect diffuse transfer. This example imports only the public framework and Three.js.

1. Read the scene factory. A unit box is shared by all meshes, then scaled and placed. The floor’s top is at Y = 0. Positive Y is up; the camera looks generally toward negative Z. Metres are an authoring convention, not enforced physical units.
2. Notice the light flags. Each surface casts and receives shadows. Material colour and roughness are explicit. The factory has no renderer or animation loop.
3. Register and start. The host creates a registry using the custom ID first, supplies a quality map and complete settings, then awaits the runtime.
4. Compare fairly. Use Direct and Combined at the same camera. Expect subtle reflected colour near the red wall, not a neon flood. On fallback the room remains visible, but indirect comparison is unavailable.
5. Make one change. In src/examples/first-scene.js, change the red wall to blue or widen the roof slot. Save and reload. Observe which surfaces change in Direct, then Combined.
6. Release ownership. Stop & dispose removes the canvas and releases the runtime and scene resources. Reload to create a new instance.

These listings are imported from the executable source at build time. They are not separately maintained pseudocode. The example is also included in the production build at /examples/first-scene.html.

A small public entry point.

Import from src/framework/index.js. Register scene factories, pass settings and quality presets, then keep the returned runtime until the application closes.

const scenes = createSceneRegistry({ gallery: createGallery });
const app = await createVisualization({
  container, scenes, settings, qualities, onFrame
});

app.update(nextSettings);
app.resetCamera();
app.dispose();

World fields: the complete current surface

Runtime returned by createVisualization

Callbacks are events, not a single fixed record

onFrame(event) receives one of: {fps, frameMs, gpu}, {error}, {motion: 'still'} or {navigation: {enabled, locked, dragFallback}}. Inspect the fields present before updating UI. Navigation events may arrive during initialization, before the awaited runtime variable is assigned. Use the event data directly there.

A backend is a lifecycle boundary

createBackend(context) is synchronous. Context contains renderer, scene, camera, settings, qualities, sun, volumeQuality. Call volumeQuality(id) for the actual density-preserving resolution. The adapter must provide render(), update(next), resetHistory(), dispose() and a boolean capabilities.indirect. Built-in adapters also report capabilities.temporal and a readable name.

Backend version 1 expresses this local contract. It is not a stable external plugin ABI. A replacement must define who owns every pass and texture, respond correctly to updates, and prove its capabilities with actual images. Naming an adapter VXGI does not supply an implementation.

Settings, with units and consequences.

These ranges are the lab validator’s current supported range. The reusable runtime does not apply that validator for you. Custom hosts must validate their own scene IDs, quality keys, camera IDs and numeric values. Start with the complete tutorial object.

How spatial cost grows

Let S be the longest world span, S₀ the optional reference span and R₀ the preset resolution. The actual longest-axis resolution is R = ceil(R₀ × max(1, S / S₀)) when a reference span is provided; otherwise R = R₀. Voxel spacing is S / R. The actual allocated dimensions include padding and mip alignment.

At Balanced quality the original atrium’s span is about 28.485 units and the extension’s is 41.835. Resolution rises from 80 to 118, keeping spacing near .355 units. The aspect-aware padded grid grows from 197,120 to 286,720 base cells. These are base-grid cell counts, not total texture bytes; directional levels, intermediate passes and temporal buffers add cost.

Extending one axis is cheaper than scaling all three. Doubling every axis while keeping spacing fixed needs roughly eight times as many base cells before padding. Raising screen resolution additionally increases screen-space pass cost. More cones and bounces add work independently. Measure one variable at a time; the largest quality preset is not a universal default.

Diagnose a representation, then adjust it.

Freeze the camera. Turn atmosphere and bloom off. Use a fixed light study. Compare Direct, Combined and the relevant diagnostic output with identical settings. Preserve the failing case before changing several controls.

Three ways to extend the framework.

Keep these questions beside the editor

• Which representation changes: visible meshes, lighting cells, screen-space output or temporal history?
• Who owns new resources, and who releases them?
• What happens on scene switch, resize, settings change and teardown?
• Is the fallback accurate about what it can render?
• Can another person reproduce the result with recorded settings and a fixed camera?
• Does the change preserve architectural contrast and measured spacing as well as visual richness?

A pocket vocabulary.

Albedo / base colour

The surface’s underlying colour, before illumination and display exposure.

Ambient occlusion

An estimate of how enclosed a point is. Useful for contact and recesses; it does not transfer coloured light.

Depth

How far a visible surface is from the camera, encoded in a buffer. It enables effects to respect surface boundaries.

Disocclusion

A surface newly revealed as something else moves away. Earlier frames may have no valid history for it.

Irradiance

Light arriving at a surface from its surroundings.

Radiance

Light travelling in a particular direction. The voxel hierarchy stores a filtered directional approximation.

Mip level

A coarser filtered version of a representation. Wider cones can sample coarser levels to cover a larger region efficiently.

Normal

A direction perpendicular to a surface. Lighting uses it to determine orientation relative to incoming light.

Parallax

Near objects move across your view faster than distant ones as the camera moves. Layered columns and arches make this especially legible.

PBR / roughness

Physically based material conventions. Roughness controls how broad or sharp specular reflections appear.

Temporal history

Information retained from earlier frames. Valuable only where the old and new surfaces still correspond.

Tone mapping

Compressing a scene’s wide brightness range into a displayable image while preserving useful contrast.

Voxel / texel / pixel

A cell in a volume, an element of a texture, and an element of the displayed image. They belong to different spaces.

VXGI / TRAA

Voxel global illumination and temporal reprojection antialiasing: the upstream Three.js systems currently used here.

Module map.

Teach the judgment behind the image.

The teaching method prepares ten real students to continue FMVisual with decreasing teacher intervention. Everyone first builds and explains a small room individually. Five pairs then rotate through architecture, materials, lighting, navigation and integration, before an independent transfer and a recipient handoff.

Try the first activity

Predict what a wider roof opening or a blue wall will do in Direct and Combined. Keep the camera and lighting fixed. Then implement a second camera, diagnose an isolated partial-settings update, verify a density-preserving expansion and hand the room to a recipient. Keep each learner's copy separate from the production lab.

Evaluate the method with observed work

The technical rehearsal checked the exercise on WebGPU and direct fallback, detected deliberate update and density mistakes, and led to a clearer colour-lighting condition. The human pilot is prepared; students have not yet participated. A learner pilot additionally needs real submissions, recorded help, transfer attempts and handoff observations. An AI-agent pilot tests agent continuation under stated conditions; it does not establish human learning or retention.

Read the rehearsal evidence and next pilot conditions ↗

A green build is only the start.

No accidental white edge.

A finite scene can imply a much larger world. Design reachable space, middle-distance architecture, the horizon and transitions separately. A distant roofline may need only a convincing silhouette; the floor beneath your feet needs geometry, navigation and valid lighting coverage.

Start with a deliberate walkable envelope and composed views through every exit. Add low-cost context before another fully detailed wing. For larger growth, prepare the next region early and use overlapping lighting zones rather than stretching one grid until detail disappears.

Keep distant context from inflating nearby lighting bounds without an explicit coverage policy. Test backtracking, fast movement, camera rails and reflected views. The Hillside sanctuary now has contained walking, a valley arcade, cypress garden and a separate distant landscape. Its reference scenes remain unchanged. The world is fully resident; multiple lighting zones remain FMV-25.

The design brief is World boundaries and staged expansion.

Keep the detail close. Let the world continue.

Imagine leaving the arcade, descending through the garden, passing beneath the aqueduct and entering a house that is now a distant silhouette. On the return, the sanctuary should keep its shape, its stonework and the same sheltered light. That journey is our next architectural target.

Our budget starts with the sanctuary

Balanced lighting currently uses 499,200 base cells at about .356-unit spacing. The distant landscape is a separate visual layer. Making that landscape visitable requires terrain navigation, stable detail transitions, overlapping lighting zones and bounded loading. Those systems are planned; the current world is fully resident.

1. Address the places. Stable coordinates, region IDs, seeds and saved overrides.
2. Connect the ground. Matching terrain edges, walkable slopes, steps and foundations.
3. Connect the light. Two bounded zones with consistent doorway illumination and measured memory.
4. Bound the working set. Prefetch, cancellation, safe release and deliberate low-detail substitutes.
5. Grow the vocabulary. Shared architectural parts, material detail, authored landmarks and meaningful variation.

Each extension must pass an out-and-back journey, moving-camera quality checks, repeated unloading and the same-camera cost comparison. A direct preview checks the route; real WebGPU is needed to qualify voxel lighting. The detailed plan separates present evidence from future requirements.

What is still ahead.