Write a module

Build the flow field example: 65 536 particles that drift through Perlin noise. You write the particles as a module, createFlowField, the way the kit writes its own. A module is a function, its factory, that borrows your root, allocates its GPU resources and returns methods that record work into passes you open. Your scene makes the module and records each frame. Modules is the one-page reference for what you write here.

The GPU runs the same small function for every particle at once. You write those functions in TypeScript, and TypeGPU turns them into shaders, the programs the GPU runs. Slime mould explains them at a slower pace.

Follow along

Work in the project from Getting started, and create each new file in src/, beside index.ts. The page reloads when you save. The finished files are in the example.

1. Put the particles in a buffer, and scatter them.

   A buffer is GPU memory that holds many values of one shape. Each Particle holds a position and the direction it last moved in. Positions are in clip space, where the canvas spans −1 to 1 on both axes.

   Create flow-field.ts. The factory takes the root and an options object, and allocates the buffer once, when the scene makes the module. Nothing allocates while a frame records.

   flow-field.ts

   import { owner, type SizeSource } from '@typegpu/kit';
   import { randf } from '@typegpu/noise';
   import { d, tgpu, type TgpuComputePass, type TgpuRoot } from 'typegpu';
   
   const WORKGROUP = 64;
   
   const Particle = d.struct({ position: d.vec2f, direction: d.vec2f });
   
   export interface FlowFieldOptions {
     readonly count: number;
     /** Seconds per `step`. */
     readonly step: number;
     readonly format: GPUTextureFormat;
     /** What the particles are drawn into, such as the canvas surface. */
     readonly size: SizeSource;
   }
   
   export function createFlowField(root: TgpuRoot, options: FlowFieldOptions) {
     const { count, step, format, size } = options;
     const own = owner('The flow field was destroyed.');
   
     const particles = own(root.createBuffer(d.arrayOf(Particle, count)).$usage('storage'));
     const writable = particles.as('mutable');
     const readable = particles.as('readonly');
   
   

   • size is anything with a width and height in pixels, such as the canvas surface. The module reads it when it draws.
   • owner collects what you pass through own and frees it all at destroy. Free the particle buffer with the module; the small uniforms below can wait for the garbage collector.
   • writable and readable are the same buffer, bound for writing in kernels and for reading in the vertex function. WebGPU forbids writable storage in a vertex function.

   A kernel is a compute function the GPU runs many times at once. Each run is a thread, numbered by gid.x from 0, and thread n places particle n. Threads start in workgroups of 64, so dispatch enough workgroups to cover every particle. The last workgroup can run past the end of the buffer, and the bounds check stops those threads:

   particles

   21

   workgroup size4816

   Change the particle count to see dispatch round up to whole workgroups of 64 threads. The bounds check if (gid.x >= count) return stops extra threads before buffer access.

   Add the seed kernel and return the module’s first recording method:

   flow-field.ts

   /** A random position across the canvas, in clip space. */
   const spawn = () => {
     'use gpu';
     return d.vec2f(randf.sample(), randf.sample()) * 2 - 1;
   };
   
     // Inside createFlowField
     const seedValue = root.createUniform(d.f32);
     const workgroups = Math.ceil(count / WORKGROUP);
   
     const seedKernel = tgpu.computeFn({
       workgroupSize: [WORKGROUP],
       in: { gid: d.builtin.globalInvocationId },
     })(({ gid }) => {
       'use gpu';
       if (gid.x >= count) return;
   
       randf.seed2(d.vec2f(d.f32(gid.x), seedValue.$));
       writable.$[gid.x] = Particle({ position: spawn(), direction: d.vec2f() });
     });
   
     const seedPipeline = root.createComputePipeline({ compute: seedKernel });
   
     return {
       seed(pass: TgpuComputePass) {
         own.usable();
         seedValue.write(Math.random());
         pass.setPipeline(seedPipeline);
         pass.dispatchWorkgroups(workgroups);
       },
   
       destroy: own.destroy,
       [Symbol.dispose]: own.destroy,
     };
   }

   • randf from @typegpu/noise gives each thread its own random numbers once you seed it. Seed it with the thread number and a value the CPU picks, so every reseed scatters the particles differently.
   • seedValue is a uniform, a small value the CPU writes and every thread reads.
   • seed takes a compute pass that the caller opens, so a scene can record several modules into one pass. It records a dispatch and returns; the scene submits the frame.
   • own.usable() throws the owner’s message once the module is destroyed, so a stale scene fails with a clear error rather than binding a freed buffer. destroy and [Symbol.dispose] are the same function, so using frees the module at the end of a block.

   Nothing draws yet. The scene uses the module in step 3.

