Weft & Loom

A weaver's words

On a loom, long threads called the warp are stretched tight. The weaver passes another thread, the weft, across them, one row at a time. Nothing in one row is special. But row after row, a picture appears in the cloth.

A computer draws a moving picture in much the same way. Sixty times a second, it builds a fresh image from scratch, in a series of sweeps across the screen. Each sweep adds one thing: the shape of the land, then the shadows, the sea, the clouds, the glow of the light. In graphics these sweeps are called passes. Get enough of them right, in the right order, and you have a world.

So the two pieces of this engine are named for the weaver's trade. Weft is the thread: a tiny toolkit for running passes on the graphics card, through the new WebGPU standard in your browser. Loom is the machine built from it: a renderer that knows how to weave a sky, a sea, weather and film. The games are the cloth.

This page is a tour, layered for different readers. The main text is for anyone curious. The blue boxes go into how the ideas work. The violet ones are for people who write shaders for fun. Open as many as you like, or use the Depth switch at the top to open them all.

Thirty-three milliseconds

Here is one frame of Starthread, at golden hour over the harbour town of Lowlight. Your graphics card made it in a few hundredths of a second. It took 55 passes.

Before a single pixel of the picture is drawn, about twenty compute passes run: they work out the colour of the sky for this exact sun, decide which of the forest's trees are worth drawing, step the ripples on the water, bake the clouds' weather and light. Then the picture is woven, layer by layer. Scroll to watch it come together. These are real captures from the game, with its passes switched on one group at a time.

Two ways to describe a world

There's a wonderful library for 3D on the web called three.js. Most 3D you've seen in a browser was probably made with it. So why build something else? The honest answer is not that one is better. They begin from different questions.

three.js asks: what is in your world? You describe a scene graph, a tree of objects. A mesh has a geometry and a material. A light hangs in the tree. A camera looks at it. Then you hand the whole tree to a renderer, and the renderer works out the passes for you: what to draw, in what order, with which shaders, how to do the shadows.

Weft asks: what does your frame do? There's no tree of objects. You write the list of passes yourself, and each one says exactly which images and buffers it reads and writes. What you list is what runs, in that order. Nothing else happens.

Neither is free. A scene graph means you get on with your world: load a model, add a light, it works. The price is that the frame belongs to the renderer. When you want to do something it didn't plan for, you work around it, through hooks, custom passes and extension points. three.js is very good at offering those, and it has been growing towards explicit GPU work too: its newer WebGPU renderer has compute and a node-based shading language (TSL) for writing custom passes.

An explicit frame means you do more yourself. There is no material system, no model loader, no shadow you didn't write. The reward is that nothing is hidden. For games built around unusual light, like clouds you fly through, rain lit by headlamps, a sea you can see into, the frame is the work, and it pays to own it outright.

What owning the frame gives you

What it costs you

So which should you use?

For most projects, three.js (or Babylon.js, or PlayCanvas), and that's said without irony. For a product viewer, a portfolio, an interactive story, most games: start there. Reach for something like weft when the frame itself is your subject, or you want to learn what a renderer actually does. Try it:

The shader is the source of truth

Programs on the GPU are written in a language called WGSL. Programs in the browser are written in JavaScript or TypeScript. The two have to agree, to the byte, on how every piece of data is laid out. Getting that wrong is the classic graphics bug: nothing crashes, the picture is just mysteriously wrong.

Most engines describe the data twice, once in the shader and once in the program, and trust you to keep them in step. Weft describes it once. You write a struct in WGSL, and a build step reads the shader and generates the matching TypeScript. Then your editor knows every field's name and type, and a typo is a red squiggle instead of a black screen.

The layout rules are where people get burned. A vec3f takes 12 bytes but insists on starting at a multiple of 16, so the GPU quietly inserts padding. Build a struct and watch:

