@downdraft/engine 0.1.0 → 0.1.2-alpha.5

package/dist/libraries/postfx/src/shaders/post-process/watercolor.wgsl

@@ -0,0 +1,82 @@
+// wgsl-validate: prelude ./fullscreen-vs.wgsl
+// wgsl-validate: prelude ./occluder-chunk.wgsl
+// Watercolor — stylized edge-aware smoothing + paper texture blend.
+// Combines a soft bilateral-like smoothing with edge enhancement and a
+// subtle paper grain overlay for a hand-painted watercolor look.
+struct U {
+  texelSize: vec2<f32>,
+  edgeStrength: f32,   // edge enhancement intensity (0–2)
+  paperScale: f32,     // paper texture scale (1–10)
+  blend: f32,          // watercolor blend amount (0–1)
+  _p0: f32,
+  _p1: f32,
+  _p2: f32,
+  _p3: f32,
+};
+@group(0) @binding(0) var colorTex: texture_2d<f32>;
+@group(0) @binding(1) var noiseTex: texture_2d<f32>;
+@group(0) @binding(2) var samp: sampler;
+@group(0) @binding(3) var<uniform> u: U;
+
+// Hash for procedural paper texture
+fn hash(p: vec2<f32>) -> f32 {
+  let h = dot(p, vec2<f32>(127.1, 311.7));
+  return fract(sin(h) * 43758.5453);
+}
+
+fn noise2D(p: vec2<f32>) -> f32 {
+  let i = floor(p);
+  let f = fract(p);
+  let a = hash(i);
+  let b = hash(i + vec2<f32>(1.0, 0.0));
+  let c = hash(i + vec2<f32>(0.0, 1.0));
+  let d = hash(i + vec2<f32>(1.0, 1.0));
+  let u = f * f * (3.0 - 2.0 * f);
+  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);
+}
+
+@fragment
+fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
+  if (isOccluded(input.uv)) { discard; }
+  let uv = input.uv;
+  let ts = u.texelSize;
+  let color = textureSample(colorTex, samp, uv).rgb;
+
+  // ── Edge-aware smoothing: 3x3 weighted blur (edge-preserving) ──
+  let tl = textureSample(colorTex, samp, uv + vec2<f32>(-1.0, -1.0) * ts).rgb;
+  let tr = textureSample(colorTex, samp, uv + vec2<f32>( 1.0, -1.0) * ts).rgb;
+  let bl = textureSample(colorTex, samp, uv + vec2<f32>(-1.0,  1.0) * ts).rgb;
+  let br = textureSample(colorTex, samp, uv + vec2<f32>( 1.0,  1.0) * ts).rgb;
+  let l = textureSample(colorTex, samp, uv + vec2<f32>(-1.0,  0.0) * ts).rgb;
+  let r = textureSample(colorTex, samp, uv + vec2<f32>( 1.0,  0.0) * ts).rgb;
+  let t = textureSample(colorTex, samp, uv + vec2<f32>( 0.0, -1.0) * ts).rgb;
+  let b = textureSample(colorTex, samp, uv + vec2<f32>( 0.0,  1.0) * ts).rgb;
+
+  // Edge weight: closer colors get more weight (bilateral-like)
+  let centerLuma = dot(color, vec3<f32>(0.299, 0.587, 0.114));
+  let neighbors = array<vec3<f32>, 8>(tl, tr, bl, br, l, r, t, b);
+  var smoothColor = vec3<f32>(0.0);
+  var totalWeight = 0.0;
+  for (var i = 0u; i < 8u; i = i + 1u) {
+    let nl = dot(neighbors[i], vec3<f32>(0.299, 0.587, 0.114));
+    let w = exp(-abs(centerLuma - nl) * 5.0);
+    smoothColor += neighbors[i] * w;
+    totalWeight += w;
+  }
+  smoothColor = (smoothColor + color * 2.0) / (totalWeight + 2.0);
+
+  // ── Edge enhancement (Sobel) ──
+  let gx = abs(dot(tr + 2.0 * r + br - tl - 2.0 * l - bl, vec3<f32>(0.299, 0.587, 0.114)));
+  let gy = abs(dot(bl + 2.0 * b + br - tl - 2.0 * t - tr, vec3<f32>(0.299, 0.587, 0.114)));
+  let edge = sqrt(gx * gx + gy * gy);
+  let edgeFactor = 1.0 - clamp(edge * u.edgeStrength, 0.0, 1.0);
+
+  // ── Paper texture ──
+  let paperUV = uv * u.paperScale * 50.0;
+  let paper = noise2D(paperUV) * 0.15 + 0.85;
+
+  // ── Combine: smoothed color darkened at edges, multiplied by paper texture ──
+  let watercolor = smoothColor * edgeFactor * paper;
+  let result = mix(color, watercolor, u.blend);
+  return vec4<f32>(result, 1.0);
+}

