@downdraft/engine 0.1.1 → 0.1.2-alpha.5

package/dist/libraries/stickman/src/index.js

@@ -0,0 +1,7 @@
+export { ARM_LEN, ARM_SWING, DEFAULT_LINE_WIDTH, ELBOW_BEND, FOOT_LIFT, HEAD_CY, HEAD_R, HEAD_SEGMENTS, HIP_Y, IDLE_ARM_OUT, IDLE_SWING, JUMP_ARM_SWING, JUMP_LEG_SWING, KNEE_BEND, LEG_LEN, LEG_SWING, NECK_Y, PLAYER_H, PLAYER_W, SHOULDER_Y, UPPER_LIMB_FRAC } from "./proportions.js";
+export { computeSkeleton, getHeadRadius, STICKMAN_FLOATS_PER_SEGMENT, STICKMAN_SEGMENT_COUNT, STICKMAN_SKELETON_FLOATS } from "./skeleton.js";
+export { buildThickLineIndices, buildThickLineVertices, STICKMAN_INDEX_COUNT, STICKMAN_VERTEX_COUNT, STICKMAN_VERTEX_STRIDE } from "./thick-line.js";
+export { STICKMAN_WGSL } from "./shader.js";
+export { StickmanPass } from "./stickman-pass.js";
+// Declarative library descriptor
+export { StickmanLib, StickmanTok } from "./library.js";

package/dist/libraries/stickman/src/library.js

@@ -0,0 +1,44 @@
+// ============================================================================
+// StickmanLib — declarative engine library descriptor for @downdraft/engine/libraries/stickman
+//
+// Games declare `libraries: [StickmanLib]` in their GameModule. The host
+// provides the stickman skeleton computation function (sim-side) via a typed
+// token.
+//
+// Games that need full control can still import computeSkeleton, the
+// thick-line geometry builders, and STICKMAN_WGSL directly (escape hatch).
+//
+// NOTE: This package does not declare a dependency on @downdraft/engine in its
+// package.json. We use a type-only import for EngineLibrary (erased at compile
+// time) and a relative import for the resourceToken runtime function.
+// ============================================================================
+import { resourceToken } from "@downdraft/engine";
+import { computeSkeleton } from "./skeleton.js";
+// ── Typed tokens (DI) ──
+/** Token for the sim-side stickman skeleton computation function. */
+export const StickmanTok = resourceToken("stickman:skeleton");
+// ── Descriptor ──
+export const StickmanLib = {
+    name: "stickman",
+    version: "1.0.0",
+    provides: [StickmanTok],
+    sim: {
+        create(_config, ctx) {
+            // The stickman library is a pure computation utility — no stateful
+            // system to instantiate. We provide the computeSkeleton function so
+            // sim systems can inject it and call it per-entity per-tick.
+            ctx.provide(StickmanTok, computeSkeleton);
+            return computeSkeleton;
+        },
+        dispose(_system) {
+            // Pure function — no resources to free.
+        },
+        // tick is game-specific (calls computeSkeleton per player entity with
+        // the entity's pose, uploads the result to a thick-line vertex buffer)
+        // — games wire this via onReady.
+    },
+    tickPhase: "post-physics",
+    // No renderer setup — stickman rendering is game-specific (the game
+    // creates a render pass using STICKMAN_WGSL + thick-line geometry).
+    defaultConfig: {},
+};

package/dist/libraries/stickman/src/proportions.js

