@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/render/wgsl.js

@@ -0,0 +1,528 @@
+import { BUFFER_BINDING_BASE } from './bindings.js';
+import { reportGpuError } from './diagnostics.js';
+import { VERTEX_LAYOUT_2D } from './mesh.js';
+/**
+ * Create a shader module and surface compile errors with file/line context. Compilation is
+ * async in the browser; errors are logged as soon as they are known.
+ */
+export function createShaderModule(device, code, label) {
+    const module = device.createShaderModule({ code, label });
+    module.getCompilationInfo().then((info) => {
+        if (!info.messages.length)
+            return;
+        const lines = code.split('\n');
+        for (const m of info.messages) {
+            const src = lines[m.lineNum - 1] ?? '';
+            const caret = `${' '.repeat(Math.max(0, m.linePos - 1))}^`;
+            const text = `[wgsl] ${label}:${m.lineNum}:${m.linePos} ${m.type}: ${m.message}\n    ${src}\n    ${caret}`;
+            if (m.type === 'error')
+                reportGpuError(text);
+            else
+                console.warn(text);
+        }
+    });
+    return module;
+}
+/**
+ * Per-frame engine bindings for every material and drawable, in `@group(0)`:
+ *
+ * - `@binding(0) globals`: `logicalSize`, `targetSize` (scene target px), `time`, `dt`.
+ * - `@binding(1) camera` (the camera block): `view`, `proj`, `view_proj` (world → clip),
+ *   `camera_pos` (world eye position, w = 1), `viewport` (target px: x, y, w, h),
+ *   `view_index` (`camera.viewIndex`: 0, or the eye index of an XR view), `inv_view_proj`
+ *   (clip → world, the inverse of `view_proj`; `camera.invViewProj` on the CPU side),
+ *   `prev_view_proj` and `prev_view` (last frame's unjittered `view_proj` and `view`) and
+ *   `jitter` (clip-space dx, dy; the pixel offset x, y).
+ */
+export const WGSL_GLOBALS = /* wgsl */ `
+struct EngineGlobals {
+  logicalSize: vec2f,
+  targetSize: vec2f,
+  time: f32,
+  dt: f32,
+  _pad: vec2f,
+};
+@group(0) @binding(0) var<uniform> globals: EngineGlobals;
+struct EngineCamera {
+  view: mat4x4f,
+  proj: mat4x4f,
+  view_proj: mat4x4f,
+  camera_pos: vec4f,
+  viewport: vec4f,
+  view_index: u32,
+  _pad0: u32, _pad1: u32, _pad2: u32,
+  inv_view_proj: mat4x4f,
+  prev_view_proj: mat4x4f,
+  prev_view: mat4x4f,
+  jitter: vec4f,
+};
+@group(0) @binding(1) var<uniform> camera: EngineCamera;
+`;
+/**
+ * The Lambert BRDF for `wgslLightLoop`: `N·L` clamped at 0, the reflected fraction of a light's
+ * colour before the albedo (the light's colour × this is what `engine_lambert` returns per light).
+ */
+export const WGSL_LAMBERT_BRDF = 'vec3f(max(dot(normal, l), 0.0))';
+/**
+ * Generate the engine light loop as a WGSL function `name(world_pos: vec3f, normal: vec3f,
+ * layer_mask: u32${params}) -> vec3f`: the sum over the lights whose `layers` share a bit with
+ * `layer_mask` of the light's colour × its attenuation × `brdf`. The sun (× `engine_shadow`),
+ * the `(1 - d/radius)²` point falloff and the spot cone (`engine_spot_cone` × the same falloff)
+ * are the loop's; the BRDF is the material's.
+ *
+ * WGSL has no function pointers, so the material supplies `brdf` as a WGSL expression that the
+ * loop body inlines once per light kind. In it, `l` is the unit direction from the surface to
+ * the light, `normal` and `world_pos` are the function's parameters and `params` (`', v: vec3f,
+ * f0: vec3f'` and so on; leading comma) adds whatever else it needs to the signature. The
+ * expression must be finite for any `l` (it is multiplied by 0 for lights that do not reach).
+ * `WGSL_LIGHTS` instantiates it as `engine_light_accum` with `WGSL_LAMBERT_BRDF`; `WGSL_PBR` as
+ * `engine_pbr_accum` with `engine_brdf(...)`. Generate rather than copy: the loop then changes
+ * in one place when the block gains a light kind.
+ */
+export function wgslLightLoop(name, brdf, params = '') {
+    return /* wgsl */ `fn ${name}(world_pos: vec3f, normal: vec3f, layer_mask: u32${params}) -> vec3f {
+  var sum = vec3f(0.0);
+  if ((lights.sun_layers & layer_mask) != 0u) {
+    let l = -lights.sun_dir;
+    sum += lights.sun_color * (${brdf}) * engine_shadow(world_pos);
+  }
+  for (var i = 0u; i < lights.point_count; i++) {
+    if ((lights.point_layers[i >> 2u][i & 3u] & layer_mask) == 0u) { continue; }
+    let light = lights.points[i];
+    let to = light.position - world_pos;
+    let d = length(to);
+    let falloff = saturate(1.0 - d / max(light.radius, 1e-4));
+    if (falloff <= 0.0) { continue; }
+    let l = to / max(d, 1e-4);
+    sum += light.color * (falloff * falloff * (${brdf}));
+  }
+  for (var i = 0u; i < lights.spot_count; i++) {
+    let light = lights.spots[i];
+    if ((light.layers & layer_mask) == 0u) { continue; }
+    let to = light.position - world_pos;
+    let d = length(to);
+    let l = to / max(d, 1e-4);
+    let falloff = saturate(1.0 - d / max(light.radius, 1e-4));
+    if (falloff <= 0.0) { continue; }
+    let cone = engine_spot_cone(dot(-l, light.direction), light.cos_outer, light.cos_inner);
+    sum += light.color * (falloff * falloff * cone * (${brdf}));
+  }
+  return sum;
+}`;
+}
+/**
+ * The lighting block, `@group(0) @binding(2)` (see `Lights` / `lights.ts`), in every material
+ * and drawable prelude: `lights.ambient`, `lights.point_count`, `lights.sun_dir` (the way
+ * the light travels), `lights.sun_color`, `lights.points[i]` (`position`, `radius`, `color`),
+ * `lights.sun_view_proj` (world → sun clip), `lights.shadow_params` (bias, map texel size,
+ * enabled, pad), `lights.fog` (rgb, density), `lights.fog_range` (near, far, pad, pad),
+ * `lights.spot_count`, `lights.sun_layers` (the sun's layer mask), `lights.point_layers`
+ * (`array<vec4u, 4>`: the mask of point `i` is `point_layers[i >> 2u][i & 3u]`) and
+ * `lights.spots[i]` (`position`, `radius`, `direction`, `cos_outer`, `color`, `cos_inner`,
+ * `layers`). The sun's shadow map (`texture_depth_2d`) and its comparison sampler sit at
+ * `@binding(3)` and `@binding(4)`; with no shadow pass a 1×1 depth texture is bound there.
+ *
+ * Helpers a game may call or ignore: `engine_point_lights(normal, world_pos)` sums the point
+ * lights' diffuse (Lambert × a smooth falloff that reaches zero at `radius`), all layers;
+ * `engine_spot_cone(cos_theta, cos_outer, cos_inner)` is a spot's cone factor;
+ * `engine_instance_layers(flags)` is the instance's layer bits from `VSOut.flags`;
+ * `engine_light_accum(world_pos, normal, layer_mask)` sums the sun (× `engine_shadow`), point
+ * and spot Lambert terms of every light whose `layers` share a bit with `layer_mask`;
+ * `engine_shadow(world_pos)` is the sun's visibility, 0..1 (3×3 PCF over the shadow map; 1
+ * outside the map or when there is no shadow pass); `engine_fog(color, world_pos)` blends
+ * `color` toward the fog colour by the distance to the camera (linear over `fog_range` when
+ * `far > near`, else exponential past `near`; identity when density is 0);
+ * `engine_lambert(normal, world_pos)` is ambient + `engine_light_accum` over every layer, so
+ * with the default block it returns `vec3f(1.0)` and `albedo * engine_lambert(...)` is unlit;
+ * `engine_lambert_layers(normal, world_pos, layer_mask)` is the same against the instance's
+ * layers (`engine_instance_layers(in.flags)`), so masked lights skip it.
+ *
+ * `engine_light_accum` is `wgslLightLoop('engine_light_accum', WGSL_LAMBERT_BRDF)`: the one
+ * light loop, generated with a Lambert BRDF; `WGSL_PBR` generates the same loop with its GGX BRDF.
+ */
+export const WGSL_LIGHTS = /* wgsl */ `
+struct EnginePointLight {
+  position: vec3f,
+  radius: f32,
+  color: vec3f,
+  _pad: f32,
+};
+struct EngineSpotLight {
+  position: vec3f,
+  radius: f32,
+  direction: vec3f,
+  cos_outer: f32,
+  color: vec3f,
+  cos_inner: f32,
+  layers: u32,
+  _pad0: u32,
+  _pad1: u32,
+  _pad2: u32,
+};
+struct EngineLights {
+  ambient: vec3f,
+  point_count: u32,
+  sun_dir: vec3f,
+  _pad0: f32,
+  sun_color: vec3f,
+  _pad1: f32,
+  points: array<EnginePointLight, 16>,
+  sun_view_proj: mat4x4f,
+  shadow_params: vec4f,
+  fog: vec4f,
+  fog_range: vec4f,
+  spot_count: u32,
+  sun_layers: u32,
+  _pad2: vec2u,
+  point_layers: array<vec4u, 4>,
+  spots: array<EngineSpotLight, 8>,
+};
+@group(0) @binding(2) var<uniform> lights: EngineLights;
+@group(0) @binding(3) var engine_shadow_map: texture_depth_2d;
+@group(0) @binding(4) var engine_shadow_sampler: sampler_comparison;
+fn engine_point_lights(normal: vec3f, world_pos: vec3f) -> vec3f {
+  var sum = vec3f(0.0);
+  for (var i = 0u; i < lights.point_count; i++) {
+    let l = lights.points[i];
+    let to = l.position - world_pos;
+    let d = length(to);
+    let falloff = saturate(1.0 - d / max(l.radius, 1e-4));
+    let diffuse = max(dot(normal, to / max(d, 1e-4)), 0.0);
+    sum += l.color * (falloff * falloff * diffuse);
+  }
+  return sum;
+}
+fn engine_shadow(world_pos: vec3f) -> f32 {
+  if (lights.shadow_params.z == 0.0) { return 1.0; }
+  let clip = lights.sun_view_proj * vec4f(world_pos, 1.0);
+  let ndc = clip.xyz / clip.w;
+  if (any(abs(ndc.xy) > vec2f(1.0)) || ndc.z < 0.0 || ndc.z > 1.0) { return 1.0; }
+  let uv = vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);
+  let depth = ndc.z - lights.shadow_params.x;
+  let texel = lights.shadow_params.y;
+  var lit = 0.0;
+  for (var y = -1; y <= 1; y++) {
+    for (var x = -1; x <= 1; x++) {
+      let o = vec2f(f32(x), f32(y)) * texel;
+      lit += textureSampleCompareLevel(engine_shadow_map, engine_shadow_sampler, uv + o, depth);
+    }
+  }
+  return lit / 9.0;
+}
+fn engine_fog(color: vec3f, world_pos: vec3f) -> vec3f {
+  let density = lights.fog.w;
+  if (density == 0.0) { return color; }
+  let d = distance(world_pos, camera.camera_pos.xyz);
+  let near = lights.fog_range.x;
+  let far = lights.fog_range.y;
+  let linear = saturate((d - near) / max(far - near, 1e-4)) * saturate(density);
+  let expo = 1.0 - exp(-density * max(d - near, 0.0));
+  let f = select(expo, linear, far > near);
+  return mix(color, lights.fog.rgb, f);
+}
+fn engine_spot_cone(cos_theta: f32, cos_outer: f32, cos_inner: f32) -> f32 {
+  let t = saturate((cos_theta - cos_outer) / max(cos_inner - cos_outer, 1e-4));
+  return t * t * (3.0 - 2.0 * t);
+}
+fn engine_instance_layers(flags: u32) -> u32 {
+  return flags >> 1u;
+}
+${wgslLightLoop('engine_light_accum', WGSL_LAMBERT_BRDF)}
+fn engine_lambert_layers(normal: vec3f, world_pos: vec3f, layer_mask: u32) -> vec3f {
+  return lights.ambient + engine_light_accum(world_pos, normal, layer_mask);
+}
+fn engine_lambert(normal: vec3f, world_pos: vec3f) -> vec3f {
+  return engine_lambert_layers(normal, world_pos, 0xffffffffu);
+}
+`;
+/** Hash / value-noise / fbm helpers available to every material and fullscreen pass. */
+export const WGSL_NOISE = /* wgsl */ `
+fn engine_hash21(p: vec2f) -> f32 {
+  var p3 = fract(vec3f(p.x, p.y, p.x) * 0.1031);
+  p3 += dot(p3, p3.yzx + 33.33);
+  return fract((p3.x + p3.y) * p3.z);
+}
+fn engine_hash22(p: vec2f) -> vec2f {
+  var p3 = fract(vec3f(p.x, p.y, p.x) * vec3f(0.1031, 0.1030, 0.0973));
+  p3 += dot(p3, p3.yzx + 33.33);
+  return fract((p3.xx + p3.yz) * p3.zy);
+}
+fn engine_noise(p: vec2f) -> f32 {
+  let i = floor(p);
+  let f = fract(p);
+  let u = f * f * (3.0 - 2.0 * f);
+  let a = engine_hash21(i);
+  let b = engine_hash21(i + vec2f(1.0, 0.0));
+  let c = engine_hash21(i + vec2f(0.0, 1.0));
+  let d = engine_hash21(i + vec2f(1.0, 1.0));
+  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);
+}
+fn engine_fbm(p: vec2f, octaves: i32) -> f32 {
+  var v = 0.0;
+  var amp = 0.5;
+  var q = p;
+  for (var i = 0; i < octaves; i++) {
+    v += amp * engine_noise(q);
+    q = q * 2.03 + vec2f(17.1, 9.2);
+    amp *= 0.5;
+  }
+  return v;
+}
+fn engine_luma(c: vec3f) -> f32 {
+  return dot(c, vec3f(0.2126, 0.7152, 0.0722));
+}
+`;
+/** The `SkinPalette` binding inside the material's group: `@group(1) @binding(16)`. */
+export const SKIN_PALETTE_BINDING = BUFFER_BINDING_BASE;
+/**
+ * GPU skinning, emitted by `materialPrelude` for a layout with `skinned: true` (after
+ * `VertexIn`, which it reads). The palette is the material's storage buffer slot 0
+ * (`SkinPalette.buffer` passed as `buffers: [palette.buffer]`): a header (`joints` per
+ * instance, `instances`, `history`) and `rows`, three `vec4f` rows per joint (row-major 3×4, the layout
+ * `anim`'s `skinMatrices` writes), instance after instance. `engine_skin(v, position, normal)`
+ * sums the four weighted joint matrices of the vertex (`v.joints`, `v.weights`) for the
+ * instance's palette slot `u32(v.params.w)` and applies them to an object-space position and
+ * normal, before the instance matrix. A weight of 0 skips the fetch.
+ */
+export const WGSL_SKIN = /* wgsl */ `struct EngineSkinPalette {
+  joints: u32,
+  instances: u32,
+  history: u32,
+  _pad1: u32,
+  rows: array<vec4f>,
+};
+@group(1) @binding(${SKIN_PALETTE_BINDING}) var<storage, read> engine_skin_palette: EngineSkinPalette;
+struct EngineSkinned {
+  position: vec3f,
+  normal: vec3f,
+};
+fn engine_skin(v: VertexIn, position: vec3f, normal: vec3f) -> EngineSkinned {
+  let base = u32(v.params.w) * engine_skin_palette.joints * 3u;
+  let p = vec4f(position, 1.0);
+  var skinned: EngineSkinned;
+  skinned.position = vec3f(0.0);
+  skinned.normal = vec3f(0.0);
+  for (var k = 0u; k < 4u; k++) {
+    let w = v.weights[k];
+    if (w == 0.0) { continue; }
+    let r = base + v.joints[k] * 3u;
+    let r0 = engine_skin_palette.rows[r];
+    let r1 = engine_skin_palette.rows[r + 1u];
+    let r2 = engine_skin_palette.rows[r + 2u];
+    skinned.position += w * vec3f(dot(r0, p), dot(r1, p), dot(r2, p));
+    skinned.normal += w * vec3f(dot(r0.xyz, normal), dot(r1.xyz, normal), dot(r2.xyz, normal));
+  }
+  return skinned;
+}
+// The previous frame's skinned position from the palette's history block (SkinPalette
+// with history), w = 1; w = 0 when the palette keeps none (velocity reads zero).
+fn engine_skin_previous(v: VertexIn, position: vec3f) -> vec4f {
+  if (engine_skin_palette.history == 0u) { return vec4f(0.0); }
+  let base = (engine_skin_palette.instances + u32(v.params.w)) * engine_skin_palette.joints * 3u;
+  let p = vec4f(position, 1.0);
+  var out = vec3f(0.0);
+  for (var k = 0u; k < 4u; k++) {
+    let w = v.weights[k];
+    if (w == 0.0) { continue; }
+    let r = base + v.joints[k] * 3u;
+    out += w * vec3f(dot(engine_skin_palette.rows[r], p), dot(engine_skin_palette.rows[r + 1u], p), dot(engine_skin_palette.rows[r + 2u], p));
+  }
+  return vec4f(out, 1.0);
+}`;
+/** The plain variant: what every material compiled with before aux targets. */
+export const PLAIN_VARIANT = Object.freeze({});
+/**
+ * Three vertex locations in 10..15 the layout's attributes leave free, for the previous-matrix
+ * lane (`prevLane`), as `[p0, p1, p2]`.
+ */
+export function prevLaneLocations(layout) {
+    const used = new Set();
+    for (const a of layout.buffer.attributes)
+        used.add(a.shaderLocation);
+    const out = [];
+    for (let loc = 10; loc <= 15 && out.length < 3; loc++)
+        if (!used.has(loc))
+            out.push(loc);
+    if (out.length < 3)
+        throw new Error(`layout ${layout.name}: no free locations for a previous-matrix lane`);
+    return [out[0], out[1], out[2]];
+}
+/** The previous-matrix vertex buffer layout (slot 2) for `layout`: 48 bytes per instance. */
+export function prevLaneBufferLayout(layout) {
+    let lane = laneLayouts.get(layout);
+    if (lane)
+        return lane;
+    const [a, b, c] = prevLaneLocations(layout);
+    lane = {
+        arrayStride: 48,
+        stepMode: 'instance',
+        attributes: [
+            { shaderLocation: a, offset: 0, format: 'float32x4' },
+            { shaderLocation: b, offset: 16, format: 'float32x4' },
+            { shaderLocation: c, offset: 32, format: 'float32x4' },
+        ],
+    };
+    laneLayouts.set(layout, lane);
+    return lane;
+}
+const laneLayouts = new WeakMap();
+/**
+ * Prelude prepended to every material, generated per vertex layout (and `PreludeVariant`).
+ * Declares `VertexIn` (the layout's vertex fields plus the 28-float instance: 3×4 world matrix
+ * rows `m0..m2`, `uvRect`, `tint`, `params`, `misc` = emissive, flags, size.xy), the default
+ * vertex entry `vs_main`, the `VSOut` varyings (`flags` is the instance's flag bits: bit 0 set
+ * means `receiveShadow: false`, bits 1..23 are its layers; `tangent` the world-space file
+ * tangent, w = 0 without one; `uv1` the second uv set, `uv` without one) and the `FragOut` MRT
+ * struct.
+ *
+ * Helpers: `engine_local_position(v)` / `engine_local_normal(v)` / `engine_local_tangent(v)`
+ * (object space; skinned for a `skinned` layout), `engine_world_position(v)`,
+ * `engine_previous_world_position(v)` (last frame's, `vec4f`, w = 0 when unknown),
+ * `engine_vertex(v)`, `engine_velocity(in)` (screen-space uv motion since last frame, zero
+ * without a velocity target) and `engine_write_aux(&o, rough_metal, velocity)` (fills the
+ * target's aux outputs, a no-op without them); the lighting block and `engine_lambert` /
+ * `engine_point_lights` from `WGSL_LIGHTS`; `WGSL_SKIN` (`engine_skin`, the palette binding)
+ * for a skinned layout only. The text for the 2D and 3D layouts does not change with skinning
+ * (E-008).
+ */
+export function materialPrelude(layout, variant = PLAIN_VARIANT) {
+    const velocity = variant.velocity === true;
+    const prevLane = variant.prevLane === true;
+    const roughMetal = variant.roughMetal === true;
+    let auxFields = '';
+    let auxLoc = 2;
+    if (roughMetal)
+        auxFields += `\n  @location(${auxLoc++}) rough_metal: vec2f,`;
+    if (velocity)
+        auxFields += `\n  @location(${auxLoc++}) velocity: vec2f,`;
+    let laneFields = '';
+    if (prevLane) {
+        const [a, b, c] = prevLaneLocations(layout);
+        laneFields = `\n  @location(${a}) p0: vec4f,\n  @location(${b}) p1: vec4f,\n  @location(${c}) p2: vec4f,`;
+    }
+    const prevRows = prevLane ? 'v.p0, v.p1, v.p2' : 'v.m0, v.m1, v.m2';
+    const prevPos = layout.wgslPreviousPosition ?? 'vec4f(engine_local_position(v), 1.0)';
+    return /* wgsl */ `
+${WGSL_GLOBALS}
+${WGSL_LIGHTS}
+${WGSL_NOISE}
+struct VertexIn {
+${layout.wgslFields}
+  @location(3) m0: vec4f,
+  @location(4) m1: vec4f,
+  @location(5) m2: vec4f,
+  @location(6) uvRect: vec4f,
+  @location(7) tint: vec4f,
+  @location(8) params: vec4f,
+  @location(9) misc: vec4f,${laneFields}
+};
+
+struct VSOut {
+  @builtin(position) clip: vec4f,
+  @location(0) uv: vec2f,
+  @location(1) local: vec2f,
+  @location(2) color: vec4f,
+  @location(3) params: vec4f,
+  @location(4) world: vec2f,
+  @location(5) emissive: f32,
+  @location(6) size: vec2f,
+  @location(7) normal: vec3f,
+  @location(8) worldPos: vec3f,
+  @location(9) @interpolate(flat) flags: u32,
+  @location(10) tangent: vec4f,
+  @location(12) uv1: vec2f,${velocity ? '\n  @location(11) prev_clip: vec4f,' : ''}
+};
+
+struct FragOut {
+  @location(0) color: vec4f,
+  @location(1) emissive: vec4f,${auxFields}
+};
+${layout.skinned ? `\n${WGSL_SKIN}\n` : ''}
+fn engine_local_position(v: VertexIn) -> vec3f {
+  return ${layout.wgslPosition};
+}
+
+fn engine_local_normal(v: VertexIn) -> vec3f {
+  return ${layout.wgslNormal};
+}
+
+fn engine_local_tangent(v: VertexIn) -> vec4f {
+  return ${layout.wgslTangent ?? 'vec4f(0.0)'};
+}
+
+fn engine_world_position(v: VertexIn) -> vec3f {
+  let p = vec4f(engine_local_position(v), 1.0);
+  return vec3f(dot(v.m0, p), dot(v.m1, p), dot(v.m2, p));
+}
+
+fn engine_previous_world_position(v: VertexIn) -> vec4f {
+  let lp = ${prevPos};
+  let p = vec4f(lp.xyz, 1.0);
+  let rows = array<vec4f, 3>(${prevRows});
+  return vec4f(dot(rows[0], p), dot(rows[1], p), dot(rows[2], p), lp.w);
+}
+
+fn engine_vertex(v: VertexIn) -> VSOut {
+  let world3 = engine_world_position(v);
+  let world = world3.xy;
+  let n = engine_local_normal(v);
+  let t = engine_local_tangent(v);
+  var o: VSOut;
+  o.clip = camera.view_proj * vec4f(world3, 1.0);
+  o.uv = mix(v.uvRect.xy, v.uvRect.zw, v.uv);
+  o.local = v.uv;
+  o.color = v.color * v.tint;
+  o.params = v.params;
+  o.world = world;
+  o.emissive = v.misc.x;
+  o.size = v.misc.zw;
+  o.normal = normalize(vec3f(dot(v.m0.xyz, n), dot(v.m1.xyz, n), dot(v.m2.xyz, n)));
+  o.worldPos = world3;
+  o.flags = u32(v.misc.y);
+  o.tangent = vec4f(vec3f(dot(v.m0.xyz, t.xyz), dot(v.m1.xyz, t.xyz), dot(v.m2.xyz, t.xyz)), t.w);
+  o.uv1 = mix(v.uvRect.xy, v.uvRect.zw, ${layout.wgslUv1 ?? 'v.uv'});${velocity
+        ? `
+  let prev = engine_previous_world_position(v);
+  o.prev_clip = select(vec4f(0.0), camera.prev_view_proj * vec4f(prev.xyz, 1.0), prev.w != 0.0);`
+        : ''}
+  return o;
+}
+
+// Screen-space motion since the previous frame in uv units (+x right, +y down), jitter
+// removed; zero when the target has no velocity attachment or the previous position is unknown.
+fn engine_velocity(in: VSOut) -> vec2f {${velocity
+        ? `
+  if (in.prev_clip.w == 0.0) { return vec2f(0.0); }
+  let cur = (in.clip.xy - camera.viewport.xy) / camera.viewport.zw - camera.jitter.xy * vec2f(0.5, -0.5);
+  let pn = in.prev_clip.xy / in.prev_clip.w;
+  let prev = vec2f(pn.x * 0.5 + 0.5, 0.5 - pn.y * 0.5);
+  return cur - prev;`
+        : '\n  return vec2f(0.0);'}
+}
+
+// Write the aux outputs the target has (roughness, metalness; velocity); nothing otherwise.
+fn engine_write_aux(o: ptr<function, FragOut>, rough_metal: vec2f, velocity: vec2f) {${roughMetal ? '\n  (*o).rough_metal = rough_metal;' : ''}${velocity ? '\n  (*o).velocity = velocity;' : ''}
+}
+
+@vertex fn vs_main(v: VertexIn) -> VSOut {
+  return engine_vertex(v);
+}
+`;
+}
+/** The material prelude for the 2D vertex layout (what every 2D material compiles with). */
+export const WGSL_MATERIAL_PRELUDE = materialPrelude(VERTEX_LAYOUT_2D);
+/** Prelude for fullscreen passes: `vs_fullscreen` emits one triangle covering the target. */
+export const WGSL_FULLSCREEN_PRELUDE = /* wgsl */ `
+${WGSL_NOISE}
+struct FullscreenIn {
+  @builtin(position) pos: vec4f,
+  @location(0) uv: vec2f,
+};
+@vertex fn vs_fullscreen(@builtin(vertex_index) i: u32) -> FullscreenIn {
+  let p = vec2f(f32((i << 1u) & 2u), f32(i & 2u));
+  var o: FullscreenIn;
+  o.pos = vec4f(p * 2.0 - 1.0, 0.0, 1.0);
+  o.uv = vec2f(p.x, 1.0 - p.y);
+  return o;
+}
+`;