Bindings work the same way. A shader declares the resources it needs, like var<uniform> sim: Sim or var prev: array<Cell>, and in TypeScript you hand them over by those names: bind: {'{'} sim, prev: state.read {'}'}. Misspell one and weft tells you which shader, which name, and what it expected.

Here's the smallest complete weft program: a ripple tank simulated in a compute pass, drawn as a lit surface, with a sky and a film curve. It's running live, from the same npm package the games use. Click the water.

import { createKit } from '@ericrius1/weft';
import ripple from './ripple.wgsl';
import water from './water.wgsl';
import post from './post.wgsl';

const kit = await createKit(canvas);
const N = 256;

// two buffers of height cells: read one, write the other
const state = kit.pingpong((i) =>
  kit.storage({ label: `ripple${i}`, count: N * N, stride: 8 }));

// uniforms typed from the WGSL structs
const sim = kit.uniforms(ripple.structs.Sim)
  .set({ size: N, damping: 0.996, speed: 0.35, dropRadius: 5 });
const look = kit.uniforms(water.structs.Water)
  .set({ size: N, extent: 40, heightScale: 0.6, sunPower: 18 });
const tone = kit.uniforms(post.structs.Post)
  .set({ exposure: 1.1, vignette: 0.35 });

const hdr = kit.texture({ format: 'rgba16float', size: 'render' });
const depth = kit.texture({ format: 'depth32float', size: 'render' });

// one compute pass: the wave equation, one step
const step = kit.compute(ripple, {
  bind: { sim, prev: state.read, next: state.write },
  threads: [N, N] });

// one render pass: the water surface, then the sky behind it
const scene = kit.pass({ color: [{ target: hdr, clear: [0,0,0,1] }],
                         depth: { target: depth, clear: 0 } });
scene.draw(water, { bind: { water: look, state: state.read },
                    count: (N - 1) * (N - 1) * 6 });
scene.fullscreen(water, { fragment: 'fs_sky', bind: { water: look },
                          depthCompare: 'equal' });

// and the film: HDR → the screen
const out = kit.pass({ color: [{ target: 'screen' }] });
out.fullscreen(post, { bind: { post: tone, hdr } });

await kit.ready();   // every pipeline compiled before frame one
kit.loop(() => {
  kit.run([step, state.swap, step, state.swap, scene, out]);
});

Read the last line: kit.run([step, state.swap, step, state.swap, scene, out]). That's the whole frame: simulate, swap, simulate, swap, draw, develop. Every game here ends each frame with a line like it, just longer.

Two smaller ideas make weft pleasant to work in. Pipelines compile up front: await kit.ready() waits for every shader, so a game never stutters the first time a new effect appears. And shaders reload without losing state: edit a .wgsl file while a game runs, and only the pipelines made from it are rebuilt. The ripples keep rippling, the plane keeps flying, and you see the change in under a second.

struct Sim {
  size: u32,
  damping: f32,     // @range(0.9, 1)
  speed: f32,       // @range(0, 0.5)
  dropRadius: f32,
  drop: vec4f,
}
@group(1) @binding(0) var<uniform> sim: Sim;
@group(1) @binding(1) var<storage, read> prev: array<vec2f>;
@group(1) @binding(2) var<storage, read_write> next: array<vec2f>;

Holding the frame

A game feels smooth when every frame arrives on time, more than when it's fast on average. Loom's games offer two presets. Epic renders a steady 30 frames a second at full detail. Smooth renders 60, and lets the resolution give first. Underneath both, weft can watch the GPU's own timer and nudge the render resolution to stay inside a budget. Throw a heavy scene at it:

Why the sky is blue, in code

Loom's sky isn't painted. It's computed from the physics of sunlight passing through air. That's why every hour of the day, every sunset and every blue hour in these games comes out right without anyone choosing its colours.

