@downdraft/engine 0.0.0 → 0.1.1

package/libraries/stickman/README.md

@@ -0,0 +1,25 @@
+# `@downdraft/engine/libraries/stickman`
+
+Stickman/figure animation helpers — procedural character figures for prototyping and tests.
+
+## Install
+
+```sh
+bun add @downdraft/engine/libraries/stickman
+```
+
+## Key exports
+
+- `ARM_LEN`
+- `ARM_SWING`
+- `DEFAULT_LINE_WIDTH`
+- `ELBOW_BEND`
+- `FOOT_LIFT`
+- `HEAD_CY`
+- `HEAD_R`
+- `HEAD_SEGMENTS`
+- `HIP_Y`
+- `IDLE_ARM_OUT`
+- …and 25 more
+
+See the [Downdraft engine repository](https://github.com/knackstedt/downdraft) for architecture docs and examples.

package/libraries/stickman/src/index.ts

@@ -0,0 +1,25 @@
+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";
+
+export {
+    computeSkeleton, getHeadRadius, STICKMAN_FLOATS_PER_SEGMENT, STICKMAN_SEGMENT_COUNT, STICKMAN_SKELETON_FLOATS, type StickmanPose
+} from "./skeleton";
+
+export {
+    buildThickLineIndices,
+    buildThickLineVertices, STICKMAN_INDEX_COUNT, STICKMAN_VERTEX_COUNT, STICKMAN_VERTEX_STRIDE, type ThickLineGeometry
+} from "./thick-line";
+
+export { STICKMAN_WGSL } from "./shader";
+
+export { StickmanPass } from "./stickman-pass";
+export type { StickmanDrawState } from "./stickman-pass";
+
+// Declarative library descriptor
+export { StickmanLib, StickmanTok } from "./library";
+export type { StickmanLibConfig } from "./library";
+

package/libraries/stickman/src/library.ts

@@ -0,0 +1,61 @@
+// ============================================================================
+// 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, type EngineLibrary } from "@downdraft/engine";
+import { computeSkeleton } from "./skeleton";
+
+// ── Config ──
+
+export interface StickmanLibConfig {
+  // Stickman is a pure computation utility — no runtime config needed.
+  // Config slot reserved for future options (e.g. custom proportions).
+}
+
+// ── Typed tokens (DI) ──
+
+/** Token for the sim-side stickman skeleton computation function. */
+export const StickmanTok = resourceToken<typeof computeSkeleton>("stickman:skeleton");
+
+// ── Descriptor ──
+
+export const StickmanLib: EngineLibrary<StickmanLibConfig> = {
+  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/libraries/stickman/src/proportions.ts

@@ -0,0 +1,45 @@
+// 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/libraries/stickman/src/shader.ts

@@ -0,0 +1,117 @@
+// 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 type { WgslStruct } from "@downdraft/engine/shader-graph";
+import { f32, vec2f, vec3f, vec4f, wgsl } from "@downdraft/engine/shader-graph";
+
+// ─── Uniform structs (single source of truth for layout) ───────────────────
+const StickmanUniformsStruct: WgslStruct = 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/libraries/stickman/src/skeleton.ts

@@ -0,0 +1,197 @@
+// 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";
+
+export interface StickmanPose {
+  /** player center X in world cell coords */
+  cx: number;
+  /** player top-of-bounding-box Y in world cell coords (increases downward) */
+  topY: number;
+  /** 1 = facing right, -1 = facing left */
+  facing: number;
+  /** animation frame counter (ticks) */
+  animFrame: number;
+  /** horizontal velocity (cells/tick) — drives walk vs idle */
+  vx: number;
+  /** true if the player is on the ground */
+  onGround: boolean;
+}
+
+// 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: StickmanPose, out?: Float32Array): Float32Array {
+  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: number, legSwingR: number, armSwingL: number, armSwingR: number;
+  let liftL: number, liftR: number;
+  // Bend amounts scale with pose: 0 at idle (straight limbs), dynamic during
+  // walk (more bend when foot is lifted), 1 during jump.
+  let kneeBendL: number, kneeBendR: number;
+  let elbowBendL: number, elbowBendR: number;
+  // At idle the hands rest slightly outward from the body center.
+  let armOutL: number, armOutR: number;
+  // Body bob: vertical offset during walk (whole skeleton dips and rises).
+  let bodyBob: number;
+
+  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: number, ay: number, bx: number, by: number) => {
+    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(): number {
+  return HEAD_R;
+}