@downdraft/engine 0.0.0 → 0.1.0

package/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/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/libraries/recast/README.md

@@ -0,0 +1,21 @@
+# `@downdraft/engine/libraries/recast`
+
+Recast/Detour bindings — navmesh generation from level geometry via the Recast toolchain.
+
+## Install
+
+```sh
+bun add @downdraft/engine/libraries/recast
+```
+
+## Key exports
+
+- `RecastAgent`
+- `RecastBackend`
+- `RecastCrowdSystem`
+- `RecastCrowdTok`
+- `RecastLib`
+- `RecastNavMeshTok`
+- `loadRecastLib`
+
+See the [Downdraft engine repository](https://github.com/knackstedt/downdraft) for architecture docs and examples.

package/libraries/recast/src/backend.ts

@@ -0,0 +1,150 @@
+// ============================================================================
+// 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";
+import type { Crowd, NavMesh, NavMeshQuery } from "recast-navigation";
+import type { RecastNavMeshConfig } from "./types";
+
+const log = createLogger();
+
+// ── WASM loader (cached + coalesced) ──
+
+interface RecastModule {
+  init: () => Promise<void>;
+  NavMesh: typeof import("recast-navigation").NavMesh;
+  NavMeshQuery: typeof import("recast-navigation").NavMeshQuery;
+  Crowd: typeof import("recast-navigation").Crowd;
+}
+
+interface GeneratorsModule {
+  generateSoloNavMesh: typeof import("recast-navigation/generators").generateSoloNavMesh;
+}
+
+let cachedModule: RecastModule | null = null;
+let cachedGenerators: GeneratorsModule | null = null;
+let loadingPromise: Promise<RecastModule> | null = 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(): Promise<RecastModule> {
+  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(): Promise<RecastModule> {
+  const mod = await import("recast-navigation");
+  await mod.init();
+  cachedModule = mod as unknown as RecastModule;
+  cachedGenerators = await import("recast-navigation/generators");
+  log.info("recast", "recast-navigation WASM initialized");
+  return cachedModule;
+}
+
+/** Returns the generators submodule (generateSoloNavMesh, etc.). */
+export function getRecastGenerators(): GeneratorsModule {
+  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 {
+  private mod: RecastModule | null = null;
+  private navMesh: NavMesh | null = null;
+  private query: NavMeshQuery | null = null;
+  private destroyed = false;
+
+  /** Asynchronously loads the WasM module. Must be called before buildNavMesh. */
+  async init(): Promise<void> {
+    if (this.mod) return;
+    this.mod = await loadRecastLib();
+  }
+
+  private ensureMod(): RecastModule {
+    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: ArrayLike<number>, indices: ArrayLike<number>, config?: RecastNavMeshConfig): boolean {
+    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(): NavMesh {
+    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(): NavMeshQuery {
+    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(): boolean {
+    return this.navMesh !== null;
+  }
+
+  /** The loaded recast-navigation module (for Crowd construction etc.). */
+  getModule(): RecastModule {
+    return this.ensureMod();
+  }
+
+  /** Releases the navmesh + query. The WASM module itself stays cached. */
+  destroy(): void {
+    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;
+  }
+}
+
+// Re-export the Crowd type for the crowd-system wrapper's type annotations.
+export type { Crowd };

package/libraries/recast/src/crowd-system.ts

@@ -0,0 +1,352 @@
+// ============================================================================
+// 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 type { ComponentDefinition } from "@downdraft/engine/ecs/component";
+import { Component } from "@downdraft/engine/ecs/component";
+import type { Entity } from "@downdraft/engine/ecs/entity";
+import type { Query } from "@downdraft/engine/ecs/query";
+import { Stage, system } from "@downdraft/engine/ecs/system";
+import type { World } from "@downdraft/engine/ecs/world";
+import { PhysicsTransform } from "@downdraft/engine/physics/body";
+import type { RecastBackend } from "./backend";
+import type { RecastAgentData, RecastAgentParams, Vec3 } from "./types";
+
+// ── ECS component ──
+
+export const RecastAgent: ComponentDefinition<RecastAgentData> = Component.register<RecastAgentData>(
+  "RecastAgent",
+  {
+    agentId: -1,
+    radius: 0.5,
+    height: 1.8,
+    maxSpeed: 3.5,
+    maxAcceleration: 10,
+    target: null,
+    state: "idle",
+    velocity: [0, 0, 0],
+  },
+);
+
+// ── Crowd system ──
+
+interface RecastCrowdConfig {
+  maxAgents: number;
+  maxAgentRadius: number;
+  /**
+   * Seconds an agent may make no appreciable progress toward its target before
+   * its state flips to `"stuck"`. Set to `0` (or `Infinity`) to disable stuck
+   * detection. Default: `2`.
+   */
+  stuckTimeout?: number;
+  /**
+   * Minimum per-tick displacement (metres) that counts as "making progress"
+   * for stuck detection. Default: `0.05`.
+   */
+  stuckMoveEpsilon?: number;
+  /**
+   * Horizontal distance (metres) from the snapped target at which an agent is
+   * considered to have arrived. Default: `0.5`.
+   */
+  arrivalDistance?: number;
+  /**
+   * When `setTarget` is called, the engine runs a `computePath` from the
+   * agent's current position to the requested target and rejects the target
+   * if the resulting path is partial (its final waypoint is farther than this
+   * from the snapped target — i.e. the target lies on a disconnected navmesh
+   * island, such as the top of an obstacle the agent cannot climb). Set to
+   * `0` to accept any target that snaps onto the navmesh without a
+   * reachability check. Default: `1.5`.
+   */
+  reachabilityTolerance?: number;
+}
+
+/**
+ * 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 {
+  private backend: RecastBackend;
+  private config: RecastCrowdConfig;
+  private crowd: import("recast-navigation").Crowd | null = null;
+  private world: World | null = null;
+  private query: Query | null = null;
+  /** entity.index → recast CrowdAgent index, for write-back during tick. */
+  private entityToAgent = new Map<number, number>();
+  /** Per-agent stuck-detection state, keyed by recast agent index. */
+  private stuckState = new Map<number, { lastPos: Vec3; timer: number }>();
+
+  // Resolved config (defaults applied once).
+  private readonly stuckTimeout: number;
+  private readonly stuckMoveEpsilon: number;
+  private readonly arrivalDistance: number;
+  private readonly reachabilityTolerance: number;
+
+  constructor(backend: RecastBackend, config: RecastCrowdConfig) {
+    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.
+   */
+  private ensureCrowd(): import("recast-navigation").Crowd {
+    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: World, query: Query): void {
+    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] as RecastAgentData;
+          const transform = components[1] as { position: Vec3; rotation: [number, number, number, number] };
+          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: Entity, params?: RecastAgentParams): number {
+    if (!this.world) throw new Error("RecastCrowdSystem not registered with a world.");
+    const crowd = this.ensureCrowd();
+    const transform = this.world.getComponent<{ position: Vec3 }>(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<RecastAgentData>(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: Entity, target: Vec3): boolean {
+    if (!this.world) return false;
+    const agent = this.world.getComponent<RecastAgentData>(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).
+   */
+  private updateStuckState(agentIdx: number, agent: RecastAgentData, pos: Vec3, dt: number): void {
+    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: Entity): void {
+    if (!this.world) return;
+    const agent = this.world.getComponent<RecastAgentData>(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: Entity): void {
+    if (!this.world) return;
+    const agent = this.world.getComponent<RecastAgentData>(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(): void {
+    this.crowd = null;
+    this.world = null;
+    this.query = null;
+    this.entityToAgent.clear();
+    this.stuckState.clear();
+  }
+}

package/libraries/recast/src/index.ts

@@ -0,0 +1,12 @@
+export { RecastBackend, loadRecastLib } from "./backend";
+export { RecastAgent, RecastCrowdSystem } from "./crowd-system";
+export type {
+  RecastAgentData,
+  RecastAgentParams,
+  RecastNavMeshConfig,
+  Vec3,
+} from "./types";
+
+// Declarative library descriptor
+export { RecastLib, RecastNavMeshTok, RecastCrowdTok } from "./library";
+export type { RecastLibConfig } from "./library";