2. Draw them.

   A draw runs two functions. The vertex function places the corners of shapes on the screen, and the fragment function colours each pixel they cover. Draw each particle as a small square of four corners, one instance per particle.

   The square’s size is in pixels, so the vertex function needs the canvas size, and the point size is a setting the reader can change. Put the settings in a struct uniform at module scope, so other code can name its type, and the canvas size in a uniform of its own:

   flow-field.ts

   export const FlowSettings = d.struct({
     /** Clip-space units per second. */
     speed: d.f32,
     /** Noise cells across the height. */
     scale: d.f32,
     /** Particle diameter in pixels. */
     pointSize: d.f32,
   });
   
   export const defaults: d.Infer<typeof FlowSettings> = { speed: 0.2, scale: 1.5, pointSize: 2 };
   
     // In FlowFieldOptions
     /** Initial values for speed, scale and point size. Override `defaults`. */
     readonly settings?: Partial<d.InferInput<typeof FlowSettings>>;
   
     // Inside createFlowField
     const settings = root.createUniform(FlowSettings, { ...defaults, ...options.settings });
     const viewport = root.createUniform(d.vec2f, d.vec2f(size.width, size.height));
   
   

   speed and scale steer the particles from step 4. Below the uniforms, write the two functions. The vertex function runs four times per particle. It reads the particle at instanceIndex, turns vertexIndex into a corner of the square and colours the particle by its direction. The fragment function fades the square into a soft dot:

   flow-field.ts

   const vertex = tgpu.vertexFn({
     in: { vertexIndex: d.builtin.vertexIndex, instanceIndex: d.builtin.instanceIndex },
     out: { position: d.builtin.position, color: d.vec3f, corner: d.vec2f },
   })(({ vertexIndex, instanceIndex }) => {
     'use gpu';
     const particle = readable.$[instanceIndex];
   
     const corner = d.vec2f(d.f32(vertexIndex & 1), d.f32(vertexIndex >>> 1)) * 2 - 1;
     const extent = (corner * settings.$.pointSize) / viewport.$;
     const center = particle.position;
   
     return {
       position: d.vec4f(center + extent, 0, 1),
       color: d.vec3f(particle.direction * 0.5 + 0.5, 0.9),
       corner,
     };
   });
   
   const fragment = tgpu.fragmentFn({
     in: { color: d.vec3f, corner: d.vec2f },
     out: d.vec4f,
   })(({ color, corner }) => {
     'use gpu';
     const falloff = 1 - std.smoothstep(0.4, 1, std.length(corner));
   
     return d.vec4f(color * (falloff * 0.5), falloff);
   });

   Make the render pipeline with additive blending, so dots that overlap brighten. Return draw, which takes a render pass, and initAsync. Import pipelines from @typegpu/kit and the type TgpuRenderCommands from typegpu:

   flow-field.ts

   const drawPipeline = root.createRenderPipeline({
     vertex,
     fragment,
     targets: { format, blend: pipelines.blend.add },
     primitive: { topology: 'triangle-strip' },
   });
   
   let width = size.width;
   let height = size.height;
   
   return {
     settings,
   
     async initAsync() {
       await Promise.all([seedPipeline.initAsync(), drawPipeline.initAsync()]);
     },
   
     draw(pass: TgpuRenderCommands) {
       own.usable();
       if (size.width !== width || size.height !== height) {
         width = size.width;
         height = size.height;
         viewport.write(d.vec2f(width, height));
       }
   
       pass.setPipeline(drawPipeline);
       pass.draw(4, count);
     },
     // seed, destroy and [Symbol.dispose] from step 1
   };

   • A triangle strip of four corners makes the square from two triangles. draw(4, count) draws it once for every particle.
   • draw writes viewport only when the canvas size changes. It compares against the size it last wrote, so a steady frame uploads nothing.
   • initAsync compiles the pipelines ahead of the first frame. Without it, each pipeline compiles when it first records, and that frame stalls.
   • settings is returned so the scene can write it when a setting changes, in step 6.

