Rendering Pipeline

GPU-driven rendering with meshes, lights, materials, shader modes, and multi-pass compositing. All rendering is built on the VirtualGPU abstraction.

Frame Structure

A typical frame in the editor/game follows this pass order:

// Simplified frame from Viewport.js (~6K lines)
1.  Update camera matrices (view, proj, viewProj, invViewProj)
2.  Upload frame uniforms (camera, time, lighting)
3.  [Debug] Particle debug pre-pass (if particle-specific mode active)
4.  [Debug] Particle depth pre-pass (if scene debug mode: depth/normals)
5.  Hybrid volume compute pass (density grid splatting)
6.  Main render pass:
        a. Entity mesh rendering (GPU instanced, dynamic lighting)
        b. Grid rendering (ground plane with sun + ambient)
        c. SDF collider visualization
        d. Cloth / Rope rendering
        e. Particle rendering (full-res or deferred half-res)
        f. Volumetric smoke rendering
        g. Gizmos, wireframes, debug overlays
7.  Depth buffer copy (for soft particles + debug viz)
8.  [Debug] Scene Debug Visualizer post-pass (depth/normals from actual depth buffer)
9.  Shadow Atlas (unified depth → per-category composite)
10. Half-res particle composite (if deferred)
11. Distortion pass (heat haze)
12. SPH fluid surface pass (screen-space fluid rendering)
13. Bloom pass (emissive glow)
14. Tonemap pass (ACES + vignette)
15. Reconstruction (TSR/FSR/SVGF upscaling) + GPU submit

Lighting System

The LightManager handles all lighting via a single GPU uniform buffer (832 bytes). It supports sun (directional), ambient, and dynamic point lights.

Light Properties

Shader Modes

The renderer supports 4 debug modes controlled by lightingMode and debugMode:

Particle Lighting Integration

Particles interact with lighting in three ways:

1. Receive — Particles sample sun + ambient from frame uniforms
2. Emit — Hot particles (fire/plasma) become dynamic point lights via ParticleLightEmission.js
3. Shadow/Tint — Smoke dims sunlight (particleSunShadow), fire tints it warm (particleSunTint)

Mesh Rendering

Entity meshes are rendered by EntityMeshRenderer which reads from ECS Renderable and Transform components. Each entity gets a per-object uniform buffer containing its model matrix, and a bind group linking the uniform to the shader.

Mesh Pipeline

// EntityMeshRenderer creates pipelines via vGPU
const pipeline = vgpu.pipeline.render({
  vertex: { module: meshShader, entryPoint: 'vs_main', buffers: vertexLayouts },
  fragment: { module: meshShader, entryPoint: 'fs_main', targets: [{ format }] },
  depthStencil: true,
  label: 'EntityMesh'
});

Half-Resolution Particle Compositing

Particles are rendered at half resolution for performance, then composited onto the main scene:

1. SDF Shader outputs vec4(litColor, alpha) — non-premultiplied
2. SDF Pipeline renders into half-res bgra8unorm texture with alpha blend
3. Half-res texture starts cleared to (0,0,0,0); after alpha blend: RGB = lit × alpha (pre-multiplied)
4. Composite pass uses fully additive blend (one + one) onto the scene

Grid Renderer

GridRenderer.js draws the ground plane as a solid fill (alpha 0.85) with sun + ambient lighting. It receives lighting data from LightManager via setLighting() each frame.

Shadow Atlas

The ShadowAtlas provides unified shadow rendering for the entire scene. All shadow casters (entities, ropes, particles) render into a shared 4096² depth texture, then shadows are composited per category with independent PCF, bias, and strength settings.

// Shadow caster categories
'entity'   → EntityMeshRenderer.flushShadowDepth()
'rope'     → RopeMeshRenderer shadow pass
'particle' → ParticleShadowCaster (round billboard shadows)

Debug Visualization

The engine provides a two-tier debug visualization system accessible via the editor’s view mode dropdown:

Scene-Wide Modes (Post-Process)

These modes read the actual hardware depth buffer (containing meshes + ropes) and composite with a particle depth color texture. They run as a fullscreen post-pass via SceneDebugVisualizerPass.

Particle-Specific Modes (Pre-Pass)

These modes render particles to a separate rgba16float texture using specialized debug renderers, then display as a fullscreen overlay. All use circular billboard clipping (dist > 1.0 discard).

Other Debug Systems

• VGPUDebugDraw — Immediate-mode lines, boxes, spheres, frustums
• Gizmo renderers — Translation/rotation/scale handles (editor)
• Collision debug — Wireframe collider visualization

Key Files