@aethervtt/shard-nav 0.0.1

package/dist/agents.js

@@ -0,0 +1,703 @@
+import { defineSystem } from "@aethervtt/shard-core";
+import { CharacterController, CharacterIntent, Physics, Velocity } from "@aethervtt/shard-physics";
+import { FixedTime } from "@aethervtt/shard-runtime";
+import { GlobalTransform, Transform } from "@aethervtt/shard-transform";
+import { NavAgent, NavAgentState, NavAreas, NavArrived, NavUnreachable } from "./components.js";
+import { traceSegment } from "./grid.js";
+import { createNavPath, findPath, meshPathLocal } from "./query.js";
+import { Nav } from "./state.js";
+const IDLE = 0;
+const MOVING = 1;
+const ARRIVED = 2;
+const UNREACHABLE = 3;
+const DRIVE_CHARACTER = 0;
+const DRIVE_TRANSFORM = 1;
+const DRIVE_VELOCITY = 2;
+const ANTICIPATE_TURNS = 1;
+const OBSTACLE_AVOIDANCE = 2;
+const OPTIMIZE_VIS = 8;
+const OPTIMIZE_TOPO = 16;
+const CROWD_OFFMESH = 2;
+const STRAIGHTPATH_END = 2;
+const CORNERS = 128;
+function columns(table, out) {
+  out.destination = table.column(NavAgent, "destination");
+  out.target = table.column(NavAgent, "target");
+  out.speed = table.column(NavAgent, "speed");
+  out.acceleration = table.column(NavAgent, "acceleration");
+  out.radius = table.column(NavAgent, "radius");
+  out.stopping = table.column(NavAgent, "stoppingDistance");
+  out.avoidance = table.column(NavAgent, "avoidance");
+  out.repath = table.column(NavAgent, "repathInterval");
+  out.drive = table.column(NavAgent, "drive");
+  out.stopped = table.column(NavAgent, "stopped");
+  out.nav = table.column(NavAgent, "nav");
+  out.agentTicks = table.changedTicks(NavAgent);
+  out.status = table.column(NavAgentState, "status");
+  out.remaining = table.column(NavAgentState, "remaining");
+  out.corners = table.column(NavAgentState, "corners");
+  out.velocity = table.column(NavAgentState, "velocity");
+  out.translation = table.column(Transform, "translation");
+  out.rotation = table.column(Transform, "rotation");
+  out.global = table.column(GlobalTransform, "matrix");
+}
+function newRecord(entity) {
+  return {
+    entity,
+    nav: -1,
+    kind: "none",
+    crowdIndex: -1,
+    corners: new Float32Array(CORNERS * 3),
+    count: 0,
+    next: 1,
+    goal: new Float64Array(3),
+    navVersion: -1,
+    sinceRepath: 0,
+    reachable: true,
+    status: IDLE,
+    agentTick: 0,
+    drive: DRIVE_TRANSFORM,
+    framed: false,
+    lpos: new Float64Array(3),
+    link: { active: false, lift: 0, x0: 0, z0: 0, y0: 0, x1: 0, z1: 0, y1: 0, arc: 0 }
+  };
+}
+const pos = new Float64Array(3);
+const goal = new Float64Array(3);
+const seg = new Float64Array(4);
+const vec = { x: 0, y: 0, z: 0 };
+const navAgents = defineSystem({
+  name: "nav/agents",
+  description: "Steers NavAgents along paths on grids (seek, arrive, separation) and navmeshes (Detour crowd with avoidance), repaths for moving targets, writes CharacterIntent / Velocity / Transform and NavAgentState, sends NavArrived and NavUnreachable.",
+  setup: (world) => ({
+    query: world.query({ with: [NavAgent, NavAgentState, Transform] }),
+    cols: {},
+    path: createNavPath(CORNERS),
+    find: { out: void 0, nav: null },
+    // Grid separation: agent positions and radii this step, bucketed in a spatial hash.
+    gx: new Float64Array(64),
+    gy: new Float64Array(64),
+    gr: new Float64Array(64),
+    gnav: new Float64Array(64),
+    heads: new Int32Array(1024),
+    next: new Int32Array(64),
+    gridCount: 0,
+    cellSize: 1
+  }),
+  run: (s, world, ctx) => {
+    const nav = world.tryResource(Nav);
+    if (!nav) return;
+    const dt = world.resource(FixedTime).step;
+    const since = ctx.lastRunTick;
+    const physicsDim = world.tryResource(Physics)?.dim ?? 3;
+    buildHash(s, nav);
+    let crowds = false;
+    for (let t = 0; t < s.query.tables.length; t++) {
+      const table = s.query.tables[t];
+      columns(table, s.cols);
+      for (let row = 0; row < table.count; row++) {
+        if (stepAgent(s, world, nav, table, row, dt, since, physicsDim)) crowds = true;
+      }
+      table.markChanged(NavAgentState);
+    }
+    if (!crowds) return;
+    for (let i = 0; i < nav.meshList.length; i++) nav.meshList[i].crowd?.update(dt);
+    for (let t = 0; t < s.query.tables.length; t++) {
+      const table = s.query.tables[t];
+      columns(table, s.cols);
+      for (let row = 0; row < table.count; row++)
+        readCrowd(s, world, nav, table, row, dt, physicsDim);
+    }
+  }
+});
+function buildHash(s, nav) {
+  let n = 0;
+  let maxR = 0.1;
+  for (let t = 0; t < s.query.tables.length; t++) {
+    const table = s.query.tables[t];
+    const tr = table.column(Transform, "translation");
+    const radius = table.column(NavAgent, "radius");
+    for (let row = 0; row < table.count; row++) {
+      const rec = nav.agents.get(table.entities[row]);
+      if (rec?.kind !== "grid") continue;
+      if (n === s.gx.length) {
+        s.gx = grow(s.gx);
+        s.gy = grow(s.gy);
+        s.gr = grow(s.gr);
+        s.gnav = grow(s.gnav);
+        const next = new Int32Array(s.next.length * 2);
+        next.set(s.next);
+        s.next = next;
+      }
+      s.gx[n] = tr[row * 3];
+      s.gy[n] = tr[row * 3 + 1];
+      s.gr[n] = radius[row];
+      s.gnav[n] = rec.nav;
+      if (radius[row] > maxR) maxR = radius[row];
+      n++;
+    }
+  }
+  s.gridCount = n;
+  s.cellSize = maxR * 4;
+  s.heads.fill(-1);
+  for (let i = 0; i < n; i++) {
+    const h = hashCell(Math.floor(s.gx[i] / s.cellSize), Math.floor(s.gy[i] / s.cellSize));
+    s.next[i] = s.heads[h];
+    s.heads[h] = i;
+  }
+}
+function grow(a) {
+  const b = new Float64Array(a.length * 2);
+  b.set(a);
+  return b;
+}
+const hashCell = (x, y) => (Math.imul(x, 73856093) ^ Math.imul(y, 19349663)) & 1023;
+const framePos = new Float64Array(3);
+function locate(nav, preferred, x, y, z, wx, wy, wz) {
+  if (preferred >= 0) return nav.grids.has(preferred) || nav.meshes.has(preferred) ? preferred : -1;
+  for (let i = 0; i < nav.gridList.length; i++) {
+    const g = nav.gridList[i];
+    if (!g.grid) continue;
+    const cx = (x - g.ox) / g.csx;
+    const cy = (y - g.oy) / g.csy;
+    if (cx >= 0 && cy >= 0 && cx < g.grid.width && cy < g.grid.height) return g.entity;
+  }
+  for (let i = 0; i < nav.meshList.length; i++) {
+    const m = nav.meshList[i];
+    const pad = m.settings.agentRadius + m.settings.cellSize * 2;
+    let px = x;
+    let py = y;
+    let pz = z;
+    if (m.frame !== null) {
+      m.pointIn(wx, wy, wz, framePos);
+      px = framePos[0];
+      py = framePos[1];
+      pz = framePos[2];
+    }
+    if (px >= m.min[0] - pad && px <= m.max[0] + pad && pz >= m.min[2] - pad && pz <= m.max[2] + pad && py >= m.min[1] - m.settings.agentHeight && py <= m.max[1] + m.settings.agentHeight)
+      return m.entity;
+  }
+  return -1;
+}
+function removeFromCrowd(nav, rec) {
+  if (rec.crowdIndex >= 0) {
+    const rt = nav.meshes.get(rec.nav);
+    rt?.crowd?.removeAgent(rec.crowdIndex);
+    rec.crowdIndex = -1;
+  }
+}
+function stepAgent(s, world, nav, table, row, dt, since, dim) {
+  const c = s.cols;
+  const entity = table.entities[row];
+  let rec = nav.agents.get(entity);
+  if (!rec) {
+    rec = newRecord(entity);
+    nav.agents.set(entity, rec);
+  }
+  const o3 = row * 3;
+  pos[0] = c.translation[o3];
+  pos[1] = c.translation[o3 + 1];
+  pos[2] = c.translation[o3 + 2];
+  const drive = c.drive[row];
+  rec.drive = drive === DRIVE_CHARACTER && !table.has(CharacterController) ? DRIVE_TRANSFORM : drive === DRIVE_VELOCITY && !table.has(Velocity) ? DRIVE_TRANSFORM : drive;
+  const g12 = row * 12;
+  const navEntity = locate(
+    nav,
+    c.nav[row],
+    pos[0],
+    pos[1],
+    pos[2],
+    c.global[g12 + 3],
+    c.global[g12 + 7],
+    c.global[g12 + 11]
+  );
+  if (navEntity !== rec.nav) {
+    removeFromCrowd(nav, rec);
+    rec.nav = navEntity;
+    rec.kind = navEntity < 0 ? "none" : nav.grids.has(navEntity) ? "grid" : "mesh";
+    rec.navVersion = -1;
+    rec.count = 0;
+  }
+  if (rec.kind === "none" || c.stopped[row] === 1) {
+    removeFromCrowd(nav, rec);
+    halt(s, world, table, row, rec, IDLE, dim);
+    return false;
+  }
+  const framedMesh = rec.kind === "mesh" ? nav.meshes.get(rec.nav) : void 0;
+  rec.framed = framedMesh !== void 0 && framedMesh.frame !== null;
+  if (rec.framed) {
+    framedMesh.pointIn(c.global[g12 + 3], c.global[g12 + 7], c.global[g12 + 11], pos);
+    rec.lpos[0] = pos[0];
+    rec.lpos[1] = pos[1];
+    rec.lpos[2] = pos[2];
+  }
+  const target = c.target[row];
+  if (target >= 0 && world.isAlive(target) && world.has(target, GlobalTransform)) {
+    const tt = world.entityTable(target);
+    const tm = tt.column(GlobalTransform, "matrix");
+    const tr = world.entityRow(target);
+    goal[0] = tm[tr * 12 + 3];
+    goal[1] = tm[tr * 12 + 7];
+    goal[2] = tm[tr * 12 + 11];
+  } else {
+    goal[0] = c.destination[o3];
+    goal[1] = c.destination[o3 + 1];
+    goal[2] = c.destination[o3 + 2];
+  }
+  if (rec.framed) framedMesh.pointIn(goal[0], goal[1], goal[2], goal);
+  rec.sinceRepath += dt;
+  const grid = rec.kind === "grid" ? nav.grids.get(rec.nav) : void 0;
+  const mesh = rec.kind === "mesh" ? nav.meshes.get(rec.nav) : void 0;
+  const version = grid ? grid.version : mesh.version;
+  const cell = grid ? Math.max(grid.csx, grid.csy) : Math.max(c.radius[row], mesh.settings.cellSize);
+  const gdx = goal[0] - rec.goal[0];
+  const gdy = goal[1] - rec.goal[1];
+  const gdz = goal[2] - rec.goal[2];
+  const moved = Math.sqrt(gdx * gdx + gdy * gdy + gdz * gdz);
+  const edited = c.agentTicks[row] > since && c.agentTicks[row] !== rec.agentTick;
+  const repath = rec.navVersion !== version || edited || moved > cell || target >= 0 && moved > 1e-4 && rec.sinceRepath >= c.repath[row];
+  if (repath) {
+    rec.agentTick = c.agentTicks[row];
+    rec.goal[0] = goal[0];
+    rec.goal[1] = goal[1];
+    rec.goal[2] = goal[2];
+    rec.navVersion = version;
+    rec.sinceRepath = 0;
+    plan(s, world, nav, rec);
+    if (rec.status === ARRIVED || rec.status === IDLE) rec.status = MOVING;
+  }
+  if (grid) {
+    steerGrid(s, world, table, row, rec, grid, dt, dim);
+    return false;
+  }
+  return requestCrowd(s, world, nav, table, row, rec, mesh, repath, dim);
+}
+function plan(s, world, nav, rec) {
+  const path = s.path;
+  if (rec.kind === "grid" && !nav.grids.get(rec.nav)?.grid) {
+    rec.count = 0;
+    return;
+  }
+  s.find.out = path;
+  s.find.nav = rec.nav;
+  const mesh = rec.kind === "mesh" ? nav.meshes.get(rec.nav) : void 0;
+  if (mesh && rec.framed) meshPathLocal(mesh, pos, rec.goal, path);
+  else findPath(world, pos, rec.goal, s.find);
+  rec.corners.set(path.corners.subarray(0, path.count * 3));
+  rec.count = path.count;
+  rec.next = 1;
+  rec.reachable = path.status === "complete";
+}
+function halt(s, world, table, row, rec, status, dim) {
+  const c = s.cols;
+  c.velocity[row * 3] = 0;
+  c.velocity[row * 3 + 1] = 0;
+  c.velocity[row * 3 + 2] = 0;
+  applyDrive(table, row, rec, 0, 0, 0, 0, dim);
+  if (status !== ARRIVED) c.remaining[row] = 0;
+  c.corners[row] = 0;
+  setStatus(world, s, row, rec, status);
+}
+function setStatus(world, s, row, rec, status) {
+  s.cols.status[row] = status;
+  if (status === rec.status) return;
+  rec.status = status;
+  if (status === ARRIVED) world.send(NavArrived, { entity: rec.entity });
+  else if (status === UNREACHABLE) world.send(NavUnreachable, { entity: rec.entity });
+}
+const worldVel = new Float64Array(3);
+function applyDrive(table, row, rec, vx, vy, vz, dt, dim, mesh) {
+  if (rec.framed && mesh) {
+    mesh.vectorOut(vx, vy, vz, worldVel);
+    driveFramed(table, row, rec, worldVel[0], worldVel[1], worldVel[2], dt);
+    return;
+  }
+  if (rec.drive === DRIVE_CHARACTER) {
+    const move = table.column(CharacterIntent, "move");
+    if (dim === 2) {
+      move[row * 3] = vx;
+      move[row * 3 + 1] = 0;
+      move[row * 3 + 2] = 0;
+    } else {
+      const q = table.column(Transform, "rotation");
+      const qx = -q[row * 4];
+      const qy = -q[row * 4 + 1];
+      const qz = -q[row * 4 + 2];
+      const qw = q[row * 4 + 3];
+      const tx = 2 * (qy * vz - qz * vy);
+      const ty = 2 * (qz * vx - qx * vz);
+      const tz = 2 * (qx * vy - qy * vx);
+      move[row * 3] = vx + qw * tx + (qy * tz - qz * ty);
+      move[row * 3 + 1] = 0;
+      move[row * 3 + 2] = vz + qw * tz + (qx * ty - qy * tx);
+    }
+    table.markChanged(CharacterIntent, row);
+    return;
+  }
+  if (rec.drive === DRIVE_VELOCITY) {
+    const lin = table.column(Velocity, "linear");
+    lin[row * 3] = vx;
+    if (dim === 2 || rec.kind === "grid") lin[row * 3 + 1] = vy;
+    else lin[row * 3 + 2] = vz;
+    table.markChanged(Velocity, row);
+    return;
+  }
+  if (dt > 0) {
+    const tr = table.column(Transform, "translation");
+    tr[row * 3] = tr[row * 3] + vx * dt;
+    tr[row * 3 + 1] = tr[row * 3 + 1] + vy * dt;
+    tr[row * 3 + 2] = tr[row * 3 + 2] + vz * dt;
+    table.markChanged(Transform, row);
+  }
+}
+function driveFramed(table, row, rec, vx, vy, vz, dt) {
+  const m = table.column(GlobalTransform, "matrix");
+  const o = row * 12;
+  const ax = axis(m, o, 0);
+  const ay = axis(m, o, 1);
+  const az = axis(m, o, 2);
+  const lx = (vx * m[o] + vy * m[o + 4] + vz * m[o + 8]) / ax;
+  const ly = (vx * m[o + 1] + vy * m[o + 5] + vz * m[o + 9]) / ay;
+  const lz = (vx * m[o + 2] + vy * m[o + 6] + vz * m[o + 10]) / az;
+  if (rec.drive === DRIVE_CHARACTER) {
+    const move = table.column(CharacterIntent, "move");
+    move[row * 3] = lx;
+    move[row * 3 + 1] = 0;
+    move[row * 3 + 2] = lz;
+    table.markChanged(CharacterIntent, row);
+    return;
+  }
+  if (rec.drive === DRIVE_VELOCITY) {
+    const lin = table.column(Velocity, "linear");
+    lin[row * 3] = vx;
+    lin[row * 3 + 1] = vy;
+    lin[row * 3 + 2] = vz;
+    table.markChanged(Velocity, row);
+    return;
+  }
+  if (dt > 0) {
+    const q = table.column(Transform, "rotation");
+    const qx = q[row * 4];
+    const qy = q[row * 4 + 1];
+    const qz = q[row * 4 + 2];
+    const qw = q[row * 4 + 3];
+    const tx = 2 * (qy * lz - qz * ly);
+    const ty = 2 * (qz * lx - qx * lz);
+    const tz = 2 * (qx * ly - qy * lx);
+    const tr = table.column(Transform, "translation");
+    tr[row * 3] = tr[row * 3] + (lx + qw * tx + (qy * tz - qz * ty)) * dt;
+    tr[row * 3 + 1] = tr[row * 3 + 1] + (ly + qw * ty + (qz * tx - qx * tz)) * dt;
+    tr[row * 3 + 2] = tr[row * 3 + 2] + (lz + qw * tz + (qx * ty - qy * tx)) * dt;
+    table.markChanged(Transform, row);
+  }
+}
+function axis(m, o, c) {
+  return Math.sqrt(m[o + c] ** 2 + m[o + 4 + c] ** 2 + m[o + 8 + c] ** 2) || 1;
+}
+function steerGrid(s, world, table, row, rec, g, dt, dim) {
+  const c = s.cols;
+  const o3 = row * 3;
+  const speed = c.speed[row];
+  const accel = c.acceleration[row];
+  const radius = c.radius[row];
+  const stopping = c.stopping[row];
+  const corners = rec.corners;
+  if (rec.count === 0) {
+    halt(s, world, table, row, rec, UNREACHABLE, dim);
+    return;
+  }
+  const reach = Math.max(stopping, radius * 0.5, 1e-3);
+  while (rec.next < rec.count - 1) {
+    const dx = corners[rec.next * 3] - pos[0];
+    const dy = corners[rec.next * 3 + 1] - pos[1];
+    if (dx * dx + dy * dy > reach * reach) break;
+    rec.next++;
+  }
+  if (rec.next >= rec.count) rec.next = rec.count - 1;
+  let remaining = 0;
+  {
+    let px = pos[0];
+    let py = pos[1];
+    for (let i = rec.next; i < rec.count; i++) {
+      const dx = corners[i * 3] - px;
+      const dy = corners[i * 3 + 1] - py;
+      remaining += Math.sqrt(dx * dx + dy * dy);
+      px = corners[i * 3];
+      py = corners[i * 3 + 1];
+    }
+  }
+  c.remaining[row] = remaining;
+  c.corners[row] = rec.count - rec.next;
+  const end = remaining <= stopping;
+  if (end && rec.next === rec.count - 1) {
+    halt(s, world, table, row, rec, rec.reachable ? ARRIVED : UNREACHABLE, dim);
+    c.remaining[row] = remaining;
+    return;
+  }
+  const tx = corners[rec.next * 3] - pos[0];
+  const ty = corners[rec.next * 3 + 1] - pos[1];
+  const d = Math.sqrt(tx * tx + ty * ty) || 1;
+  let want = speed;
+  const brake = Math.sqrt(2 * accel * Math.max(0, remaining - stopping * 0.5));
+  if (brake < want) want = brake;
+  let dvx = tx / d * want;
+  let dvy = ty / d * want;
+  const cs = s.cellSize;
+  const hx = Math.floor(pos[0] / cs);
+  const hy = Math.floor(pos[1] / cs);
+  for (let oy = -1; oy <= 1; oy++) {
+    for (let ox = -1; ox <= 1; ox++) {
+      for (let j = s.heads[hashCell(hx + ox, hy + oy)]; j !== -1; j = s.next[j]) {
+        if (s.gnav[j] !== rec.nav) continue;
+        const ax = pos[0] - s.gx[j];
+        const ay = pos[1] - s.gy[j];
+        const min = radius + s.gr[j];
+        const dd = ax * ax + ay * ay;
+        if (dd >= min * min || dd < 1e-12) continue;
+        const dist = Math.sqrt(dd);
+        const push = (min - dist) / min * speed * 2;
+        dvx += ax / dist * push;
+        dvy += ay / dist * push;
+      }
+    }
+  }
+  const dl = Math.sqrt(dvx * dvx + dvy * dvy);
+  if (dl > speed) {
+    dvx = dvx / dl * speed;
+    dvy = dvy / dl * speed;
+  }
+  let vx = c.velocity[o3];
+  let vy = c.velocity[o3 + 1];
+  const ex = dvx - vx;
+  const ey = dvy - vy;
+  const el = Math.sqrt(ex * ex + ey * ey);
+  const maxDv = accel * dt;
+  if (el > maxDv) {
+    vx += ex / el * maxDv;
+    vy += ey / el * maxDv;
+  } else {
+    vx = dvx;
+    vy = dvy;
+  }
+  if (rec.drive === DRIVE_TRANSFORM && g.grid) {
+    const grid = g.grid;
+    seg[0] = (pos[0] - g.ox) / g.csx;
+    seg[1] = (pos[1] - g.oy) / g.csy;
+    seg[2] = (pos[0] + vx * dt - g.ox) / g.csx;
+    seg[3] = (pos[1] + vy * dt - g.oy) / g.csy;
+    if (!traceSegment(grid, seg, 2, 255)) {
+      seg[3] = seg[1];
+      if (traceSegment(grid, seg, 2, 255)) vy = 0;
+      else {
+        seg[2] = seg[0];
+        seg[3] = (pos[1] + vy * dt - g.oy) / g.csy;
+        if (traceSegment(grid, seg, 2, 255)) vx = 0;
+        else {
+          vx = 0;
+          vy = 0;
+        }
+      }
+    }
+  }
+  c.velocity[o3] = vx;
+  c.velocity[o3 + 1] = vy;
+  c.velocity[o3 + 2] = 0;
+  applyDrive(table, row, rec, vx, vy, 0, dt, dim);
+  setStatus(world, s, row, rec, rec.reachable ? MOVING : UNREACHABLE);
+}
+function crowdParams(s, row, rt) {
+  const c = s.cols;
+  const r = c.radius[row];
+  const avoid = c.avoidance[row] === 1;
+  return {
+    radius: r,
+    height: rt.settings.agentHeight,
+    maxAcceleration: c.acceleration[row],
+    maxSpeed: c.speed[row],
+    collisionQueryRange: r * 12,
+    pathOptimizationRange: r * 30,
+    // Separation pushes across the whole query range (12 radii): agents at the edge of a group
+    // settle short of their goals. Velocity-obstacle avoidance alone keeps them apart.
+    separationWeight: 0,
+    updateFlags: ANTICIPATE_TURNS | OPTIMIZE_VIS | OPTIMIZE_TOPO | (avoid ? OBSTACLE_AVOIDANCE : 0),
+    obstacleAvoidanceType: 3,
+    queryFilterType: 0
+  };
+}
+function ensureCrowd(world, nav, rt, radius) {
+  let agents = 0;
+  for (const r of nav.agents.values()) if (r.nav === rt.entity) agents++;
+  if (rt.crowd && rt.crowdCapacity >= agents && rt.crowdRadius >= radius) return;
+  const capacity = Math.max(32, rt.crowdCapacity * 2, agents * 2);
+  const maxRadius = Math.max(radius, rt.crowdRadius, rt.settings.agentRadius);
+  rt.destroyCrowd();
+  rt.crowd = new rt.R.Crowd(rt.navMesh, { maxAgents: capacity, maxAgentRadius: maxRadius });
+  rt.crowdCapacity = capacity;
+  rt.crowdRadius = maxRadius;
+  rt.applyAreas(world.tryResource(NavAreas) ?? {});
+  for (const r of nav.agents.values()) if (r.nav === rt.entity) r.crowdIndex = -1;
+}
+function requestCrowd(s, world, nav, table, row, rec, rt, repath, dim) {
+  const c = s.cols;
+  if (!rt.crowd || rec.crowdIndex < 0) ensureCrowd(world, nav, rt, c.radius[row]);
+  const crowd = rt.crowd;
+  vec.x = pos[0];
+  vec.y = pos[1];
+  vec.z = pos[2];
+  let agent = rec.crowdIndex >= 0 ? crowd.agents[rec.crowdIndex] : void 0;
+  if (!agent) {
+    agent = crowd.addAgent(vec, crowdParams(s, row, rt));
+    rec.crowdIndex = agent.agentIndex;
+    repath = true;
+  } else if (c.agentTicks[row] > rec.agentTick || repath) {
+    agent.updateParameters(crowdParams(s, row, rt));
+  }
+  if (rec.count === 0) {
+    halt(s, world, table, row, rec, UNREACHABLE, dim);
+    agent.resetMoveTarget();
+    return true;
+  }
+  if (repath) {
+    const e = (rec.count - 1) * 3;
+    vec.x = rec.corners[e];
+    vec.y = rec.corners[e + 1];
+    vec.z = rec.corners[e + 2];
+    agent.requestMoveTarget(vec);
+  }
+  if (rec.drive !== DRIVE_TRANSFORM && agent.raw.get_state() !== CROWD_OFFMESH) {
+    const raw = agent.raw;
+    raw.set_npos(0, pos[0]);
+    raw.set_npos(1, pos[1]);
+    raw.set_npos(2, pos[2]);
+  }
+  return true;
+}
+function readCrowd(s, world, nav, table, row, dt, dim) {
+  const c = s.cols;
+  const rec = nav.agents.get(table.entities[row]);
+  if (rec?.kind !== "mesh" || rec.crowdIndex < 0 || c.stopped[row] === 1) return;
+  const rt = nav.meshes.get(rec.nav);
+  const agent = rt?.crowd?.agents[rec.crowdIndex];
+  if (!agent || rec.count === 0) return;
+  const raw = agent.raw;
+  const o3 = row * 3;
+  const px = raw.get_npos(0);
+  const py = raw.get_npos(1);
+  const pz = raw.get_npos(2);
+  let vx = raw.get_vel(0);
+  let vy = raw.get_vel(1);
+  let vz = raw.get_vel(2);
+  const hx = rec.framed ? rec.lpos[0] : c.translation[o3];
+  const hy = rec.framed ? rec.lpos[1] : c.translation[o3 + 1];
+  const hz = rec.framed ? rec.lpos[2] : c.translation[o3 + 2];
+  const e = (rec.count - 1) * 3;
+  const ex = rec.corners[e] - hx;
+  const ez = rec.corners[e + 2] - hz;
+  const ey = rec.corners[e + 1] - hy;
+  let remaining = 0;
+  let lx = hx;
+  let ly = hy;
+  let lz = hz;
+  const n = raw.get_ncorners();
+  let ended = false;
+  for (let i = 0; i < n; i++) {
+    const cx = raw.get_cornerVerts(i * 3);
+    const cy = raw.get_cornerVerts(i * 3 + 1);
+    const cz = raw.get_cornerVerts(i * 3 + 2);
+    remaining += Math.sqrt((cx - lx) ** 2 + (cy - ly) ** 2 + (cz - lz) ** 2);
+    lx = cx;
+    ly = cy;
+    lz = cz;
+    if ((raw.get_cornerFlags(i) & STRAIGHTPATH_END) !== 0) ended = true;
+  }
+  if (!ended) {
+    remaining += Math.sqrt(
+      (rec.corners[e] - lx) ** 2 + (rec.corners[e + 1] - ly) ** 2 + (rec.corners[e + 2] - lz) ** 2
+    );
+  }
+  const flat = Math.sqrt(ex * ex + ez * ez);
+  c.remaining[row] = n === 0 ? flat : remaining;
+  c.corners[row] = n;
+  if (flat <= c.stopping[row] && Math.abs(ey) < rt.settings.agentHeight) {
+    agent.resetMoveTarget();
+    halt(s, world, table, row, rec, rec.reachable ? ARRIVED : UNREACHABLE, dim);
+    c.remaining[row] = flat;
+    raw.set_npos(0, hx);
+    raw.set_npos(1, hy);
+    raw.set_npos(2, hz);
+    return;
+  }
+  const offmesh = raw.get_state() === CROWD_OFFMESH;
+  const link = rec.link;
+  if (offmesh && !link.active) startLink(nav, rec, hy, px, py, pz);
+  link.active = offmesh;
+  if (rec.drive === DRIVE_TRANSFORM || offmesh) {
+    let y = py;
+    if (offmesh) {
+      const total = Math.sqrt((link.x1 - link.x0) ** 2 + (link.z1 - link.z0) ** 2);
+      const done = Math.sqrt((px - link.x0) ** 2 + (pz - link.z0) ** 2);
+      const t = total > 1e-6 ? Math.min(1, done / total) : 1;
+      y = link.y0 + (link.y1 - link.y0) * t + link.lift + link.arc * 4 * t * (1 - t);
+    }
+    vx = (px - hx) / dt;
+    vy = (y - hy) / dt;
+    vz = (pz - hz) / dt;
+    if (rec.framed) {
+      const drive = rec.drive;
+      rec.drive = DRIVE_TRANSFORM;
+      applyDrive(table, row, rec, vx, vy, vz, dt, dim, rt);
+      rec.drive = drive;
+    } else {
+      const tr = c.translation;
+      tr[o3] = px;
+      tr[o3 + 1] = y;
+      tr[o3 + 2] = pz;
+      table.markChanged(Transform, row);
+    }
+    if (rec.drive !== DRIVE_TRANSFORM) applyDrive(table, row, rec, 0, 0, 0, 0, dim, rt);
+  } else {
+    applyDrive(table, row, rec, vx, vy, vz, dt, dim, rt);
+  }
+  c.velocity[o3] = vx;
+  c.velocity[o3 + 1] = vy;
+  c.velocity[o3 + 2] = vz;
+  setStatus(world, s, row, rec, rec.reachable ? MOVING : UNREACHABLE);
+}
+function startLink(nav, rec, y, x, surface, z) {
+  const link = rec.link;
+  link.x0 = x;
+  link.z0 = z;
+  link.y0 = surface;
+  link.x1 = x;
+  link.z1 = z;
+  link.y1 = surface;
+  link.arc = 0.5;
+  let best = Infinity;
+  for (let i = 0; i < nav.links.length; i++) {
+    const l = nav.links[i];
+    const ds = (l.start[0] - x) ** 2 + (l.start[2] - z) ** 2;
+    const de = l.bidirectional ? (l.end[0] - x) ** 2 + (l.end[2] - z) ** 2 : Infinity;
+    const d = Math.min(ds, de);
+    if (d >= best) continue;
+    best = d;
+    const near = ds <= de ? l.start : l.end;
+    const far = ds <= de ? l.end : l.start;
+    link.y0 = near[1];
+    link.x1 = far[0];
+    link.z1 = far[2];
+    link.y1 = far[1];
+    link.arc = 0.4 + Math.abs(far[1] - near[1]);
+  }
+  link.lift = rec.drive === DRIVE_TRANSFORM ? 0 : Math.max(0, y - link.y0);
+}
+function dropAgent(world, entity) {
+  const nav = world.tryResource(Nav);
+  const rec = nav?.agents.get(entity);
+  if (!nav || !rec) return;
+  removeFromCrowd(nav, rec);
+  nav.agents.delete(entity);
+}
+export {
+  dropAgent,
+  navAgents
+};