3. Run the module in your scene.

   Replace scene.ts from Getting started. The scene makes the field and waits for its pipelines. Each frame records into an encoder, a list of GPU commands that the loop submits when frame returns. Commands come in passes: a compute pass for the seed, then a render pass that clears the canvas and draws:

   scene.ts

   import { owner, type Frame, type Surface } from '@typegpu/kit';
   import type { TgpuRoot } from 'typegpu';
   import { createFlowField } from './flow-field.ts';
   
   export async function createScene(root: TgpuRoot, surface: Surface) {
     const own = owner();
     const field = own(
       createFlowField(root, {
         count: 65_536,
         step: 1 / 60,
         format: surface.format,
         size: surface,
       }),
     );
     await field.initAsync();
     let seeding = true;
   
     return {
       frame(frame: Frame) {
         const compute = frame.encoder.beginComputePass();
         if (seeding) field.seed(compute);
         seeding = false;
         compute.end();
   
         const pass = frame.encoder.beginRenderPass({
           colorAttachments: { view: surface.view(frame), clearValue: [0.01, 0.015, 0.03, 1] },
         });
         field.draw(pass);
         pass.end();
       },
   
       destroy: own.destroy,
     };
   }

   The scene owns the field, so it passes it through an owner of its own and returns that owner’s destroy. The host calls it when the scene closes. The root and surface are borrowed from the host, so the scene leaves them alone. The seed and the draw go into one encoder, so the GPU scatters the particles before it draws them.

   The particles appear, scattered and still:

   flow-field65 536 particles, each steered by the Perlin noise under it.

   PauseOpen the full example

   Reseed to scatter the particles again. The simulation is paused, as yours is until step 4.

4. Move them through noise.

   Each step, every particle samples Perlin noise at its position, turns the value into an angle and moves that way. Nearby positions get similar angles, so the particles flow in smooth streams. Import perlin2d from @typegpu/noise and std from typegpu, and add the step kernel:

   flow-field.ts

   const TAU = Math.PI * 2;
   /** Chance per step of respawning a particle elsewhere. Prevents particles collecting in sinks. */
   const RESPAWN = 1 / 240;
   
   // Inside createFlowField
   const stepKernel = tgpu.computeFn({
     workgroupSize: [WORKGROUP],
     in: { gid: d.builtin.globalInvocationId },
   })(({ gid }) => {
     'use gpu';
     if (gid.x >= count) return;
     const particle = writable.$[gid.x];
   
     const aspect = viewport.$.x / viewport.$.y;
     const sample = particle.position * d.vec2f(aspect, 1) * settings.$.scale;
     const angle = perlin2d.sample(sample) * TAU;
     const direction = d.vec2f(std.cos(angle), std.sin(angle));
   
     let position = particle.position + direction * (settings.$.speed * step);
   
     randf.seed3(d.vec3f(position, d.f32(gid.x)));
     if (randf.sample() < RESPAWN || std.any(std.gt(std.abs(position), d.vec2f(1)))) {
       position = spawn();
     }
   
     writable.$[gid.x] = Particle({ position, direction });
   });
   const stepPipeline = root.createComputePipeline({ compute: stepKernel });

   • The sample position is stretched by the canvas’s aspect ratio, so the noise’s cells stay square on a wide canvas.
   • step is a constant from the options. The kernel captures it, so no frame uploads the step length.
   • A few particles respawn at random each step, and every particle that leaves the canvas does. Without that, particles would gather where the streams meet and leave the rest of the canvas empty.

   Return step beside seed, recording one fixed step into the caller’s compute pass, and compile its pipeline in initAsync:

   flow-field.ts

     async initAsync() {
       await Promise.all([
         seedPipeline.initAsync(),
         stepPipeline.initAsync(),
         drawPipeline.initAsync(),
       ]);
     },
   
     step(pass: TgpuComputePass) {
       own.usable();
       pass.setPipeline(stepPipeline);
       pass.dispatchWorkgroups(workgroups);
     },
   
   

   Stepping once per frame would move the particles twice as fast at 120 Hz as at 60 Hz. A fixed step counts how many 1/60 s steps fit in the time since the last frame and carries the rest into the next:

   PauseStall 150 ms

   display30 fps60 fps144 fps

   step30 Hz60 Hz120 Hz

   maxSteps

   4

   Stall a frame or change the display rate. Step length stays fixed; catch-up frames run at most maxSteps and drop time beyond the cap, shown at one fifth speed.

   In scene.ts, import clock from @typegpu/kit, make the fixed step, and step the field after the seed:

   scene.ts

   // In createScene
   const sim = clock.fixedStep({ step: 1 / 60 });
   const field = own(
     createFlowField(root, {
       count: 65_536,
       step: sim.step,
       format: surface.format,
       size: surface,
     }),
   );
   
   // In frame, after the seed
   for (let steps = sim.advance(frame.dt); steps > 0; steps--) {
     field.step(compute);
   }

   The particles stream across the canvas. At 30 frames a second, each frame runs two steps in its one compute pass; at 120, half the frames run none.