package/dist/libraries/postfx/src/shaders/post-process/white-balance.wgsl

@@ -0,0 +1,41 @@
+// wgsl-validate: prelude ./fullscreen-vs.wgsl
+// wgsl-validate: prelude ./occluder-chunk.wgsl
+// White balance — temperature (K) + tint adjustment.
+// Applies a white-balance correction by shifting the color temperature
+// (warm/cool) and tint (green/magenta).
+struct U {
+  temperature: f32,   // -1.0 (cool) to 1.0 (warm), 0 = neutral
+  tint: f32,          // -1.0 (green) to 1.0 (magenta), 0 = neutral
+  _p0: f32,
+  _p1: f32,
+  _p2: f32,
+  _p3: f32,
+  _p4: f32,
+  _p5: f32,
+};
+@group(0) @binding(0) var colorTex: texture_2d<f32>;
+@group(0) @binding(1) var dummyTex: texture_2d<f32>;
+@group(0) @binding(2) var samp: sampler;
+@group(0) @binding(3) var<uniform> u: U;
+
+@fragment
+fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
+  if (isOccluded(input.uv)) { discard; }
+  let uv = input.uv;
+  var color = textureSample(colorTex, samp, uv).rgb;
+
+  // Temperature: shift warm (R+ B-) or cool (R- B+)
+  let tempR = 1.0 + u.temperature * 0.1;
+  let tempB = 1.0 - u.temperature * 0.1;
+  // Tint: shift green (G+) or magenta (G-)
+  let tintG = 1.0 - u.tint * 0.1;
+
+  color = color * vec3<f32>(tempR, tintG, tempB);
+
+  // Normalize luminance to avoid overall brightness shift
+  let luma = dot(color, vec3<f32>(0.299, 0.587, 0.114));
+  let origLuma = dot(textureSample(colorTex, samp, uv).rgb, vec3<f32>(0.299, 0.587, 0.114));
+  color = color * (origLuma / max(luma, 0.0001));
+
+  return vec4<f32>(color, 1.0);
+}

package/dist/libraries/recast/src/backend.js

