Tables

PauseHit rows 1 and 6

Hit rows 1 and 6 while a kernel moves every row. The flush uploads host rows between the two tints; storing x in the same struct overwrites GPU motion with stale CPU values.

A game may keep enemies, pickups, lights or fish in a GPU buffer. If the CPU and kernels write the same fields, a stale CPU copy can overwrite a kernel’s update, such as the start of a death animation.

A table separates CPU-owned host fields from GPU-owned device fields in different buffers. Uploading host rows preserves the device fields that kernels wrote.

import { frames, table } from '@typegpu/kit';

const Enemy = table.define('Enemy', {
  host: { species: d.u32, tint: d.vec4f, radius: d.f32 }, // written by the CPU
  device: { position: d.vec3f, velocity: d.vec3f, health: d.f32 }, // by kernels
});

const enemies = table.create(root, Enemy, {
  capacity: 4096,
  defaults: { tint: [1, 1, 1, 1], radius: 0.5, health: 10 },
});

const id = enemies.add({ species: 2, position: [4, 0, 1] });
enemies.fields.tint.set(id, 1, 0, 0, 1);

frames.create(root, (frame) => {
  enemies.flush(); // uploads what changed, before any pass reads the table
  // ... passes
});

enemies.remove(id);

• table.define takes no root, so it lives at module scope beside its shaders. Its name brands the ids and names the WGSL (EnemyHost, Enemy_position); nothing looks it up.
• Either part may be omitted. A host-only table holds instance data, such as Blockfall’s blocks. A field in both parts is a type error, and define throws for it and for f16 and bool fields.
• The capacity is fixed, at most 2^20, and add throws when the table is full. Fields start at defaults, or zero, and add() with no values allocates nothing. count is the live rows; clear() removes them all.
• The types take the definition: table.Table<typeof Enemy>, table.Options, table.Fields.
• enemies.buffers holds the host, device and live buffers and the index uniform (the span and the id mask), for a readback or a bind group of your own.
• table.rows(Enemy, 'device', capacity) gives a part’s array schema, for a buffer or history of your own. It throws for a capacity a table can’t have, or a part with no fields.

Row ids

add returns a row id, a u32 containing the slot and generation with the type RowId<'Enemy'>. A plain number or another definition’s id is a type error.

• remove(id) bumps the slot’s generation; a field handle given the stale id throws, and has(id) checks first. idAt(slot) turns a slot read back from the GPU into an id.
• Ids belong to the definition. Another table of Enemy accepts the same id if its slot has the same generation. Keep each table’s ids separate.
• Generations start at 1, so a zeroed u32 is never a live id.

The capacity determines how many bits the slot needs. The generation uses the remaining bits. Once a slot’s generation wraps, an old id is valid again. A bullet spawned and freed every frame takes the same slot every frame, so at 120 fps it wraps after:

Capacity	Generation bits	Wraps after
8	29	52 days
300	23	19 hours
4096	20	2.4 hours
2^20	12	34 seconds

Writing fields

enemies.fields has a handle per field, which writes the CPU copy at a fixed offset:

const tint = enemies.fields.tint; // keep it outside the loop

for (const id of hit) tint.set(id, 1, 0, 0, 1); // components: nothing allocated

tint.write(id, [1, 0, 0, 1]); // allocates the tuple
tint.get(id, d.vec4f()); // host fields read back from the CPU copy
enemies.write(id, { tint: [1, 0, 0, 1], health: 10 }); // several fields, both parts

• A vector field’s write and get also take any array of numbers, such as a Float32Array from a math library. write reads its first components.
• Matrices, arrays and nested structs have only write. A matrix may be a Float32Array in its padded layout.
• Device fields have no get. A device write sets an absolute value before the frame’s GPU work, for a teleport or a revive. Apply relative changes, such as damage, with a command.

Uploading changes

AddRemoveFlush

Click cells, add or remove rows, then flush. Outlines mark changed fields, and the highlight marks uploaded cells.

Nothing reaches the GPU until flush(). Call it once per frame, before any pass that reads the table. Without history it needs no encoder, because queue.writeBuffer runs before the next submit. It uploads:

• written host rows in runs, bridging gaps of fewer than 16 unwritten rows from the CPU copy;
• each written device row, from its first written field to its last;
• new rows’ device values, whole;
• adjacent device rows whose uploads meet, such as new rows and rows written from their first field to their last, as one run;
• the live bits, and the span when it changed.

Last frame’s rows

A drawing’s motion output runs its vertex code a second time, compiled with history.previously. To give rows that move a motion of their own, create the table with history: true. That code then reads last frame’s rows:

const enemies = table.create(root, Enemy, { capacity: 4096, history: true });

