# The engine

> A tour of the WebGPU engine that draws every World, one folder at a time.

The engine is written directly on WebGPU, with no framework in between. It
started as [Tidewater](https://github.com/dgreenheck/tidewater), Daniel
Greenheck's ocean and island renderer, and Orbium has grown it with what its
games need: grass, wind-blown sand and snow, tracks in the ground, dust, a sky
full of far things. It lives in `engine/` and knows nothing of the
games.

## The folders

| Folder                                 | What it does                                                                |
| -------------------------------------- | --------------------------------------------------------------------------- |
| gpu/ (`engine/gpu/`)               | The device, buffers and textures, WGSL modules, compute kernels             |
| render/ (`engine/render/`)         | Materials, the mesh renderer, shadows, full-screen passes                   |
| scene/ (`engine/scene/`)           | Objects, groups, meshes and cameras                                         |
| math/ (`engine/math/`)             | Vectors, matrices, quaternions, frustums (pure: the server uses it too)     |
| terrain/ (`engine/terrain/`)       | The island's ground, its level of detail, rocks, the shore field            |
| ocean/ (`engine/ocean/`)           | The sea: FFT waves, shore waves, surf, foam, caustics                       |
| sky/ (`engine/sky/`)               | The atmosphere, clouds and the environment light                            |
| post/ (`engine/post/`)             | Upscaling, ambient occlusion, haze, motion blur, bloom, the underwater lens |
| fx/ (`engine/fx/`)                 | Particles: spray, dust, sand and snow on the wind, marine snow              |
| vegetation/ (`engine/vegetation/`) | Grass, pushed down by whatever moves through it                             |
| materials/ (`engine/materials/`)   | The scene's lighting and local lights                                       |
| audio/ (`engine/audio/`)           | The mixer: placed sounds, ambience, the muffle under water                  |

## A frame

Each frame, every system updates on the CPU, then records its GPU work into one
command encoder, sent to the GPU in a single submit:

1. **Simulation**, in compute passes: the atmosphere's lookup tables, the
   ocean's FFT, the surf, caustics, particles, clouds, terrain and grass
   selection.
2. **Shadows**: cascaded maps of the sun, the far cascades updated less often.
3. **The scene**: opaque meshes and the sky, then everything under the water at
   half resolution (for refraction), then the water and transparent objects.
4. **Post**: ambient occlusion, haze and light shafts, temporal upscaling,
   motion blur, lens flare, bloom, exposure, grading and tone mapping.

The graphics presets switch whole systems off and change the resolution and
budgets: see [requirements](https://orbium.games/docs/platform/requirements#graphics).

## Procedural, not loaded

There are no model or texture files. The terrain is generated from noise, the
rocks are shaped from seeds (RockShape.js (`engine/terrain/RockShape.js`)),
foam and detail textures are generated on the GPU at start. A World costs a few
megabytes, most of it sound.

## Next

- [WebGPU in Orbium](https://orbium.games/docs/developers/webgpu-basics): how the engine talks to
  the GPU.
- [The ocean](https://orbium.games/docs/developers/ocean): the first system in depth.