@@ -0,0 +1,124 @@
+// ============================================================================
+// RecastBackend — WASM loader + navmesh generation/query wrapper
+//
+// Mirrors the loadPhysicsLib() pattern from @downdraft/engine/libraries/physics-rapier:
+//   - cached + coalesced async load (hot-reload/dispose cycles can retry)
+//   - WASM import isolated to one module so the rest of the library stays
+//     WASM-agnostic and testable.
+//
+// recast-navigation ships as ESM with the .wasm loaded via
+// `new URL(..., import.meta.url)`. It must be excluded from Vite dep
+// pre-bundling (see packages/engine/app/src/vite/index.ts optimizeDeps.exclude).
+// ============================================================================
+import { createLogger } from "@downdraft/engine";
+const log = createLogger();
+let cachedModule = null;
+let cachedGenerators = null;
+let loadingPromise = null;
+/**
+ * Loads + initializes the recast-navigation WASM module. Idempotent after the
+ * first successful call (recast's `init()` also short-circuits if already
+ * initialized). Concurrent callers share the in-flight load; a failed load
+ * clears the promise so a retry is possible (important for dev hot-reload).
+ */
+export function loadRecastLib() {
+    if (cachedModule)
+        return Promise.resolve(cachedModule);
+    if (loadingPromise)
+        return loadingPromise;
+    const p = doLoadRecastLib();
+    loadingPromise = p;
+    p.then(() => { if (loadingPromise === p)
+        loadingPromise = null; })
+        .catch(() => { if (loadingPromise === p)
+        loadingPromise = null; });
+    return p;
+}
+async function doLoadRecastLib() {
+    const mod = await import("recast-navigation");
+    await mod.init();
+    cachedModule = mod;
+    cachedGenerators = await import("recast-navigation/generators");
+    log.info("recast", "recast-navigation WASM initialized");
+    return cachedModule;
+}
+/** Returns the generators submodule (generateSoloNavMesh, etc.). */
+export function getRecastGenerators() {
+    if (!cachedGenerators)
+        throw new Error("recast-navigation not loaded. Call loadRecastLib() first.");
+    return cachedGenerators;
+}
+// ── RecastBackend ──
+/**
+ * Wraps a generated recast {@link NavMesh} + a {@link NavMeshQuery}. Created
+ * by {@link RecastLib.sim.create} and exposed via the {@link RecastNavMeshTok}
+ * DI token. Games call `buildNavMesh(positions, indices, config)` once
+ * (typically in `onReady`) to populate the mesh from terrain/level geometry.
+ */
+export class RecastBackend {
+    mod = null;
+    navMesh = null;
+    query = null;
+    destroyed = false;
+    /** Asynchronously loads the WasM module. Must be called before buildNavMesh. */
+    async init() {
+        if (this.mod)
+            return;
+        this.mod = await loadRecastLib();
+    }
+    ensureMod() {
+        if (!this.mod || this.destroyed) {
+            throw new Error("RecastBackend not initialized or destroyed. Call init() first.");
+        }
+        return this.mod;
+    }
+    /**
+     * Builds a solo (single-tile) navmesh from triangle input.
+     *
+     * @param positions flat array of vertex positions: [x0,y0,z0, x1,y1,z1, ...]
+     * @param indices   flat array of triangle indices: [i0,i1,i2, i3,i4,i5, ...]
+     * @param config    optional recast generation config (cell size, agent
+     *                  radius, walkable slope, etc.)
+     * @returns `true` on success. On failure, logs the recast error + returns false.
+     */
+    buildNavMesh(positions, indices, config) {
+        this.ensureMod(); // ensures WASM is loaded
+        const generators = getRecastGenerators();
+        const result = generators.generateSoloNavMesh(positions, indices, config);
+        if (!result.success) {
+            log.error("recast", `generateSoloNavMesh failed: ${result.error}`);
+            return false;
+        }
+        this.navMesh = result.navMesh;
+        this.query = new this.mod.NavMeshQuery(this.navMesh);
+        return true;
+    }
+    /** The generated navmesh. Throws if buildNavMesh hasn't succeeded. */
+    getNavMesh() {
+        if (!this.navMesh)
+            throw new Error("RecastBackend: navmesh not built. Call buildNavMesh() first.");
+        return this.navMesh;
+    }
+    /** A NavMeshQuery over the built navmesh. Throws if not built. */
+    getQuery() {
+        if (!this.query)
+            throw new Error("RecastBackend: navmesh not built. Call buildNavMesh() first.");
+        return this.query;
+    }
+    /** Whether buildNavMesh has succeeded and the mesh is usable. */
+    isBuilt() {
+        return this.navMesh !== null;
+    }
+    /** The loaded recast-navigation module (for Crowd construction etc.). */
+    getModule() {
+        return this.ensureMod();
+    }
+    /** Releases the navmesh + query. The WASM module itself stays cached. */
+    destroy() {
+        this.destroyed = true;
+        // recast NavMesh/NavMeshQuery are GC'd; no explicit destroy on the JS wrappers.
+        this.navMesh = null;
+        this.query = null;
+        this.mod = null;
+    }
+}

package/dist/libraries/recast/src/crowd-system.js

