Modules

Every module has a factory, create(root, options), that allocates resources and returns them with shader functions and recording methods. How the kit works introduces the rules modules follow. This page covers the details you rely on when using or writing one.

Lifecycle

Follow resources from creation to teardown. The first use creates GPU buffers and bind groups; later frames allocate nothing, destroy() frees four buffers, pipelines and groups release when unreferenced, and the borrowed surface remains.

• initAsync() compiles every pipeline. It is optional; without it the first recording compiles, which stalls that frame and is slow on WebKit.
• A few setup calls submit, marked submits setup on their card: meshPool.add(shape) and meshes.bake given no encoder or pass. Call them while loading, or pass the frame’s encoder where supported.
• destroy() frees the resources listed under owns on the card. It leaves borrowed resources alive. Calling it twice is safe. [Symbol.dispose] is the same function, so using destroys a module at the end of its block on the web. The card’s lifecycle shows whether a module has destroy(). A drawing built by a description has its own drawn.destroy().
• After destroy(), a method that would put a destroyed resource into GPU work throws an error that names the module, such as “The live lists were destroyed.” That covers inject(), recording methods (compact, sort, pick), writes (a camera’s write) and getters that hand out GPU objects (a target set’s views, a surface’s view). A table throws on every use.
• Methods that only read CPU state or perform optional work return without an error. frames.run returns false, capture records nothing, take and latest return undefined, and a camera’s update writes nothing. A loop that ticks once more after its scene is torn down ends without an error.

Freeing what a scene made

The garbage collector frees what a dropped scene made. On a device that outlives the scene, such as one a gallery shares, destroy frees the large things sooner: targets that follow the screen, large buffers, models and the modules the scene made. Leave small uniforms, samplers, bind groups and pass descriptions to the collector. owner() collects each thing as you make it, so destroy needn’t list them again:

import { owner } from '@typegpu/kit';

const own = owner();
const view = cameras.orbit(root, { size: surface, target: [0, 0.4, 0], distance: 5 });
const canvas = passes.create(root, surface).pipe(view.inject());
const time = root.createUniform(d.f32);
const sparks = own(particles.create(root, view, { capacity: 2048, step: sim.step, blend: 'add' }));
const drawn = [canvas.add(sparks.drawing)];

const scene = {
  view,
  frame(frame: Frame) {
    time.write(frame.time);
    view.update(frame.dt);
    canvas.record(frame, drawn);
  },
  destroy: own.destroy,
};

• own(thing) returns thing. It takes anything with destroy(), and a fixed resource such as a uniform, which it frees through its buffer. It passes undefined through, for a part you make only with a setting on.
• own(() => …) runs the function at destroy. Take a texture that a resize replaces this way, as one function that frees the current texture, rather than each texture as it is made.
• destroy frees the last thing first, so a module goes before the ones it borrows. Calling it twice is safe.
• Something taken after destroy is freed at once, such as a model that finishes loading after the scene closed.
• Leave out what the scene borrows: the root, the surface and the host’s resources.

Recording methods

A method takes the smallest piece of the frame it needs, so the call site shows the pass structure.

Method	Takes	When
step(pass)	TgpuComputePass	compute dispatches, in a pass you share between modules
draw(pass)	TgpuRenderCommands	draws into your attachments, or into a render bundle you replay
record(encoder)	TgpuCommandEncoder	passes of its own, such as a shadow map or a post-processing chain
record(frame)	Frame	passes of its own that draw into a surface, whose view belongs to the frame
capture(frame)	Frame	work after the submit too, through frame.afterSubmit

const compute = encoder.beginComputePass();
particles.step(compute);
wind.step(compute);
compute.end();

light.shadow.record(encoder, casters); // opens and ends its own depth pass

const pass = scene.begin(frame);
terrain.draw(pass); // what scene.add(drawing) built
embers.draw(pass);
pass.end();

• A renderer returns a drawing. A description of passes builds it with scene.add(drawing), which returns a handle with draw(pass).
• step runs one fixed step and can run several times in a pass. Compute work that runs once per frame has a specific name, such as live lists’ compact or the particles’ spawn.

Bind a pipeline’s groups at setup, then set it on the pass and draw through the pass. Each .with(...) returns another object, and a draw through a different object from the previous draw’s sets the pipeline, groups and buffers again:

pipeline.with(group).with(pass).draw(3); // in the frame: a new object and all state on every draw

const bound = pipeline.with(group); // at setup
pass.setPipeline(bound); // in the frame
pass.draw(3); // a later draw with the same pipeline sets nothing

• A pass.setBindGroup or setVertexBuffer between draws makes the next draw set everything again.
• A group that follows a replaced texture comes from memo, and the pipeline bound to it can too, as finish’s is.
• A module sets only its pipeline on the caller’s pass. It makes no other state changes such as pass.setBindGroup there, because later draws would inherit them. Your frame code can make those changes.