5. Move on every frame.

   On a display faster than 60 Hz, the particles hold still on the frames that run no step, then jump a whole step, so they stutter. sim.ahead is the time since the last step, in seconds. Draw each particle that far along its direction, and it moves on every frame while the simulation still steps 60 times a second:

   Pause

   Change the display rate. Ticks mark the particle after each 60 Hz step and rings mark where the last frames drew it, at one sixth speed. Drawn at its last step, the particle holds still for several frames, stacked here; drawn sim.ahead seconds along, it moves on every frame.

   ahead changes every frame, so it gets a uniform of its own, which the scene owns and writes. The module reads it through an accessor, a value its shader reads whose source the pipeline decides. Filled with the scene’s uniform, the shader reads the uniform; without one, it reads 0. Import the type TgpuUniform from typegpu:

   flow-field.ts

   // @filename: ../../packages/typegpu-kit-examples/src/flow-field/flow-field-tutorial-7.ts
   import { pipelines } from '@typegpu/kit';
   import { d, tgpu, type TgpuRoot, type TgpuUniform } from 'typegpu';
   declare const root: TgpuRoot, format: GPUTextureFormat;
   const Particle = d.struct({ position: d.vec2f, direction: d.vec2f });
   const FlowSettings = d.struct({ speed: d.f32, scale: d.f32, pointSize: d.f32 });
   const readable = root.createBuffer(d.arrayOf(Particle, 4)).$usage('storage').as('readonly');
   const settings = root.createUniform(FlowSettings);
     // In FlowFieldOptions
     /**
      * Seconds since the last fixed step, written from `sim.ahead` each frame. Particles are drawn
      * that far along their direction, so they move at the display rate. Default 0.
      */
     readonly ahead?: TgpuUniform<d.F32>;
   
   // Inside createFlowField
   const ahead = tgpu.accessor(d.f32);
   
     // In vertex, in place of the center at the particle's position
     const center = particle.position + particle.direction * (settings.$.speed * ahead.$);
   
   // In place of root.createRenderPipeline
   const drawPipeline = root.with(ahead, options.ahead ?? 0).createRenderPipeline({
     // ...the same description as before
   });

   In scene.ts, import d from typegpu, make the uniform, hand it to the field and write it after the steps:

   scene.ts

   // In createScene
   const ahead = root.createUniform(d.f32);
   const field = own(
     createFlowField(root, {
       count: 65_536,
       step: sim.step,
       ahead,
       format: surface.format,
       size: surface,
     }),
   );
   
   // In frame, after the steps
   ahead.write(sim.ahead);

   On a 120 Hz or faster display, the particles now move smoothly on every frame.

6. Change the settings.

   Writing a uniform uploads all of it, so group values by how often they change. The field has four:

   Uniform	Holds	Written
   settings	speed, scale, point size	by the scene, when a setting changes
   viewport	the canvas size	by draw, when the canvas size changes
   ahead	the time since a step	by the scene, once a frame
   seedValue	the random seed	by seed

   A steady frame uploads 4 bytes, the ahead value. Data on the GPU has the rule for every module. Keep the settings in a plain object, hand it to the field as its starting values, and return them with a write that uploads them, and a reseed. Import defaults from ./flow-field.ts:

   scene.ts

   // In createScene
   const settings = { ...defaults };
   const field = own(
     createFlowField(root, {
       count: 65_536,
       step: sim.step,
       ahead,
       format: surface.format,
       size: surface,
       settings,
     }),
   );
   
   // In the returned object
     sim,
     settings,
     write: () => field.settings.write(settings),
     reseed: () => {
       seeding = true;
     },
   
   

   The page decides how to show the settings. Add lil-gui to the project:

   npm

   npm i lil-gui

   pnpm

   pnpm add lil-gui

   yarn

   yarn add lil-gui

   bun

   bun add lil-gui

   In index.ts, build the panel in attach, which web.host calls once the scene is made. The host disposes what attach returns when it tears the scene down:

   index.ts

   import * as web from '@typegpu/kit/web';
   import GUI from 'lil-gui';
   import { createScene } from './scene.ts';
   
   web.host(createScene, {
     canvas: document.querySelector('canvas')!,
     attach({ scene }) {
       const gui = new GUI({ title: 'flow field' });
       gui.add(scene.settings, 'speed', 0, 1, 0.01);
       gui.add(scene.settings, 'scale', 0.1, 6, 0.1);
       gui.add(scene.settings, 'pointSize', 0.5, 8, 0.5);
       gui.onChange(scene.write);
       gui.add(scene.sim, 'paused');
       gui.add(scene, 'reseed');
       return { [Symbol.dispose]: () => gui.destroy() };
     },
   });

   The panel changes the field as you drag. Pausing stops the steps and holds the particles still. The figure has the same controls, and its settings writes readout counts uploads of settings. It rises only when you change a setting:

   flow-field65 536 particles, each steered by the Perlin noise under it.

   PauseOpen the full example

   Change the speed or point size to add one uniform write. Reseeding and waiting leave the count unchanged.