@@ -0,0 +1,40 @@
+// Stickman proportions in world-cell units.
+//
+// All offsets are relative to `topY = py` (the top of the player's bounding
+// box) and `cx = px` (the horizontal center). `py` increases downward (screen
+// convention), so larger Y = lower on screen. The player's bounding box is
+// PLAYER_W cells wide and PLAYER_H cells tall; the feet land at
+// `topY + PLAYER_H`.
+//
+// These constants are the single source of truth shared by:
+//   - the WGSL stickman shader (via computeSkeleton)
+//   - the DOM/SVG NPC overlay in games that use stickman rendering
+//
+// Keep them in sync with the player collision box in each game.
+export const PLAYER_W = 3;
+export const PLAYER_H = 7;
+// Vertical joint offsets from topY (top of bounding box).
+export const HEAD_CY = 1.0; // head center Y
+export const HEAD_R = 0.8; // head radius (cells)
+export const HEAD_SEGMENTS = 24; // circle outline segment count (smooth circle)
+export const NECK_Y = 1.8; // neck (top of spine)
+export const SHOULDER_Y = 2.2; // shoulder pivot
+export const HIP_Y = 4.5; // hip pivot (bottom of spine)
+export const ARM_LEN = 1.5; // full arm length (shoulder -> hand)
+export const LEG_LEN = 2.5; // full leg length (hip -> foot) — reaches AABB bottom
+// 2-segment limb split: upper segment (shoulder->elbow / hip->knee) is this
+// fraction of the full limb length; the remainder is the lower segment.
+export const UPPER_LIMB_FRAC = 0.55;
+// Walk-cycle / pose amplitudes (in cells, applied per-limb).
+export const LEG_SWING = 0.5; // forward/back foot offset
+export const ARM_SWING = 0.4; // forward/back hand offset
+export const KNEE_BEND = 0.35; // knee lateral offset during walk
+export const ELBOW_BEND = 0.25; // elbow lateral offset during walk
+export const FOOT_LIFT = 0.45; // vertical foot lift during swing phase
+export const IDLE_SWING = 0.05; // idle breathing amplitude
+export const IDLE_ARM_OUT = 0.35; // idle: hands rest this far out from center
+export const JUMP_LEG_SWING = 0.3;
+export const JUMP_ARM_SWING = 0.5;
+// Render defaults. Line width is in cell units so strokes scale with zoom
+// (matches the SVG NPC overlay's strokeW = max(1, scale * 0.25)).
+export const DEFAULT_LINE_WIDTH = 0.3;

package/dist/libraries/stickman/src/shader.js

@@ -0,0 +1,113 @@
+// Shared thick-line + SDF-circle stickman WGSL shader.
+//
+// Both games use this single shader. The per-game coordinate transform is
+// baked into a uniform affine `u.transform` (cell coords -> NDC):
+//
+//   ndc.xy = worldPos.xy * transform.xy + transform.zw
+//
+// 2D grid games: transform = (2/gridW, -2/gridH, -1, +1)
+//
+// Two segment types (detected via endpointB.z > 0):
+//   Line:  extrudes a thick stroke perpendicular to the segment.
+//   Circle (head): expands quad to bounding box, fragment shader uses SDF
+//     to draw a perfect anti-aliased circle ring.
+//
+// Light/volumetric textures are sampled at the player's world position
+// (half-res, matching the game's light-accum pass). 2D grid games may bind
+// 1x1 white dummy textures so lighting is identity.
+import { f32, vec2f, vec3f, vec4f, wgsl } from "@downdraft/engine/shader-graph";
+// ─── Uniform structs (single source of truth for layout) ───────────────────
+const StickmanUniformsStruct = wgsl.struct("StickmanUniforms", {
+    transform: vec4f,
+    screenSize: vec2f,
+    lineWidth: f32,
+    color: vec3f,
+});
+export const STICKMAN_WGSL = /* wgsl */ `
+
+${StickmanUniformsStruct.wgsl}
+
+@group(0) @binding(0) var<uniform> u: StickmanUniforms;
+@group(0) @binding(1) var lightTex: texture_2d<f32>;
+@group(0) @binding(2) var volumetricTex: texture_2d<f32>;
+
+struct VertexInput {
+  @location(0) endpointA: vec3<f32>,
+  @location(1) endpointB: vec3<f32>,
+  @location(2) cornerVec: vec2<f32>,
+};
+
+struct VSOut {
+  @builtin(position) pos: vec4<f32>,
+  @location(0) color: vec3<f32>,
+  @location(1) worldPos: vec2<f32>,
+  @location(2) circleCenter: vec2<f32>,  // valid only for circle segments
+  @location(3) circleRadius: f32,         // > 0 for circle, 0 for line
+};
+
+fn worldToNdc(p: vec2<f32>) -> vec2<f32> {
+  return p * u.transform.xy + u.transform.zw;
+}
+
+@vertex
+fn vs_main(input: VertexInput) -> VSOut {
+  let isCircle = input.endpointB.z > 0.0;
+
+  var out: VSOut;
+  out.color = u.color;
+  out.circleCenter = vec2<f32>(0.0, 0.0);
+  out.circleRadius = 0.0;
+
+  if (isCircle) {
+    // Head circle: expand quad to bounding box (center ± radius).
+    let center = input.endpointA.xy;
+    let radius = input.endpointB.z;
+    let worldPos = center + input.cornerVec * radius;
+    let ndcPos = worldToNdc(worldPos);
+    out.pos = vec4<f32>(ndcPos, 0.0, 1.0);
+    out.worldPos = worldPos;
+    out.circleCenter = center;
+    out.circleRadius = radius;
+  } else {
+    // Line segment: extrude thick stroke.
+    let a = input.endpointA.xy;
+    let b = input.endpointB.xy;
+    let ndcA = worldToNdc(a);
+    let ndcB = worldToNdc(b);
+    let dir = normalize(ndcB - ndcA);
+    let perp = vec2<f32>(-dir.y, dir.x);
+    let halfWidthNdc = u.lineWidth * abs(u.transform.x);
+    let offset = perp * input.cornerVec.y * halfWidthNdc;
+    let t = input.cornerVec.x;
+    let ndcPos = mix(ndcA, ndcB, t) + offset;
+    out.pos = vec4<f32>(ndcPos, 0.0, 1.0);
+    out.worldPos = mix(a, b, t);
+  }
+
+  return out;
+}
+
+@fragment
+fn fs_main(in: VSOut) -> @location(0) vec4<f32> {
+  // Sample light + volumetric at the player's world position (half-res).
+  let lc = vec2<i32>(i32(in.worldPos.x) / 2, i32(in.worldPos.y) / 2);
+  let light = textureLoad(lightTex, lc, 0);
+  let vol = textureLoad(volumetricTex, lc, 0);
+  let lighting = light.rgb + vol.rgb;
+
+  if (in.circleRadius > 0.0) {
+    // Filled head disc with a soft anti-aliased rim (a thin ring read as a
+    // floating block at game zooms).
+    let dist = distance(in.worldPos, in.circleCenter);
+    let aa = 0.5;
+    let alpha = 1.0 - smoothstep(in.circleRadius - aa, in.circleRadius, dist);
+    if (alpha < 0.01) {
+      discard;
+    }
+    return vec4<f32>(in.color * lighting, alpha);
+  }
+
+  // Line segment: opaque.
+  return vec4<f32>(in.color * lighting, 1.0);
+}
+`;