Sunlight is all colours together. Air molecules are tiny, and they scatter short wavelengths far more than long ones: blue about five times more than red. So the light that reaches you from every direction except the sun's is mostly blue, scattered towards you by the sky. When the sun is low, its light crosses so much air that the blue is scattered away before it arrives, leaving the reds and oranges. Bigger particles (dust, haze, droplets) scatter all colours, mostly forwards, which makes the bright glow around the sun.

Flying through a cloud

In Stormbreak you can fly into a thunderhead, lose the enemy inside it, and come out the other side through the hole you tore. Clouds you can enter can't be painted onto the sky. They have to be real volumes, and drawing them takes three ideas.

1 · Shape from noise

A cloud's shape starts as noise: a smooth, random-looking 3D pattern. Clouds form where the air is wet enough, so the engine keeps only the parts of the noise above a threshold set by coverage. Slide it to grow a sky. Underneath, a weather map drifts across the world deciding where coverage is high, what type of cloud forms, and how storm-like it is.

2 · Light by marching

To find a pixel's colour, the engine sends a ray from your eye into the cloud and walks along it in steps. At each step it asks how dense the cloud is there and how much sunlight reaches that spot, and adds a little light. It also dims everything behind, because a cloud absorbs as well as glows. This is ray marching.

Steps are expensive, so there are never enough. Too few and the cloud shows hard bands, one per step. The trick is to start each pixel's walk at a slightly different random offset. The bands become fine noise, and averaging a few frames makes the noise vanish. Try it:

3 · The silver lining

Water droplets don't scatter light evenly. They throw most of it almost straight ahead. So a cloud between you and the sun glows brightest at its thin edges, the silver lining, while a cloud lit from behind you looks soft and white. How much light goes in each direction is called the phase function. Swing the sun around:

A sea you can see into

Real waves don't move water across the ocean. Each bit of water goes round in a circle, and the shape of the wave travels on. Sum a dozen of those circles at different sizes and directions, and you get a sea.

This is a Gerstner wave. Because the points move sideways as well as up and down, they bunch together at the crests and spread out in the troughs: sharp peaks, flat valleys, the shape of real water. Turn up the steepness until the crests nearly fold over.

The colour of the sea is just as physical. Water absorbs red light within a few metres, green over tens, and blue last. Over pale sand in the shallows you see the light that survived the round trip: turquoise. Over deep water there's no sand to bounce back from, and you see the blue that water scatters itself. Loom tints whatever it sees through the sea by the thickness of water crossed, colour by colour.

Lamplight in the rain

Rainline is a night race in a thunderstorm, and most of its picture is light you can't normally see: headlamp beams and lamplight made visible by the rain and mist they pass through.

To draw a beam, the engine walks along each pixel's view ray and asks, at a few points, how much lamplight is there to be scattered towards you. But lamplight is very uneven. It's blinding next to the bulb and nearly nothing a few metres off, and with only a handful of samples, where you put them decides everything.

The rain itself is a lovely cheat: nothing is simulated. Every raindrop's position is a formula of its number and the time, falling through a box that wraps around the camera. It costs only the drawing. Drops are stretched along their motion relative to the camera, so driving into the rain draws them into streaks, and each splash is placed by picking a random spot on the screen and asking the depth buffer what surface is there: road, roof or bonnet.

const thA = Math.atan((a - delta) / D), thB = Math.atan((b - delta) / D);
const theta = thA + u * (thB - thA);           // u uniform in [0, 1)
const t = delta + D * Math.tan(theta);
const pdf = D / ((thB - thA) * (D * D + (t - delta) ** 2));

Developing the picture

Inside the engine, light has its real range. The sun's disc is tens of thousands of times brighter than a shadow under the trees. A screen can show maybe a thousand to one. Squeezing one into the other is called tone mapping, and it decides more of a game's look than almost anything else.

Chop the bright values off and the sky clips to a flat white slab. Squash them evenly and everything goes grey. Film did something cleverer: highlights roll off gently and lose their colour as they brighten, the way a real photo of a sunset fades to white at the sun. Loom uses AgX, a modern curve designed to behave like that.