@@ -0,0 +1,310 @@
+// ============================================================================
+// RecastCrowdSystem — ECS-integrated wrapper over recast-navigation's Crowd
+//
+// Mirrors the structure of @downdraft/engine/libraries/navmesh's CrowdSystem but uses
+// recast's WASM Crowd (real RVO avoidance + Detour pathfollowing) instead of
+// the hand-rolled boids steering. Defines its own RecastAgent component so
+// the two navmesh libraries can coexist without ECS schema coupling.
+// ============================================================================
+import { Component } from "@downdraft/engine/ecs/component";
+import { Stage, system } from "@downdraft/engine/ecs/system";
+import { PhysicsTransform } from "@downdraft/engine/physics/body";
+// ── ECS component ──
+export const RecastAgent = Component.register("RecastAgent", {
+    agentId: -1,
+    radius: 0.5,
+    height: 1.8,
+    maxSpeed: 3.5,
+    maxAcceleration: 10,
+    target: null,
+    state: "idle",
+    velocity: [0, 0, 0],
+});
+/**
+ * Wraps a recast-navigation {@link Crowd}. Created by the {@link RecastLib}
+ * descriptor and exposed via {@link RecastCrowdTok}. Games register it with
+ * their ECS world via {@link register}, then add agents with {@link addAgent}
+ * and steer them with {@link setTarget}.
+ *
+ * Each tick the system calls `crowd.update(dt)` then writes agent
+ * position/velocity back into the ECS `RecastAgent` + `PhysicsTransform`
+ * components (mirroring the read-back pattern in library-navmesh's
+ * CrowdSystem).
+ */
+export class RecastCrowdSystem {
+    backend;
+    config;
+    crowd = null;
+    world = null;
+    query = null;
+    /** entity.index → recast CrowdAgent index, for write-back during tick. */
+    entityToAgent = new Map();
+    /** Per-agent stuck-detection state, keyed by recast agent index. */
+    stuckState = new Map();
+    // Resolved config (defaults applied once).
+    stuckTimeout;
+    stuckMoveEpsilon;
+    arrivalDistance;
+    reachabilityTolerance;
+    constructor(backend, config) {
+        this.backend = backend;
+        this.config = config;
+        this.stuckTimeout = config.stuckTimeout ?? 2;
+        this.stuckMoveEpsilon = config.stuckMoveEpsilon ?? 0.05;
+        this.arrivalDistance = config.arrivalDistance ?? 0.5;
+        this.reachabilityTolerance = config.reachabilityTolerance ?? 1.5;
+    }
+    /**
+     * Lazily creates the recast Crowd. The Crowd requires a built NavMesh, so
+     * this is called from {@link register} (after the game has built the mesh)
+     * or explicitly by the game once the mesh is ready.
+     */
+    ensureCrowd() {
+        if (this.crowd)
+            return this.crowd;
+        const mod = this.backend.getModule();
+        const navMesh = this.backend.getNavMesh();
+        this.crowd = new mod.Crowd(navMesh, {
+            maxAgents: this.config.maxAgents,
+            maxAgentRadius: this.config.maxAgentRadius,
+        });
+        return this.crowd;
+    }
+    /**
+     * Registers the per-tick crowd update system with the ECS world.
+     * @param world  the ECS world
+     * @param query  a query over `[RecastAgent, PhysicsTransform]`
+     */
+    register(world, query) {
+        this.world = world;
+        this.query = query;
+        const crowdSys = system("recast-crowd-agents", Stage.Update, (ctx) => {
+            if (!this.query)
+                return;
+            const crowd = this.crowd;
+            if (!crowd)
+                return; // mesh not built yet — no-op until ensureCrowd runs
+            crowd.update(ctx.dt);
+            this.query.iterate(ctx.tick, (entity, components) => {
+                const agent = components[0];
+                const transform = components[1];
+                const agentIdx = this.entityToAgent.get(entity.index);
+                if (agentIdx === undefined)
+                    return;
+                const crowdAgent = crowd.getAgent(agentIdx);
+                if (!crowdAgent)
+                    return;
+                const pos = crowdAgent.position();
+                transform.position[0] = pos.x;
+                transform.position[1] = pos.y;
+                transform.position[2] = pos.z;
+                const vel = crowdAgent.velocity();
+                agent.velocity[0] = vel.x;
+                agent.velocity[1] = vel.y;
+                agent.velocity[2] = vel.z;
+                // State heuristic: arrived when within arrivalDistance of the
+                // (snapped) target; otherwise seeking, with stuck detection as a
+                // backstop for agents that make no progress (e.g. target on an
+                // unreachable navmesh island, or wedged against geometry).
+                if (agent.target) {
+                    const dx = agent.target[0] - pos.x;
+                    const dz = agent.target[2] - pos.z;
+                    const distSq = dx * dx + dz * dz;
+                    if (distSq < this.arrivalDistance * this.arrivalDistance) {
+                        agent.state = "arrived";
+                        this.stuckState.delete(agentIdx);
+                    }
+                    else {
+                        this.updateStuckState(agentIdx, agent, [pos.x, pos.y, pos.z], ctx.dt);
+                    }
+                }
+                else {
+                    this.stuckState.delete(agentIdx);
+                }
+            });
+        }, { queries: [query] });
+        world.schedule.add(crowdSys);
+    }
+    /**
+     * Adds an agent to the crowd. Reads the entity's current `PhysicsTransform`
+     * position as the spawn point. Stores the recast agent index on the
+     * `RecastAgent` component and in the entity→agent map.
+     */
+    addAgent(entity, params) {
+        if (!this.world)
+            throw new Error("RecastCrowdSystem not registered with a world.");
+        const crowd = this.ensureCrowd();
+        const transform = this.world.getComponent(entity, PhysicsTransform.id);
+        const pos = transform?.position ?? [0, 0, 0];
+        const crowdAgent = crowd.addAgent({ x: pos[0], y: pos[1], z: pos[2] }, {
+            radius: params?.radius ?? 0.5,
+            height: params?.height ?? 1.8,
+            maxAcceleration: params?.maxAcceleration ?? 10,
+            maxSpeed: params?.maxSpeed ?? 3.5,
+            collisionQueryRange: params?.collisionQueryRange ?? 2.5,
+            pathOptimizationRange: params?.pathOptimizationRange ?? 0,
+            separationWeight: params?.separationWeight ?? 0,
+            updateFlags: params?.updateFlags ?? 7,
+            obstacleAvoidanceType: params?.obstacleAvoidanceType ?? 0,
+            queryFilterType: params?.queryFilterType ?? 0,
+        });
+        const agentIdx = crowdAgent.agentIndex;
+        const agent = this.world.getComponent(entity, RecastAgent.id);
+        if (agent) {
+            agent.agentId = agentIdx;
+            agent.radius = params?.radius ?? agent.radius;
+            agent.height = params?.height ?? agent.height;
+            agent.maxSpeed = params?.maxSpeed ?? agent.maxSpeed;
+            agent.maxAcceleration = params?.maxAcceleration ?? agent.maxAcceleration;
+        }
+        this.entityToAgent.set(entity.index, agentIdx);
+        this.stuckState.delete(agentIdx);
+        return agentIdx;
+    }
+    /**
+     * Sets a move target for the agent. The crowd will pathfind + steer to it.
+     *
+     * The requested target is validated before being issued:
+     *   1. It is snapped to the nearest walkable navmesh polygon.
+     *   2. A `computePath` is run from the agent's current position to the
+     *      snapped target. If the path is partial (its final waypoint is
+     *      farther than `reachabilityTolerance` from the target — i.e. the
+     *      target lies on a disconnected navmesh island such as the top of an
+     *      obstacle the agent cannot climb), the target is rejected and
+     *      `false` is returned. The agent's existing target is left untouched.
+     *
+     * On success, the *snapped, reachable* endpoint is stored as the agent's
+     * target (not the raw input) so the arrival heuristic measures distance to
+     * the actual goal rather than a point inside geometry.
+     *
+     * @returns `true` if the target was accepted and issued to the crowd.
+     */
+    setTarget(entity, target) {
+        if (!this.world)
+            return false;
+        const agent = this.world.getComponent(entity, RecastAgent.id);
+        if (!agent || agent.agentId < 0)
+            return false;
+        const crowd = this.crowd;
+        if (!crowd)
+            return false;
+        const crowdAgent = crowd.getAgent(agent.agentId);
+        if (!crowdAgent)
+            return false;
+        // Snap the requested target to the nearest walkable polygon, then verify
+        // the agent can actually reach it. Without this, a target inside an
+        // obstacle snaps to the nearest navmesh polygon — which may be the
+        // obstacle's walkable *top*, a disconnected island the agent cannot climb
+        // to — and the crowd spends forever steering into the obstacle base.
+        if (this.reachabilityTolerance > 0 && this.backend.isBuilt()) {
+            const query = this.backend.getQuery();
+            const startPos = crowdAgent.position();
+            const path = query.computePath({ x: startPos.x, y: startPos.y, z: startPos.z }, { x: target[0], y: target[1], z: target[2] });
+            if (!path.success || path.path.length === 0)
+                return false;
+            const last = path.path[path.path.length - 1];
+            const dx = last.x - target[0];
+            const dz = last.z - target[2];
+            // Partial path → target is on a disconnected island. Reject it.
+            if (Math.hypot(dx, dz) > this.reachabilityTolerance)
+                return false;
+            // Issue the move target at the reachable endpoint and store the snapped
+            // target so arrival detection is accurate.
+            const ok = crowdAgent.requestMoveTarget({ x: last.x, y: last.y, z: last.z });
+            if (!ok)
+                return false;
+            agent.target = [last.x, last.y, last.z];
+        }
+        else {
+            // Reachability check disabled: fall back to recast's built-in snapping.
+            const ok = crowdAgent.requestMoveTarget({ x: target[0], y: target[1], z: target[2] });
+            if (!ok)
+                return false;
+            agent.target = [target[0], target[1], target[2]];
+        }
+        agent.state = "seeking";
+        this.stuckState.delete(agent.agentId);
+        return true;
+    }
+    /**
+     * Per-tick stuck detection. Uses a sliding window: every `stuckTimeout`
+     * seconds it checks whether the agent has made appreciable *net* progress
+     * from its position at the start of the window. Measuring net displacement
+     * (rather than per-tick movement) correctly classifies an agent that
+     * oscillates against an obstacle as stuck — it jittered but ended up back
+     * where it started. This is a backstop for cases the `setTarget`
+     * reachability check cannot catch (dynamic obstacles, crowd local minima,
+     * agents wedged against geometry).
+     */
+    updateStuckState(agentIdx, agent, pos, dt) {
+        if (this.stuckTimeout <= 0 || !Number.isFinite(this.stuckTimeout)) {
+            agent.state = "seeking";
+            return;
+        }
+        let s = this.stuckState.get(agentIdx);
+        if (!s) {
+            s = { lastPos: [pos[0], pos[1], pos[2]], timer: 0 };
+            this.stuckState.set(agentIdx, s);
+        }
+        s.timer += dt;
+        if (s.timer >= this.stuckTimeout) {
+            // Window elapsed — evaluate net displacement from the window start.
+            const moved = Math.hypot(pos[0] - s.lastPos[0], pos[1] - s.lastPos[1], pos[2] - s.lastPos[2]);
+            if (moved < this.stuckMoveEpsilon) {
+                agent.state = "stuck";
+            }
+            else {
+                // Made progress — start a fresh window from the current position.
+                s.lastPos[0] = pos[0];
+                s.lastPos[1] = pos[1];
+                s.lastPos[2] = pos[2];
+                s.timer = 0;
+                agent.state = "seeking";
+            }
+        }
+        else {
+            agent.state = "seeking";
+        }
+    }
+    /** Clears the agent's move target (it will decelerate to a stop). */
+    clearTarget(entity) {
+        if (!this.world)
+            return;
+        const agent = this.world.getComponent(entity, RecastAgent.id);
+        if (!agent || agent.agentId < 0)
+            return;
+        const crowd = this.crowd;
+        if (!crowd)
+            return;
+        const crowdAgent = crowd.getAgent(agent.agentId);
+        if (!crowdAgent)
+            return;
+        crowdAgent.resetMoveTarget();
+        agent.target = null;
+        agent.state = "idle";
+        this.stuckState.delete(agent.agentId);
+    }
+    /** Removes an agent from the crowd. */
+    removeAgent(entity) {
+        if (!this.world)
+            return;
+        const agent = this.world.getComponent(entity, RecastAgent.id);
+        if (!agent || agent.agentId < 0)
+            return;
+        const crowd = this.crowd;
+        if (crowd)
+            crowd.removeAgent(agent.agentId);
+        agent.agentId = -1;
+        agent.state = "idle";
+        this.entityToAgent.delete(entity.index);
+        this.stuckState.delete(agent.agentId);
+    }
+    /** Releases the recast Crowd. The backend + navmesh are owned by RecastBackend. */
+    destroy() {
+        this.crowd = null;
+        this.world = null;
+        this.query = null;
+        this.entityToAgent.clear();
+        this.stuckState.clear();
+    }
+}

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