package/dist/libraries/stickman/src/skeleton.js

@@ -0,0 +1,163 @@
+// Stickman skeleton computation — shared between games.
+//
+// Produces a flat list of line segments `[ax, ay, bx, by, ...]` in world-cell
+// coordinates, given a pose. The wrapper uploads these into a thick-line quad
+// vertex buffer each frame. Segment count is constant, so GPU buffers can be
+// allocated once.
+//
+// Segment types:
+//   - Line segments: endpointA = start, endpointB = end (z=0), cornerVec = (t, side)
+//   - Circle segment (head): endpointA = (cx, cy, 0), endpointB = (cx, cy, radius),
+//     cornerVec = (cornerX, cornerY) where each is ±1. The shader detects
+//     circle mode via endpointB.z > 0 and renders a perfect SDF circle ring.
+import { ARM_LEN, ARM_SWING, ELBOW_BEND, FOOT_LIFT, HEAD_CY, HEAD_R, HIP_Y, IDLE_ARM_OUT, IDLE_SWING, JUMP_ARM_SWING, JUMP_LEG_SWING, KNEE_BEND, LEG_LEN, LEG_SWING, NECK_Y, SHOULDER_Y, UPPER_LIMB_FRAC, } from "./proportions.js";
+// Segment layout: 1 head circle + 1 spine + 4 arm segs + 4 leg segs = 10.
+export const STICKMAN_SEGMENT_COUNT = 1 + 1 + 4 + 4;
+export const STICKMAN_FLOATS_PER_SEGMENT = 4;
+export const STICKMAN_SKELETON_FLOATS = STICKMAN_SEGMENT_COUNT * STICKMAN_FLOATS_PER_SEGMENT;
+/**
+ * Compute the stickman skeleton as a flat Float32Array of segment endpoints.
+ * The returned array is a fresh, exactly-sized buffer; reuse it via the
+ * optional `out` argument to avoid per-frame allocation.
+ *
+ * Segment 0 is the head circle: [centerX, centerY, centerX, centerY + radius*0].
+ * The thick-line builder encodes the radius in endpointB.z (see thick-line.ts).
+ */
+export function computeSkeleton(pose, out) {
+    const seg = out && out.length >= STICKMAN_SKELETON_FLOATS ? out : new Float32Array(STICKMAN_SKELETON_FLOATS);
+    const { cx, topY, facing: f, animFrame, vx, onGround } = pose;
+    const headCx = cx;
+    const headCy = topY + HEAD_CY;
+    const neckX = cx, neckY = topY + NECK_Y;
+    const hipX = cx, hipY = topY + HIP_Y;
+    const shoulderX = cx, shoulderY = topY + SHOULDER_Y;
+    // --- Pose / swing ---
+    const moving = Math.abs(vx) > 0.01;
+    const inAir = !onGround;
+    const t = animFrame * 0.25;
+    const s = Math.sin(t);
+    let legSwingL, legSwingR, armSwingL, armSwingR;
+    let liftL, liftR;
+    // Bend amounts scale with pose: 0 at idle (straight limbs), dynamic during
+    // walk (more bend when foot is lifted), 1 during jump.
+    let kneeBendL, kneeBendR;
+    let elbowBendL, elbowBendR;
+    // At idle the hands rest slightly outward from the body center.
+    let armOutL, armOutR;
+    // Body bob: vertical offset during walk (whole skeleton dips and rises).
+    let bodyBob;
+    if (inAir) {
+        // Jump: legs apart + tucked, arms out.
+        legSwingL = JUMP_LEG_SWING;
+        legSwingR = -JUMP_LEG_SWING;
+        armSwingL = -JUMP_ARM_SWING;
+        armSwingR = JUMP_ARM_SWING;
+        liftL = FOOT_LIFT * 0.6;
+        liftR = FOOT_LIFT * 0.6;
+        kneeBendL = 1;
+        kneeBendR = 1;
+        elbowBendL = 1;
+        elbowBendR = 1;
+        armOutL = 0;
+        armOutR = 0;
+        bodyBob = 0;
+    }
+    else if (moving) {
+        legSwingL = s * LEG_SWING;
+        legSwingR = -s * LEG_SWING;
+        armSwingL = -s * ARM_SWING;
+        armSwingR = s * ARM_SWING;
+        // Lift each foot during its forward swing phase.
+        const liftPhaseL = Math.max(0, s);
+        const liftPhaseR = Math.max(0, -s);
+        liftL = liftPhaseL * FOOT_LIFT;
+        liftR = liftPhaseR * FOOT_LIFT;
+        // Knee bends more when the foot is lifted, straightens when planted.
+        kneeBendL = liftPhaseL;
+        kneeBendR = liftPhaseR;
+        // Elbows bend slightly and constantly during walk.
+        elbowBendL = 0.5;
+        elbowBendR = 0.5;
+        armOutL = 0;
+        armOutR = 0;
+        // Body bobs up when a foot is lifted (mid-step), dips when both feet are near ground.
+        bodyBob = (liftPhaseL + liftPhaseR) * 0.15;
+    }
+    else {
+        // Idle: gentle breathing sway, straight legs, arms resting outward.
+        const idle = Math.sin(animFrame * 0.05) * IDLE_SWING;
+        legSwingL = idle;
+        legSwingR = -idle;
+        armSwingL = -idle;
+        armSwingR = idle;
+        liftL = 0;
+        liftR = 0;
+        kneeBendL = 0;
+        kneeBendR = 0;
+        elbowBendL = 0;
+        elbowBendR = 0;
+        armOutL = -IDLE_ARM_OUT + idle;
+        armOutR = IDLE_ARM_OUT - idle;
+        bodyBob = 0;
+    }
+    // Apply body bob to the whole skeleton (shifts all joints up by bodyBob).
+    const bobY = -bodyBob; // negative = up (Y increases downward)
+    const headCyB = headCy + bobY;
+    const neckYB = neckY + bobY;
+    const shoulderYB = shoulderY + bobY;
+    const hipYB = hipY + bobY;
+    // --- Limb joints ---
+    const upperLegLen = LEG_LEN * UPPER_LIMB_FRAC;
+    const upperArmLen = ARM_LEN * UPPER_LIMB_FRAC;
+    // Knees: on the hip->foot line when bend=0 (straight leg); biased forward
+    // by KNEE_BEND when bend>0 (walk/jump). The knee X interpolates between
+    // the hip X (straight) and the foot X (fully bent forward).
+    const kneeLx = cx + legSwingL * f * UPPER_LIMB_FRAC + KNEE_BEND * f * kneeBendL;
+    const kneeLy = hipYB + upperLegLen;
+    const kneeRx = cx + legSwingR * f * UPPER_LIMB_FRAC - KNEE_BEND * f * kneeBendR;
+    const kneeRy = hipYB + upperLegLen;
+    const footLx = cx + legSwingL * f;
+    const footLy = hipYB + LEG_LEN - liftL;
+    const footRx = cx + legSwingR * f;
+    const footRy = hipYB + LEG_LEN - liftR;
+    // Hands + elbows.
+    const handLx = cx + armSwingL * f + armOutL;
+    const handLy = shoulderYB + ARM_LEN;
+    const handRx = cx + armSwingR * f + armOutR;
+    const handRy = shoulderYB + ARM_LEN;
+    const elbowLx = cx + armSwingL * f * UPPER_LIMB_FRAC + armOutL * UPPER_LIMB_FRAC - ELBOW_BEND * f * elbowBendL;
+    const elbowLy = shoulderYB + upperArmLen;
+    const elbowRx = cx + armSwingR * f * UPPER_LIMB_FRAC + armOutR * UPPER_LIMB_FRAC + ELBOW_BEND * f * elbowBendR;
+    const elbowRy = shoulderYB + upperArmLen;
+    // --- Emit segments ---
+    let i = 0;
+    const push = (ax, ay, bx, by) => {
+        seg[i++] = ax;
+        seg[i++] = ay;
+        seg[i++] = bx;
+        seg[i++] = by;
+    };
+    // Head circle: encoded as [centerX, centerY, centerX, centerY].
+    // The thick-line builder puts the radius in endpointB.z (see thick-line.ts).
+    push(headCx, headCyB, headCx, headCyB);
+    // Spine (neck -> hip).
+    push(neckX, neckYB, hipX, hipYB);
+    // Arms: shoulder -> elbow -> hand (2 segments each).
+    push(shoulderX, shoulderYB, elbowLx, elbowLy);
+    push(elbowLx, elbowLy, handLx, handLy);
+    push(shoulderX, shoulderYB, elbowRx, elbowRy);
+    push(elbowRx, elbowRy, handRx, handRy);
+    // Legs: hip -> knee -> foot (2 segments each).
+    push(hipX, hipYB, kneeLx, kneeLy);
+    push(kneeLx, kneeLy, footLx, footLy);
+    push(hipX, hipYB, kneeRx, kneeRy);
+    push(kneeRx, kneeRy, footRx, footRy);
+    return seg;
+}
+/**
+ * Get the head circle radius (used by the thick-line builder to encode it
+ * in the vertex data).
+ */
+export function getHeadRadius() {
+    return HEAD_R;
+}

