Runtime Reference

This page documents the runtime-facing modules that power the demo. Test-only verification helpers are intentionally excluded; see the compute-shader notes for the CPU mirrors used to validate WGSL behavior.

Configuration

Runtime constants and shader preambles live in src/config/sim.ts.

Constant	Type	Default	Description
PARTICLE_COUNT	number	10000	Default number of particles
PARTICLE_SIZE	number	16	Bytes per particle (4 floats)
WORKGROUP_SIZE	number	64	Compute shader workgroup size
GRAVITY	Vec2	{x: 0, y: 600}	Gravity acceleration (px/s²)
DAMPING	number	0.9	Velocity damping on bounce
REPULSION_RADIUS	number	200	Mouse influence radius (px)
REPULSION_STRENGTH	number	3000	Mouse repulsion force
MAX_SPEED	number	800	Maximum velocity (px/s)
TRAIL_FADE_ALPHA	number	0.05	Trail fade per frame

function buildComputeShaderPreamble(): string;
function buildRenderShaderPreamble(): string;
function buildTrailShaderPreamble(): string;

These helpers inject TypeScript-owned constants into WGSL at pipeline creation time.

Shared Types

src/types.ts holds the shared contracts between the runtime, shader setup, and tests.

interface Particle {
  x: number;
  y: number;
  vx: number;
  vy: number;
}

interface Vec2 {
  x: number;
  y: number;
}

interface Uniforms {
  width: number;
  height: number;
  mouseX: number;
  mouseY: number;
  deltaTime: number;
  _pad1: number;
  _pad2: number;
  _pad3: number;
}

interface WebGPUContext {
  adapter: GPUAdapter;
  device: GPUDevice;
  context: GPUCanvasContext;
  format: GPUTextureFormat;
  canvas: HTMLCanvasElement;
}

Runtime Modules

Application bootstrap (src/main.ts)

The bootstrap path is intentionally thin:

1. size the canvas,
2. initialize WebGPU,
3. resolve adaptive quality,
4. create GPU resources,
5. attach input and overlays,
6. start the renderer.

Canvas sizing (src/core/canvas.ts)

function setupCanvas(canvas: HTMLCanvasElement): void;

Keeps the canvas synced to the viewport and device pixel ratio.

WebGPU initialization (src/core/webgpu.ts)

async function initWebGPU(canvas: HTMLCanvasElement): Promise<WebGPUContext>;
function reconfigureContext(ctx: WebGPUContext): void;

Owns adapter/device acquisition, canvas context configuration, and resize reconfiguration.

Runtime quality (src/core/quality.ts)

type SimulationQualityTier = 'low' | 'medium' | 'high';

interface RuntimeSimulationSettings {
  particleCount: number;
  qualityTier: SimulationQualityTier;
  scale: number;
}

function resolveSimulationSettings(
  input: SimulationHeuristicsInput,
  preferredParticleCount?: number
): RuntimeSimulationSettings;
function readRuntimeHeuristics(adapter: GPUAdapter, device: GPUDevice): SimulationHeuristicsInput;

Derives a safe particle budget from the current device and viewport.

GPU resource assembly (src/core/simulation-resources.ts)

interface SimulationResources {
  buffers: ParticleBuffers;
  pipelines: Pipelines;
}

function createSimulationResources(
  device: GPUDevice,
  format: GPUTextureFormat,
  canvasSize: Vec2,
  particleCount?: number
): SimulationResources;
function destroySimulationResources(resources: SimulationResources): void;

Creates the particle buffers, uniform buffer, pipelines, and bind groups as one coherent unit.

Frame orchestration (src/core/renderer.ts)

class Renderer {
  start(): void;
  stop(): void;
  destroy(): void;
}

function createRenderer(
  ctx: WebGPUContext,
  pipelines: Pipelines,
  buffers: ParticleBuffers,
  getMousePosition: () => Vec2,
  onFrame?: () => void
): Renderer;

Owns the render loop, offscreen trail texture lifecycle, and GPU submission.

Input and overlays (src/core/input.ts, src/core/app-shell.ts)

These modules stay intentionally simple:

• createMouseHandler() tracks pointer/touch position in canvas space.
• createFPSCounter(), createInfoOverlay(), createLoadingIndicator(), and showError() own the minimal DOM shell around the demo.

Data Layouts

Particle Buffer

Offset	Size	Field	Type
0	4	x	f32
4	4	y	f32
8	4	vx	f32
12	4	vy	f32

Uniform Buffer

Offset	Size	Field	Type
0	4	width	f32
4	4	height	f32
8	4	mouseX	f32
12	4	mouseY	f32
16	4	deltaTime	f32
20-28	12	_pad	f32