/typegpu

name: typegpu
description: >-
  TypeGPU is type-safe WebGPU in TypeScript. Use whenever the user writes, debugs, or designs TypeGPU code: 'use gpu' shader functions, tgpu.fn, buffers, textures, bind groups, compute and render pipelines, command encoders, render passes, render bundles, vertex layouts, slots, accessors, @typegpu/react hooks (useRoot, useFrame, useUniform), React Native worklet rendering, and any TypeGPU API. Shader logic and CPU-side resources are tightly coupled - handle both sides here even if the user only mentions one (e.g. "how do I write a shader", "how do I create a buffer"). Trigger on any mention of typegpu, tgpu, "use gpu", TypedGPU, or WebGPU code written using TypeGPU's schema API (d.*, tgpu.*, std.*). Do NOT trigger for raw WebGPU (using GPUDevice/GPURenderPipeline directly without tgpu), WGSL-only questions, Three.js, Babylon.js, or WebGL.

TypeGPU

A single schema (`d.*`) defines a GPU type, CPU buffer layout, and TypeScript type at once - no manual alignment, type mapping, or casting. The build plugin `unplugin-typegpu` transforms `'use gpu'`-marked TypeScript for runtime WGSL transpilation, enabling type inference and polymorphism across the CPU/GPU boundary.

This skill targets TypeGPU `0.12`. If the user's project is on an older release, verify API availability before relying on examples or recommended patterns here.

---

When to read reference files

**Read before writing virtually any shader or GPU function** — these two cover the rules that trip people up most:

• `references/types.md` — abstract type resolution, exactly when `d.f32()` is required vs redundant, vector constructor overloads, sampler/texture schemas for `tgpu.fn` signatures, CPU-side `TgpuBuffer`/`TgpuTexture` TypeScript types. **If you skip this, you'll hit type errors.**
• `references/shaders.md` — loops (`std.range`, `tgpu.unroll`), ternary/logical-operator semantics, `tgpu.comptime`, outer-scope capture rules, complete builtin reference for all three shader stages, `console.log`. **Read this for any non-trivial shader logic.**
• `references/std.md` — full `std` function listing (math, comparison/boolean vectors, matrix builders, texture, atomics, packing, subgroups, environment probes). Consult before hand-rolling any math/utility function.

**Read when the task specifically involves:**

• `references/pipelines.md` — vertex buffers/layouts, `attribs` wiring, MRT, fullscreen triangle, depth/stencil, blend modes, `fragDepth` output, loading 3D models (`@loaders.gl`), resolve API
• `references/matrices.md` — `wgpu-matrix` integration, column-major layout, camera uniforms, `common.writeSoA`, fast-path CPU writes. **Read for any 3D work** (view/projection matrices, animated transforms, model loading)
• `references/textures.md` — texture creation, views, samplers, storage textures, mipmaps, multisampling
• `references/noise.md` — `@typegpu/noise` (random, distributions, Perlin 2D/3D)
• `references/sdf.md` — `@typegpu/sdf` (2D/3D primitives, operators, ray marching, AA masking)
• `references/encoders.md` — typed command encoders, multi-pipeline render/compute passes, render bundles, batched submission, raw-WebGPU encoder interop (unstable API, stable behavior)
• `references/timing.md` — GPU timing via timestamp queries: `withPerformanceCallback` vs a shared query set, the `available` guard, why per-pass timings overlap
• `references/react.md` — `@typegpu/react` hooks (useRoot, useFrame, useUniform, ...), React Native worklet render loops
• `references/setup.md` — TypeGPU CLI, install, `unplugin-typegpu` build plugin, `tsover` operator overloading, troubleshooting
• `references/advanced.md` — buffer reinterpretation, indirect drawing/dispatch, ArrayBuffer IO, minification, warning silencing, `root.unwrap`

---

Setup

import { tgpu, d, std, common } from 'typegpu';

const root = await tgpu.init();                 // request a GPU device
const root = tgpu.initFromDevice({ device });   // or wrap an existing GPUDevice

const context = root.configureContext({ canvas, alphaMode: 'premultiplied' });

Create one root at app startup. Resources from different roots cannot interact. Teardown: `root.destroy()` destroys all resources created through the root, plus the device itself if the root came from `tgpu.init` (not `initFromDevice`).

---

Data schemas (`d.*`)

A schema defines memory layout and infers TypeScript types; the same schema is used for buffers, shader signatures, and bind group entries.

Scalars

d.f32    d.i32    d.u32    d.f16   // f16 needs the 'shader-f16' device feature (references/setup.md)
// d.bool is NOT host-shareable - use d.u32 in buffers

Vectors and matrices

d.vec2f  d.vec3f  d.vec4f     // f32
d.vec2i  d.vec3i  d.vec4i     // i32
d.vec2u  d.vec3u  d.vec4u     // u32
d.vec2h  d.vec3h  d.vec4h     // f16
d.vec2b  d.vec3b  d.vec4b     // bool - shader-side only (not host-shareable)

d.mat2x2f   d.mat3x3f   d.mat4x4f

Instance types: `d.vec3f()` -> `d.v3f`, `d.mat4x4f()` -> `d.m4x4f`.

**Vector constructors are richly overloaded** — they compose from any mix of scalars, smaller vectors, and swizzles that adds up to the right component count (`d.vec4f(rgb, 1)`, `d.vec3f(v.xy, newZ)`). Prefer them over manual component decomposition; full overload listing in `references/types.md`.

Compound types

const Particle = d.struct({
  position: d.vec2f,
  velocity: d.vec2f,
  color:    d.vec4f,
});

const ParticleArray = d.arrayOf(Particle, 1000); // fixed-size

**Runtime-sized schemas.** `d.arrayOf(Element)` without a count returns a *function* `(n: number) => WgslArray<Element>`. This dual nature is the key: pass the function itself (unsized) to bind group layouts, call it with a count (sized) for buffer creation.

// Plain array - arrayOf without count is already a factory:
const layout = tgpu.bindGroupLayout({
  data: { storage: d.arrayOf(d.f32), access: 'mutable' },  // unsized for layout
});
const buf = r