frames.create(root, (frame) => {
  enemies.flush(frame.encoder); // copies last frame's rows aside, then lands the uploads
  // ... kernels that move them, passes that draw them
});

• The table is a HistoryTable, whose flush takes the frame’s encoder. Held as a plain Table, it throws without one. A row added this frame starts last frame where it is, so it doesn’t streak in from the origin.
• Kernels and render pipelines read and write the current rows, as without history. Only code compiled with previously reads last frame’s.
• Last frame’s rows follow the current ones in the same buffer, from slot capacity, so reading them binds no more buffers. Read rows through the getters, such as Enemy.position(i): Enemy.device.$[i] always reads the current rows.
• Each flush copies the device rows across the span. It copies host rows only in the frame after an upload changed them.
• A write that jumps a row, such as a teleport, reads as motion for a frame.

Removing rows

Slots never move. An id stays valid until its row is removed, and other buffers can refer to rows by slot. The span is the highest live slot plus one. add takes the lowest free slot to keep the span short. Kernels skip dead rows but still read memory across the span. A span with half its rows dead at random costs about twice as much as dense rows.

Play wavesAdd 6Remove 6Reset

Play matching additions and removals in the table and a last-freed-first list. Kernels visit the full span, so a larger live fraction means less wasted work.

Drawing rows

A dead instance costs as much vertex work as a live one, so don’t draw over the span. Live lists list each group’s live slots on the GPU every frame. They draw them indirectly at the cost of dense rows.

Live lists group rows by a field, such as species: d.u32. Groups share one capacity in any mix; rows with different fields belong in different tables.

To light and draw meshes, use a set of instances. A set is a table whose add takes a mesh, and its renderer draws the live rows of each mesh.

Rows in shaders

Shaders use the definition’s field getters, row(i), alive(i), span() and slotOf(id). The pipeline’s fills choose the table, here through root.pipe(enemies.inject()).pipe(live.inject()):

// A helper that takes a whole row: the dead sink into the floor
const sinkOf = (enemy: RowOf<typeof Enemy>) => {
  'use gpu';
  return std.select(d.f32(0), enemy.radius * 2, enemy.health <= 0);
};

const vertex = tgpu.vertexFn({
  in: { vertexIndex: d.builtin.vertexIndex, instanceIndex: d.builtin.instanceIndex },
  out: { position: d.builtin.position },
})(({ vertexIndex, instanceIndex }) => {
  'use gpu';
  const slot = live.slot(SKELETON, instanceIndex);
  const center = Enemy.position(slot); // loads one field
  const enemy = Enemy.row(slot); // the whole row

  const corner = cube.vertexAt(vertexIndex).position * enemy.radius;
  const world = center + corner - d.vec3f(0, sinkOf(enemy), 0);

  return { position: viewProjection.$ * d.vec4f(world, 1) };
});

• Without enemies.inject(), the pipeline fails at first use or in initAsync with an error that names the accessor and the inject() it needs, such as Nothing filled `Enemy_host`: ….
• Prefer getters to row(i) in hot code. row(i) copies every field, and some compilers keep loads the shader doesn’t use.
• host, device, row, alive, span and slotOf are taken; a field can’t use them.
• One pipeline reads one table of a definition. To read two, such as a player and its enemies, define a second.

Writing device fields

A kernel writes through a reference from Enemy.device, and reads through the getters:

const STEP = 1 / 60;

const crowd = tgpu.computeFn({
  workgroupSize: [64],
  in: { gid: d.builtin.globalInvocationId },
})(({ gid }) => {
  'use gpu';
  const i = gid.x;
  if (!Enemy.alive(i)) return; // also false past the span

  const speed = 2 / Enemy.radius(i); // a host field: small enemies are fast
  const enemy = Enemy.device.$[i]; // a reference: writes go to the buffer

  enemy.velocity = std.mix(enemy.velocity, toPlayer(enemy.position) * speed, 0.1);
  enemy.position += enemy.velocity * STEP;
});

Device rows bind read-write in compute pipelines and read-only in render pipelines. WebGPU forbids read-write storage in vertex stages. Writing device rows in a render pipeline fails with readonly buffers cannot be mutated. Host rows are read-only everywhere.

Reading neighbours while writing them

A boid kernel reads neighbours while other threads move them. Some neighbours may have moved this step and others may not. First copy the fields neighbours need in a separate dispatch. Have the steering kernel read only that copy:

/** A fish as its neighbours see it. */
const Seen = d.struct({ position: d.vec3f, velocity: d.vec3f });
const seen = root.createMutable(d.arrayOf(Seen, 4096));