@@ -0,0 +1,4 @@
+export { RecastBackend, loadRecastLib } from "./backend.js";
+export { RecastAgent, RecastCrowdSystem } from "./crowd-system.js";
+// Declarative library descriptor
+export { RecastLib, RecastNavMeshTok, RecastCrowdTok } from "./library.js";

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

@@ -0,0 +1,59 @@
+// ============================================================================
+// RecastLib — declarative engine library descriptor for @downdraft/engine/libraries/recast
+//
+// Games declare `libraries: [RecastLib]` (or with config override) in their
+// GameModule. The host creates the RecastBackend + RecastCrowdSystem
+// (sim-side only — recast has no renderer component) and exposes them via
+// typed tokens.
+//
+// Games that need full control can still import RecastBackend,
+// RecastCrowdSystem, and RecastAgent directly (escape hatch).
+// ============================================================================
+import { resourceToken } from "@downdraft/engine";
+import { RecastBackend } from "./backend.js";
+import { RecastCrowdSystem } from "./crowd-system.js";
+// ── Typed tokens (DI) ──
+/** Token for the sim-side recast backend (navmesh + query). Inject in sim systems that need pathfinding. */
+export const RecastNavMeshTok = resourceToken("recast:navmesh");
+/** Token for the sim-side recast crowd system. Inject in sim systems that drive agents. */
+export const RecastCrowdTok = resourceToken("recast:crowd");
+// ── Descriptor ──
+export const RecastLib = {
+    name: "recast",
+    version: "1.0.0",
+    // No SAB channels — recast is sim-only, results synced via main SimBuffer.
+    sabChannels: [],
+    provides: [RecastNavMeshTok, RecastCrowdTok],
+    sim: {
+        async create(config, ctx) {
+            const backend = new RecastBackend();
+            await backend.init();
+            const crowd = new RecastCrowdSystem(backend, {
+                maxAgents: config.maxAgents ?? 512,
+                maxAgentRadius: config.maxAgentRadius ?? 0.6,
+                stuckTimeout: config.stuckTimeout,
+                stuckMoveEpsilon: config.stuckMoveEpsilon,
+                arrivalDistance: config.arrivalDistance,
+                reachabilityTolerance: config.reachabilityTolerance,
+            });
+            ctx.provide(RecastNavMeshTok, backend);
+            ctx.provide(RecastCrowdTok, crowd);
+            return { backend, crowd };
+        },
+        dispose(system) {
+            const { backend, crowd } = system;
+            crowd.destroy();
+            backend.destroy();
+        },
+        // tick is game-specific (calls crowd.update via the registered ECS system,
+        // setTarget per agent, repathing, etc.) — games wire this via onReady.
+    },
+    tickPhase: "post-physics",
+    // No renderer setup — recast is entirely sim-side.
+    defaultConfig: {
+        agentRadius: 0.5,
+        agentHeight: 1.8,
+        maxAgents: 512,
+        maxAgentRadius: 0.6,
+    },
+};