7. Test the module.

   A test of the module checks what it records, without a GPU. recordingRoot() from @typegpu/kit/testing is a root on a stand-in device that logs commands and writes, and offscreenSurface stands in for the canvas. Add Vitest, which reads vite.config.ts, so the TypeGPU plugin transforms your module in tests too:

   npm

   npm i -D vitest

   pnpm

   pnpm add -D vitest

   yarn

   yarn add -D vitest

   bun

   bun add -d vitest

   Create flow-field.test.ts beside the module. Make the field on a recording root and record frames as a scene would:

   flow-field.test.ts

   import { frames } from '@typegpu/kit';
   import { offscreenSurface, recordingRoot } from '@typegpu/kit/testing';
   import { expect, it } from 'vitest';
   import { createFlowField } from './flow-field.ts';
   
   it('records into the passes it is given, and a steady frame writes and creates nothing', async () => {
     const { root, log } = recordingRoot();
     const surface = offscreenSurface(root, { width: 64, height: 36, format: 'bgra8unorm' });
     const field = createFlowField(root, {
       count: 1000,
       step: 1 / 60,
       format: surface.format,
       size: surface,
     });
     await field.initAsync();
     expect(log.pipelines).toBe(3);
   
     let seeding = true;
     const loop = frames.create(root, (frame) => {
       const compute = frame.encoder.beginComputePass();
       if (seeding) field.seed(compute);
       seeding = false;
       field.step(compute);
       compute.end();
       const pass = frame.encoder.beginRenderPass({
         colorAttachments: { view: surface.view(frame) },
       });
       field.draw(pass);
       pass.end();
     });
   
   

   initAsync compiled all three pipelines, so none compiles during a frame. Run two frames, which seed and make TypeGPU’s first-use objects, then check a third:

   flow-field.test.ts

     // In the test, after the loop
     loop.run(0);
     loop.run(1 / 60);
     const counts = log.counts();
     log.events.length = 0;
     log.writes.length = 0;
   
     loop.run(2 / 60);
     expect(log.events).toEqual([
       'begin-compute',
       'dispatch',
       'end-compute',
       'begin-render',
       'draw',
       'end-render',
       'submit',
     ]);
     expect(log.writes).toEqual([]);
     expect(log.counts()).toEqual(counts);
   
     surface.setSize({ width: 128, height: 72 });
     loop.run(3 / 60);
     expect(log.writes.map((write) => write.size)).toEqual([8]); // the viewport
   
     field.destroy();
     expect(() => loop.run(4 / 60)).toThrow('The flow field was destroyed.');
   
   

   • The steady frame records one step and one draw into the passes it was given, submits once, writes nothing and creates no GPU object. Without a scene, nothing writes ahead.
   • A new canvas size writes the 8 bytes of viewport, once.
   • After destroy, recording throws the owner’s message.

   Run pnpm vitest. Testing covers the rest of the log, and how to compile the WGSL on a real GPU.

What you wrote

• Directorysrc/

  • index.ts the page: web.host and the settings panel
  • scene.ts createScene(root, surface) with the field, the fixed step and the frame
  • flow-field.ts the module
  • flow-field.test.ts its test on a recording root

Next

• Let the field drift over time. Sample perlin3d with the elapsed time as the third coordinate in place of perlin2d, from a uniform the scene writes once a step.
• Add finer eddies. Sample the noise again at twice the scale and add half of it to the angle.
• Give Particle an age, count it up in the step kernel and fade each particle in after it respawns.
• Package the module as the kit does, as Modules describes.