Paint, ink and painter's shadows

Not every world should look like a photograph. Fauve is named after the painters who used colour wildly, and loom has a second set of tools for it.

Toon light blocks light the way a painter does instead of shading it smoothly: a lit side in the light's own warm colour, a shadow side in a cool complementary colour, never grey. A white wall's shadow is violet, a yellow wall's is orange-brown, a magenta one's purple. There's a hot line where light meets shade, and a rim of sky colour on edges turned away from you.

Ink lines come from a neat property of depth. In loom's reversed-Z depth buffer, any flat surface on screen has depth that changes in a perfectly straight line from pixel to pixel. So the change of the change, the second difference, is exactly zero on every face, whatever its angle, and spikes at creases and silhouettes. One test finds both kinds of edge.

Things built to break

Smithereens is a whole harbour city made to come down: towers 280 m tall, a bridge, a TV tower. Everything that breaks is made of cells (bricks, slabs, beams, panes), each a simple convex shape, held together by bonds where they touch.

When something hits a wall, the impact's energy (half its mass times its speed squared) spreads into the bonds and cells around it. Bonds snap. Cells that take too much shatter into fragments. To make the fragments, scatter some points through the cell and give each point all the space that's closer to it than to any other point. Those regions are Voronoi cells, and they look remarkably like real cracks. Click to break the slab:

Sound without a single recording

There are no audio files in these games. Every splash, footstep, engine, thunderclap, cricket and note of music is synthesised by code when the game loads, in a background thread.

Water is the best example. The sound of water isn't really the water: it's bubbles. A bubble born underwater rings like a tiny bell for a few milliseconds, at a pitch set by its size (Minnaert, 1933). Small bubbles ring high, big ones low. A drip is one bubble; a stream is thousands. Loom builds its water sounds from populations of them.

Take the thread

Weft and loom are open source and on npm. These games install them like anyone else would. If you'd like to see how a renderer really works, or build something where the frame is the point, they're yours to read, run and take apart.

# the kit
npm install @ericrius1/weft

# the renderer, if you want it
npm install @ericrius1/loom

// vite.config.ts
import { weft } from '@ericrius1/weft/vite';

export default defineConfig({
  plugins: [weft({ libs: { loom: '@ericrius1/loom' } })],
});

A word on its ancestry: much of loom's look (the atmosphere, the clouds' first generation, the film) was first built for Waterbending, which runs on its own engine, then ported onto weft so the other games could share it.

Further reading

• Sébastien Hillaire, A Scalable and Production Ready Sky and Atmosphere Rendering Technique, EGSR 2020
• Andrew Schneider, The Real-Time Volumetric Cloudscapes of Horizon Zero Dawn, SIGGRAPH 2015, and the Nubis talks after it
• Sébastien Hillaire, Physically Based Sky, Atmosphere and Cloud Rendering in Frostbite, SIGGRAPH 2016
• Magnus Wrenninge, Production Volume Rendering, SIGGRAPH 2017 course (multiple-scattering octaves)
• Christopher Kulla & Marcos Fajardo, Importance Sampling Techniques for Path Tracing in Participating Media, EGSR 2012
• Jorge Jimenez et al., Practical Real-Time Strategies for Accurate Indirect Occlusion (GTAO), SIGGRAPH 2016
• Yuriy O'Donnell, FrameGraph: Extensible Rendering Architecture in Frostbite, GDC 2017
• Christoph Schied et al., Spatiotemporal Variance-Guided Filtering (SVGF), HPG 2017
• Robert Ulichney, The void-and-cluster method for dither array generation, 1993 (blue noise)
• Kees van den Doel, Physically-based models for liquid sounds, ICAD 2004
• Troy Sobotka's AgX, and its many ports
• Erin Catto's box3d, and Isaac Mason's box3d.js
• Brendan Duncan's wgsl_reflect
• And three.js, which taught a generation of us 3D on the web