package/dist/save/codec.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Save envelope, the typed-array JSON codec and the export/import string codec.
+ *
+ * Stored value: JSON `{ "v": <version>, "t": <savedAt ms>, "d": <data> }`.
+ * Export string: `TC1.<game>.<checksum>.<base64url(envelope JSON)>`. The checksum
+ * (FNV-1a, hex) catches truncated copy-paste; it is not tamper protection.
+ *
+ * Typed arrays inside the data are stored as `{ "$b": <base64url bytes>, "$t"?: <kind> }`
+ * (`$t` omitted for `Uint8Array`) by `saveReplacer` and turned back by `saveReviver`, so a
+ * tilemap or a voxel chunk never goes through a JSON number array. Bytes are in platform byte
+ * order (little-endian everywhere WebGPU runs). A plain object of the player's data that has
+ * its own `$b` key is escaped as `$$b` (one more `$` per level) and unescaped on load.
+ */
+export interface Envelope {
+    v: number;
+    t: number;
+    d: unknown;
+}
+export declare function isEnvelope(x: unknown): x is Envelope;
+/** 32-bit FNV-1a over UTF-16 code units, as 8 hex chars. */
+export declare function fnv1a(text: string): string;
+/** Element kinds a typed array can be tagged with in stored JSON. */
+export type TypedKind = 'u8' | 'u16' | 'u32' | 'i8' | 'i16' | 'i32' | 'f32' | 'f64';
+export type TypedArrayOf<K extends TypedKind> = K extends 'u8' ? Uint8Array : K extends 'u16' ? Uint16Array : K extends 'u32' ? Uint32Array : K extends 'i8' ? Int8Array : K extends 'i16' ? Int16Array : K extends 'i32' ? Int32Array : K extends 'f32' ? Float32Array : Float64Array;
+type TypedCtor = {
+    new (buffer: ArrayBuffer, byteOffset?: number, length?: number): ArrayBufferView;
+    readonly BYTES_PER_ELEMENT: number;
+};
+/** Typed-array kind → constructor. Internal: `schema.ts` and the tests import it from here. */
+export declare const TYPED_KIND_CTORS: Record<TypedKind, TypedCtor>;
+/** The tag kind for `value` if it is one of the eight supported typed arrays, else null. */
+export declare function typedKindOf(value: unknown): TypedKind | null;
+/**
+ * `JSON.stringify` replacer: typed arrays become `{ $b, $t? }`; a plain object with a key
+ * matching `/^\$+b$/` gets that key prefixed with one more `$`.
+ */
+export declare function saveReplacer(_key: string, value: unknown): unknown;
+/** `JSON.parse` reviver undoing `saveReplacer`. Bad tags (damaged base64) are left as objects. */
+export declare function saveReviver(_key: string, value: unknown): unknown;
+export declare function encodeExport(game: string, env: Envelope): string;
+export type DecodeResult = {
+    ok: true;
+    envelope: Envelope;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function decodeExport(game: string, text: string): DecodeResult;
+export {};