Architecture Overview

How Particle Engine v2 is organized — from GPU hardware to gameplay systems. Everything flows through the VirtualGPU abstraction layer.

The Big Picture

Particle Engine v2 is a pure-browser WebGPU game engine. There is no Node.js, no build step, no transpilation. Every module is an ES module that runs directly in the browser. The engine is organized into layers, each building on the one below it:

Layer Breakdown

Layer 1: WebGPU API (Browser)

The raw WebGPU API provided by the browser. It gives low-level access to GPU hardware — device creation, buffer allocation, shader compilation, command encoding, and queue submission. Powerful but verbose.

Layer 2: VirtualGPU — The Core Abstraction

The VirtualGPU class wraps the raw WebGPU API with automatic resource management. Instead of writing 20+ lines of boilerplate, you write 1 line:

// Initialize once
const vgpu = await VirtualGPU.create();

// Create a buffer — vGPU handles usage flags, pooling, tracking
const { buffer } = vgpu.buffer.create({ size: 1024, usage: 'vertex' });

// Compile a shader — cached automatically
const module = vgpu.shader.compile('myShader', wgslCode);

// Create a render pipeline — blend states resolved from strings
const pipeline = vgpu.pipeline.render({ vertex: { module }, fragment: { module }, blend: 'alpha' });

The vGPU layer manages 6 core subsystems plus 20+ advanced modules:

Layer 3: ECS + Rendering

The Entity-Component-System holds all game state. Entities are just IDs. Components are typed data arrays. Systems are functions that run each frame. The rendering pipeline reads from ECS components to draw the world.

Layer 4: Simulation Systems

GPU-accelerated simulation runs on compute shaders via vGPU. This includes:

• Particles — 100M+ GPU particles with SPH fluids, thermal simulation, chemistry, electromagnetic fields, flocking, and more
• Physics — Cloth (mass-spring), rope (PBD), fluid volumes, ragdoll
• Audio — Procedural synthesis, patch-based node graph, spatial audio, material-to-sound mapping
• AI — Behavior trees, steering, influence maps, squad tactics

Layer 5: Applications

The top layer is what users interact with:

• Editor — Full scene editor with viewport, entity inspector, particle editor, audio studio
• Game Client — The actual game runtime (menu, world, HUD)
• Test Suite — Interactive demos (this documentation site)

Directory Map

The repository is organized by concern. Each top-level folder has a clear purpose:

engine/                     ← Engine core (the library)
├── core/
│   ├── gpu/                ← VirtualGPU + 50 GPU utilities
│   ├── math/               ← Vec3, Mat4, Quat, scalar math
│   ├── events/             ← Event bus, signals
│   └── framegraph/         ← Frame graph resource scheduling
├── ecs/                    ← Entity-Component-System
│   ├── components/         ← Transform, Camera, Light, etc.
│   ├── systems/            ← Physics, Render, Camera systems
│   └── world/              ← World management
├── render/                 ← Rendering pipeline
│   ├── particles/          ← 30+ particle renderers
│   ├── shaders/            ← WGSL shader modules
│   ├── materials/          ← Material system
│   └── passes/             ← Render passes (depth, color, post)
├── sim/                    ← Simulation
│   ├── particles/          ← 60+ particle sim modules
│   ├── physics/            ← Rigid body physics
│   ├── cloth/              ← Mass-spring cloth solver
│   └── fluids/             ← Eulerian fluid sim
├── audio/                  ← Audio engine
│   ├── synth/              ← Procedural synthesis nodes
│   ├── bridge/             ← Material↔sound bridges
│   └── core/               ← Audio context, worklets
└── net/                    ← Networking (protocol, replication)

editor/                     ← Scene editor application
├── js/
│   ├── modules/            ← EditorParticles, EditorAudio, etc.
│   ├── panels/             ← Viewport, Inspector, World panel
│   └── components/         ← UI components
└── css/                    ← Editor styles

tests/                      ← Documentation & demo site (you are here)
├── guide/                  ← Engine manual
├── api/                    ← API reference
├── examples/               ← Interactive demos
└── common/                 ← Shared theme & utilities

Data Flow: A Single Frame

Here's what happens every frame in the editor (the most complex case):

Design Principles

What to Read Next