const snapshot = tgpu.computeFn({
  workgroupSize: [64],
  in: { gid: d.builtin.globalInvocationId },
})(({ gid }) => {
  'use gpu';
  const i = gid.x;
  if (!Fish.alive(i)) return;

  seen.$[i] = Seen({ position: Fish.position(i), velocity: Fish.velocity(i) });
});
// the steering kernel reads seen.$[k] and writes only Fish.device.$[i]

• Two dispatches in one compute pass run in order, so the copy is whole before steering starts.
• The copy holds only what neighbours read. In the fish tank, the neighbour grid’s sort writes it, in sorted order.

Modules that read a table

A module that reads rows takes getters in its options. Pipe the table’s inject() into each getter. The module receives no table handle, and its factory defines shaders that call those getters:

interface TrailsOptions {
  readonly capacity: number;
  readonly alive: (i: number) => boolean;
  readonly position: table.Getter<d.Vec3f>;
  readonly width: table.Getter<d.F32>;
}

export function createTrails(root: TgpuRoot, options: TrailsOptions) {
  const { capacity, alive, position, width } = options;

  const step = tgpu.computeFn({
    workgroupSize: [64],
    in: { gid: d.builtin.globalInvocationId },
  })(({ gid }) => {
    'use gpu';
    if (gid.x >= capacity || !alive(gid.x)) return;

    const p = position(gid.x);
    const w = width(gid.x);
    // ..
  });

  return root.createComputePipeline({ compute: step });
}

const rows = enemies.inject();
const trails = { ...enemies.live(), position: Enemy.position.pipe(rows) };
createTrails(root, { ...trails, width: Enemy.size.pipe(rows) });
createTrails(root, { ...trails, width: Enemy.species.pipe(rows) }); // species is a u32
Error ts(2322)  ― Type 'Getter<U32>' is not assignable to type 'Getter<F32>'.
  Types of property '[schemaOf]' are incompatible.
    Type 'U32 | undefined' is not assignable to type 'F32 | undefined'.
      Type 'U32' is not assignable to type 'F32'.
        Types of property 'type' are incompatible.
          Type '"u32"' is not assignable to type '"f32"'.

• table.Getter keeps a field’s schema in its type, through pipe too, so a u32 field doesn’t pass for an f32, though both are numbers in TypeScript.
• You can pass any shader function. (i) => Enemy.alive(i) && Enemy.species(i) === BOSS selects some rows. A procedural source needs no fill. Wrap your function to pipe a fill into it: tgpu.fn((i: number) => { … }).pipe(rows).
• enemies.live() returns the table’s capacity, its filled alive getter and a span function. Spread them into options for the neighbour grid, live lists, picker or state machines: liveLists.create(root, { ...enemies.live(), draws }). Each dispatches only up to the span.

Changes the GPU applies

The CPU doesn’t know a device field’s value. To apply a relative change such as “take 5 damage”, send a command to the kernel that owns the field. A host-only table holds the commands:

const Hits = table.define('Hits', { host: { victim: d.u32, amount: d.f32 } });
const hits = table.create(root, Hits, { capacity: 256 });

hits.add({ victim: id, amount: 5 }); // an enemy's id, stored as a u32
// after the frame: hits.clear()

// The kernel that owns `health`, created from root.pipe(enemies.inject()).pipe(hits.inject()):
const damage = tgpu.computeFn({
  workgroupSize: [64],
  in: { gid: d.builtin.globalInvocationId },
})(({ gid }) => {
  'use gpu';
  const i = gid.x;
  if (!Enemy.alive(i)) return;

  const enemy = Enemy.device.$[i];
  for (let h = d.u32(0); h < Hits.span(); h++) {
    if (Hits.alive(h) && Enemy.slotOf(Hits.victim(h)) === i) enemy.health -= Hits.amount(h);
  }
});

• Use one thread per row to scan the commands. A thread per command can lose an update when two commands hit the same row, and WGSL has no float atomics.
• The kernel does rows × commands checks. This suits a few hundred commands per frame. For more, sort them by target or use fixed-point atomics.

Limits

• Rows can’t be added on the GPU; particles keep a ring of their own.
• No struct-of-arrays layout, and no packed fields such as rgba8 in a u32.
• A table uses three of the eight storage bindings WebGPU guarantees per stage, for host rows, device rows and live bits.
• slotOf(id) reads the id mask from the uniform the table binds for its span, so a shader that reads ids binds it too.
• Two definitions given one name share their ids’ brand.
• A device part of more than 32 fields marks its 32nd and later fields with one bit, so a write to any of them uploads to the end of the row.
• The instances renderer passes a whole row to each of an instance kind’s hooks per vertex and per fragment. Prefer field getters in hot shader code to avoid unnecessary loads.