package/dist/libraries/recast/src/types.js

@@ -0,0 +1,4 @@
+// ============================================================================
+// Shared types for @downdraft/engine/libraries/recast
+// ============================================================================
+export {};

package/dist/libraries/sand/src/cell.js

@@ -0,0 +1,32 @@
+// ============================================================================
+// Cell packing helpers — shared between the sand simulation and consumers.
+//
+// A cell is packed into a single uint32:
+//   bits  0-7  : material id (0..255)
+//   bits  8-15 : lifetime (0..255)
+//   bits 16-23 : flags (shade bits 0-1, FLAG_UPDATED bit 2, FLAG_SPARK bit 3,
+//                        FLAG_POPPED bit 5)
+//   bits 24-31 : unused (reserved)
+// ============================================================================
+export const FLAG_UPDATED = 0x04; // bit 2 — cell was updated this frame
+export const FLAG_SPARK = 0x08; // bit 3 — this fire is a spark (expires to empty, not smoke)
+export const FLAG_ANCHORED = 0x10; // bit 4 — fire stays put (wax flame, doesn't rise/drift)
+export const FLAG_POPPED = 0x20; // bit 5 — popcorn that has already popped (won't re-pop)
+export const SHADE_MASK = 0x03; // bits 0-1 — shade index (0-3)
+// Precomputed bit position of FLAG_UPDATED within the packed uint32 flags field.
+// OR-ing this into a packed cell value sets FLAG_UPDATED without re-packing.
+export const FLAG_UPDATED_BIT = FLAG_UPDATED << 16;
+export function pack(cell) {
+    return (cell.mat & 0xff) | ((cell.lifetime & 0xff) << 8) | ((cell.flags & 0xff) << 16);
+}
+export function unpack(v) {
+    return {
+        mat: v & 0xff,
+        lifetime: (v >> 8) & 0xff,
+        flags: (v >> 16) & 0xff,
+    };
+}
+/** Pack a cell value from raw components without allocating a Cell object. */
+export function packCell(mat, lifetime, flags) {
+    return (mat & 0xff) | ((lifetime & 0xff) << 8) | ((flags & 0xff) << 16);
+}