draw takes a render pass or a render bundle encoder. pass.executeBundles([bundle]) replays the recorded draws in one call, which saves per-draw JS work on Hermes:

const bundler = root['~unstable'].createRenderBundleEncoder({
  colorFormats: [format],
  depthStencilFormat: 'depth24plus',
});
terrain.draw(bundler);
props.draw(bundler);
const bundle = bundler.finish();

// each frame
pass.executeBundles([bundle]);
embers.draw(pass);

• A bundle replays fixed draw calls while buffer contents can change. Record it again when the draw calls or resources change. Instances need this when a mesh gets its first instance or its textures arrive. Finish needs it when bloom replaces its output.
• A method that sets a viewport or a scissor can’t go in a bundle. It takes a pass, or the encoder and opens its own passes, as bloom’s record does.

An open pass

Don’t call a method that takes the encoder or the frame while a pass is open. WebGPU rejects commands on an encoder whose pass is still open:

const pass = encoder.beginRenderPass({
  colorAttachments: { view: surface.view(frame) },
});
terrain.draw(pass);
glow.record(encoder); // the render pass is still open
pass.end();

Writing a module

This module damps a buffer of velocities. Its rate is a setting; its step length is fixed at creation:

import { owner } from '@typegpu/kit';
import { d, std, tgpu, type TgpuComputePass, type TgpuRoot } from 'typegpu';

const DampingSettings = d.struct({ rate: d.f32 }); // no root needed

interface DampingOptions {
  readonly count: number;
  /** Seconds per `step`. */
  readonly step: number;
}

export function createDamping(root: TgpuRoot, options: DampingOptions) {
  const { count, step } = options;
  const own = owner('The damping was destroyed.');
  const settings = own(root.createUniform(DampingSettings, { rate: 2 }));
  const velocities = own(root.createMutable(d.arrayOf(d.vec2f, count)));

  const kernel = tgpu.computeFn({
    workgroupSize: [64],
    in: { gid: d.builtin.globalInvocationId },
  })(({ gid }) => {
    'use gpu';
    if (gid.x >= count) return;
    const decay = std.exp(-settings.$.rate * step);
    velocities.$[gid.x] *= decay;
  });
  const pipeline = root.createComputePipeline({ compute: kernel });

  return {
    settings,
    velocities,
    initAsync: () => pipeline.initAsync(),
    step(pass: TgpuComputePass) {
      own.usable();
      pass.setPipeline(pipeline);
      pass.dispatchWorkgroups(Math.ceil(count / 64));
    },
    destroy: own.destroy,
    [Symbol.dispose]: own.destroy,
  };
}

export type Damping = ReturnType<typeof createDamping>;

• Schemas and shader functions that capture no instance’s resources live at module scope.
• The kit’s owner takes each resource as it is made and frees them all once at destroy. Its usable() throws its message after destruction, so calling it in step keeps a dispatch from binding destroyed buffers.
• Validation and allocation happen in the factory; recording methods only record.
• A test builds it on recordingRoot and checks what it records.

Pitfalls

• d.struct rejects WGSL’s reserved words as field names, such as type and target.
• unplugin-typegpu doesn’t transform a 'use gpu' object shorthand method, { alive(i) { 'use gpu'; … } }. Write it as a property: alive: (i) => { 'use gpu'; … }.
• Shift a u32 right with >>>: d.u32(0x32) >>> corner. TypeGPU warns about >> on a u32, and a bare literal on the left of a shift is an i32.
• Code that runs on React Native follows the platform rules, such as copying an array before sorting it.

Error	Cause
Missing value for 'slot:weather'	a pipeline reads an accessor nothing filled; create it from root.pipe(weather.inject())
Nothing filled `cameras.current`: …	the same, for an accessor whose default is unfilled; it names the inject()
Missing bind groups for layouts	a pipeline reads a shared layout, and the pass has no group set for it
readonly buffers cannot be mutated	a render pipeline writes a buffer it binds read-only, such as a table’s device rows
bindGroupLayoutCount (5) is larger than the maximum allowed (4)	the pipeline uses more bind groups than the device allows; a census counts them
The damping was destroyed.	a call after destroy()
Found duplicate TypeGPU version	two copies of TypeGPU loaded; see Setting up a project

Write a module builds a module step by step, from its first kernel to its test.

In a package

A package exports each module as a namespace. The module’s file calls its factory create and its options Options, and the package entry re-exports the file:

index.ts

// damping.ts: export function create(…), export interface Options, export type Damping
export * as damping from './damping.ts';
export type { Damping } from './damping.ts';

Call damping.create(root, options) and name the result for what it holds, as in const drag = damping.create(...). frames.create and bloom.create follow the same convention. A module in your own program can stay a plain createDamping.