package/dist/libraries/stickman/src/stickman-pass.js

@@ -0,0 +1,210 @@
+// ============================================================================
+// StickmanPass — shared render pass that draws a stickman player avatar as
+// thick lines, lit by the game's light/volumetric textures.
+//
+// Generalized from the falling-sand + mining-rpg copies. Viewport is set
+// separately from the per-frame pose:
+//   - setGridViewport(gridW, gridH): cell coords -> NDC across the whole
+//     canvas (falling-sand — grid fills the screen).
+//   - setCameraViewport(camX, camY, zoom, canvasW, canvasH): pan/zoom camera
+//     (mining-rpg).
+//
+// Bindings: 0 = uniforms, 1 = light accumulation texture, 2 = volumetric
+// texture. Unset light bindings default to a 1×1 white dummy (identity
+// lighting).
+// ============================================================================
+import { createValidatedShaderModule } from "@downdraft/engine";
+import { f32, vec2f, vec3f, vec4f, wgsl } from "@downdraft/engine/shader-graph";
+import { DEFAULT_LINE_WIDTH } from "./proportions.js";
+import { STICKMAN_WGSL } from "./shader.js";
+import { computeSkeleton } from "./skeleton.js";
+import { buildThickLineIndices, buildThickLineVertices, STICKMAN_INDEX_COUNT, STICKMAN_VERTEX_COUNT, STICKMAN_VERTEX_STRIDE, } from "./thick-line.js";
+// ─── Uniform struct (must match StickmanUniforms in STICKMAN_WGSL) ──────────
+const StickmanUniformsStruct = wgsl.struct("StickmanUniforms", {
+    transform: vec4f,
+    screenSize: vec2f,
+    lineWidth: f32,
+    color: vec3f,
+});
+const UNIFORM_SIZE = StickmanUniformsStruct.size;
+const UNIFORM_FLOATS = StickmanUniformsStruct.floatCount;
+export class StickmanPass {
+    device;
+    format;
+    pipeline = null;
+    bindGroupLayout = null;
+    bindGroup = null;
+    uniformBuffer = null;
+    vertexBuffer = null;
+    indexBuffer = null;
+    lightView = null;
+    volumetricView = null;
+    dummyTexture = null;
+    dummyView = null;
+    // Current viewport transform (set via setGridViewport/setCameraViewport).
+    transform = new Float32Array(4); // scaleX, scaleY, offX, offY
+    screenSize = new Float32Array([1, 1]);
+    // Preallocated uniform buffer (avoid per-frame allocation)
+    _uniformBuf = null;
+    _uniformView = null;
+    // Reused each frame to avoid allocation.
+    skeleton;
+    geom;
+    constructor(config) {
+        this.device = config.device;
+        this.format = config.format;
+        this.skeleton = new Float32Array(0);
+        this.geom = { vertices: new Float32Array(0), indices: new Uint16Array(0), vertexCount: 0, indexCount: 0 };
+    }
+    init() {
+        this.uniformBuffer = this.device.createBuffer({
+            size: UNIFORM_SIZE,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        this._uniformBuf = new Float32Array(UNIFORM_FLOATS);
+        this._uniformView = StickmanUniformsStruct.view(this._uniformBuf);
+        // 1x1 dummy white texture for the light/volumetric bindings (before the
+        // real views are set each frame). Lighting becomes identity (white).
+        this.dummyTexture = this.device.createTexture({
+            size: [1, 1],
+            format: "rgba8unorm",
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+        });
+        this.dummyView = this.dummyTexture.createView();
+        this.device.queue.writeTexture({ texture: this.dummyTexture }, new Uint8Array([255, 255, 255, 255]), { bytesPerRow: 4, rowsPerImage: 1 }, [1, 1]);
+        // Static-size vertex buffer (rewritten each frame) + static index buffer.
+        this.vertexBuffer = this.device.createBuffer({
+            size: STICKMAN_VERTEX_COUNT * STICKMAN_VERTEX_STRIDE,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+        const indices = buildThickLineIndices();
+        this.indexBuffer = this.device.createBuffer({
+            size: indices.byteLength,
+            usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
+        });
+        this.device.queue.writeBuffer(this.indexBuffer, 0, indices);
+        const shader = createValidatedShaderModule(this.device, { code: STICKMAN_WGSL, label: "StickmanPass" });
+        this.bindGroupLayout = this.device.createBindGroupLayout({
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
+                { binding: 1, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
+                { binding: 2, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
+            ],
+        });
+        const pipelineLayout = this.device.createPipelineLayout({
+            bindGroupLayouts: [this.bindGroupLayout],
+        });
+        this.pipeline = this.device.createRenderPipeline({
+            layout: pipelineLayout,
+            vertex: {
+                module: shader,
+                entryPoint: "vs_main",
+                buffers: [{
+                        arrayStride: STICKMAN_VERTEX_STRIDE,
+                        attributes: [
+                            { shaderLocation: 0, offset: 0, format: "float32x3" }, // endpointA
+                            { shaderLocation: 1, offset: 12, format: "float32x3" }, // endpointB
+                            { shaderLocation: 2, offset: 24, format: "float32x2" }, // cornerVec
+                        ],
+                    }],
+            },
+            fragment: { module: shader, entryPoint: "fs_main", targets: [{ format: this.format }] },
+            primitive: { topology: "triangle-list" },
+        });
+        this.createBindGroup();
+    }
+    createBindGroup() {
+        if (!this.bindGroupLayout || !this.uniformBuffer || !this.dummyView)
+            return;
+        const lView = this.lightView ?? this.dummyView;
+        const vView = this.volumetricView ?? this.dummyView;
+        this.bindGroup = this.device.createBindGroup({
+            layout: this.bindGroupLayout,
+            entries: [
+                { binding: 0, resource: { buffer: this.uniformBuffer } },
+                { binding: 1, resource: lView },
+                { binding: 2, resource: vView },
+            ],
+        });
+    }
+    /** Set the light accumulation texture view (binding 1). */
+    setLightTexture(view) {
+        if (this.lightView === view)
+            return;
+        this.lightView = view;
+        this.createBindGroup();
+    }
+    /** Set the volumetric light texture view (binding 2). */
+    setVolumetricTexture(view) {
+        if (this.volumetricView === view)
+            return;
+        this.volumetricView = view;
+        this.createBindGroup();
+    }
+    /** Grid-fills-canvas viewport: cell coords → NDC across the whole canvas. */
+    setGridViewport(gridW, gridH) {
+        this.transform[0] = 2 / gridW;
+        this.transform[1] = -2 / gridH;
+        this.transform[2] = -1;
+        this.transform[3] = 1;
+        this.screenSize[0] = gridW;
+        this.screenSize[1] = gridH;
+    }
+    /** Pan/zoom camera viewport: world cell coords → NDC. */
+    setCameraViewport(camX, camY, zoom, canvasW, canvasH) {
+        const scaleX = (zoom * 2) / canvasW;
+        const scaleY = (-zoom * 2) / canvasH;
+        this.transform[0] = scaleX;
+        this.transform[1] = scaleY;
+        this.transform[2] = -camX * scaleX;
+        this.transform[3] = -camY * scaleY;
+        this.screenSize[0] = canvasW;
+        this.screenSize[1] = canvasH;
+    }
+    update(state) {
+        if (!this.vertexBuffer || !this.uniformBuffer)
+            return;
+        // --- Skeleton -> thick-line vertices ---
+        this.skeleton = computeSkeleton({ cx: state.cx, topY: state.topY, facing: state.facing, animFrame: state.animFrame, vx: state.vx, onGround: state.onGround }, this.skeleton);
+        this.geom = buildThickLineVertices(this.skeleton, this.geom);
+        this.device.queue.writeBuffer(this.vertexBuffer, 0, this.geom.vertices);
+        // --- Color: health gradient (red -> yellow -> green) ---
+        const hp = Math.max(0, Math.min(1, state.health / 100));
+        let r, g, b;
+        if (hp > 0.5) {
+            const t = (hp - 0.5) * 2;
+            r = 1.0 - t;
+            g = 0.85 + (1.0 - 0.85) * t;
+            b = 0.2 * t;
+        }
+        else {
+            const t = hp * 2;
+            r = 1.0;
+            g = 0.85 * t;
+            b = 0.0;
+        }
+        const view = this._uniformView;
+        view.set("transform", [this.transform[0], this.transform[1], this.transform[2], this.transform[3]]);
+        view.set("screenSize", [this.screenSize[0], this.screenSize[1]]);
+        view.set("lineWidth", DEFAULT_LINE_WIDTH);
+        view.set("color", [r, g, b]);
+        this.device.queue.writeBuffer(this.uniformBuffer, 0, this._uniformBuf);
+    }
+    render(pass) {
+        if (!this.pipeline || !this.bindGroup || !this.vertexBuffer || !this.indexBuffer)
+            return;
+        pass.setPipeline(this.pipeline);
+        pass.setBindGroup(0, this.bindGroup);
+        pass.setVertexBuffer(0, this.vertexBuffer);
+        pass.setIndexBuffer(this.indexBuffer, "uint16");
+        pass.drawIndexed(STICKMAN_INDEX_COUNT);
+    }
+    destroy() {
+        this.uniformBuffer?.destroy();
+        this.vertexBuffer?.destroy();
+        this.indexBuffer?.destroy();
+        this.dummyTexture?.destroy();
+        this._uniformBuf = null;
+        this._uniformView = null;
+    }
+}