@thi.ng/boids 0.1.15 → 1.0.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-12-31T09:44:23Z
+- **Last updated**: 2024-01-23T15:58:26Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,37 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+# [1.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/boids@1.0.0) (2024-01-23)
+
+#### 🛑 Breaking changes
+
+- major refactoring/restructuring, new behavior system ([22cb42d](https://github.com/thi-ng/umbrella/commit/22cb42d))
+- BREAKING CHANGE: major refactoring/restructuring, new behavior system
+  - modular behavior system with currently these 7 behaviors:
+    - alignment()
+    - attractPolyline()
+    - braitenberg2()
+    - cohesion()
+    - dynamicTarget()
+    - followPolyline()
+    - separation()
+  - add blendedBehaviorUpdate()
+  - add clamp2/3() and wrap2/3() global constraints
+  - add Flock class (+ defFlock() factory fn)
+  - update/simplify Boid class and 2d/3d factory fns
+  - update BoidOpts
+  - add doc strings
+  - add/update deps
+
+#### 🚀 Features
+
+- update dynamicTarget() ([647d7e1](https://github.com/thi-ng/umbrella/commit/647d7e1))
+  - add radius param
+
+#### 🩹 Bug fixes
+
+- update separation() behavior neighbor lookup ([c8ece89](https://github.com/thi-ng/umbrella/commit/c8ece89))
+
 ### [0.1.3](https://github.com/thi-ng/umbrella/tree/@thi.ng/boids@0.1.3) (2023-11-09)
 
 #### ♻️ Refactoring

package/README.md

@@ -12,6 +12,8 @@ This is a standalone project, maintained as part of the
 anti-framework.
 
 - [About](#about)
+  - [Available behaviors](#available-behaviors)
+  - [Acceleration structures](#acceleration-structures)
 - [Status](#status)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
@@ -22,7 +24,57 @@ anti-framework.
 
 ## About
 
-n-dimensional boids simulation with highly configurable behaviors.
+n-dimensional boids simulation with modular behavior system.
+
+The API of this package is still unstable, but the underlying implementations
+have been used in many of the author's projects since ~2005... The agent/boid
+behaviors are fully modular and can be highly customized via the given
+parameters (which can also be dynamically/spatially adjusted). As with other
+thi.ng packages, the visual representation of the boids is entirely separate and
+out of scope of this package. This package only deals with the simulation of
+agents, their behavioral aspects and essentially only processes points in space
+(and their directions, forces)...
+
+### Available behaviors
+
+The following behavior building blocks are provided. All of them can be freely
+combined (incl. multiple instances with different configurations) and assigned
+to individual boids (or groups of them). Each behavior also has an associated
+weight to adjust its impact on the overall movement of the boids (also
+dynamically adjustable).
+
+- [`alignment()`](https://docs.thi.ng/umbrella/boids/functions/alignment.html):
+  Steer towards the average direction of neighbors within given radius
+- [`attractPolyline()`](https://docs.thi.ng/umbrella/boids/functions/attractPolyline.html):
+  Steer towards the nearest point on a pre-configured polyline (or polygon)
+- [`braitenberg2()`](https://docs.thi.ng/umbrella/boids/functions/braitenberg2.html):
+  Field-based 3-sensor (left/right/center) Braitenberg vehicle steering
+- [`cohesion()`](https://docs.thi.ng/umbrella/boids/functions/cohesion.html):
+  Steer towards the centroid of neighbors within given radius
+- [`dynamicTarget()`](https://docs.thi.ng/umbrella/boids/functions/dynamicTarget.html):
+  Steer towards user defined (dynamically changeable) location(s)
+- [`followPolyline()`](https://docs.thi.ng/umbrella/boids/functions/followPolyline.html):
+  Steer towards the following/next point on a pre-configured polyline (or
+  polygon)
+- [`separation()`](https://docs.thi.ng/umbrella/boids/functions/separation.html):
+  Steer away from neighbors within given radius
+
+### Acceleration structures
+
+Intended for behaviors requiring neighbor lookups, the package defines &
+utilizes the [`IBoidAccel`
+interface](https://docs.thi.ng/umbrella/boids/interfaces/IBoidAccel.html). It's
+recommended to use a compatible spatial acceleration structure such as
+[`HashGrid2` or
+`HashGrid3`](https://docs.thi.ng/umbrella/geom-accel/classes/HashGrid2.html#queryNeighborhood)
+from the [@thi.ng/geom-accel
+package](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-accel).
+For cases where this isn't needed, the
+[`noAccel`](https://docs.thi.ng/umbrella/boids/functions/noAccel.html) dummy
+implementation of this interface can be used... In all cases, an acceleration
+structure has to be provided to the boid ctor and factory functions
+[`defBoid2()`](https://docs.thi.ng/umbrella/boids/functions/defBoid2.html) /
+[`defBoid3()`](https://docs.thi.ng/umbrella/boids/functions/defBoid3.html).
 
 ## Status
 
@@ -50,13 +102,16 @@ For Node.js REPL:
 const boids = await import("@thi.ng/boids");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.13 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 1.92 KB
 
 ## Dependencies
 
 - [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
+- [@thi.ng/checks](https://github.com/thi-ng/umbrella/tree/develop/packages/checks)
 - [@thi.ng/distance](https://github.com/thi-ng/umbrella/tree/develop/packages/distance)
-- [@thi.ng/geom-accel](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-accel)
+- [@thi.ng/geom-closest-point](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-closest-point)
+- [@thi.ng/geom-resample](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-resample)
+- [@thi.ng/math](https://github.com/thi-ng/umbrella/tree/develop/packages/math)
 - [@thi.ng/timestep](https://github.com/thi-ng/umbrella/tree/develop/packages/timestep)
 - [@thi.ng/vectors](https://github.com/thi-ng/umbrella/tree/develop/packages/vectors)
 
@@ -93,4 +148,4 @@ If this project contributes to an academic publication, please cite it as:
 
 ## License
 
-© 2023 Karsten Schmidt // Apache License 2.0
+© 2023 - 2024 Karsten Schmidt // Apache License 2.0

package/accel.d.ts

@@ -0,0 +1,12 @@
+import type { IBoidAccel } from "./api.js";
+/**
+ * Dummy {@link IBoidAccel} implementation (i.e does no spatial indexing and
+ * always processes _all_ boids).
+ *
+ * @remarks
+ * Due to no incurred overhead for (re)constructing the acceleration structure,
+ * for low numbers of boids this can actually be more efficient than using a
+ * `HashGrid` (from thi.ng/geom-accel package).
+ */
+export declare const noAccel: () => IBoidAccel;
+//# sourceMappingURL=accel.d.ts.map

package/accel.js

@@ -0,0 +1,16 @@
+const noAccel = () => {
+  let boids;
+  return {
+    build($boids) {
+      boids = $boids;
+    },
+    queryNeighborhood(neighborhood) {
+      for (let b of boids)
+        neighborhood.consider(b.pos.curr, b);
+      return neighborhood;
+    }
+  };
+};
+export {
+  noAccel
+};

package/api.d.ts

@@ -1,28 +1,45 @@
-import { type FnU } from "@thi.ng/api";
-import type { Vec } from "@thi.ng/vectors";
+import type { Fn, Fn2, IDeref } from "@thi.ng/api";
+import type { INeighborhood } from "@thi.ng/distance";
+import type { ReadonlyVec, Vec } from "@thi.ng/vectors";
+import type { Boid } from "./boid.js";
+export type GlobalConstraint = Fn2<Vec, Boid, Vec>;
 export interface BoidOpts {
-    constrain: FnU<Vec>;
-    maxSpeed: number;
-    maxForce: number;
     /**
-     * Min distance to neighboring boids
+     * Boid behaviors
+     */
+    behaviors: IBoidBehavior[];
+    /**
+     * Behavior update function. Default: {@link blendedBehaviorUpdate}
      */
-    minDist: number;
+    update?: Fn<Boid, Vec>;
     /**
-     * Max distance to neighboring boids
+     * Spatial acceleration structure to use for {@link Boid.neighbors} lookups.
      */
-    maxDist: number;
+    accel: IBoidAccel;
     /**
-     * Relative weight for enforcing separation
+     * Position constraint. If used, the function MUST mutate the given vector
+     * (1st arg) and also return it.
      */
-    separation: number;
+    constrain?: GlobalConstraint;
     /**
-     * Relative weight for directional alignment
+     * Max speed (per second)
      */
-    alignment: number;
+    maxSpeed: number;
     /**
-     * Relative weight for group cohesion
+     * Scale factor for applying any of the separation, alignment and cohesion
+     * forces.
+     *
+     * @defaultValue 1
      */
-    cohesion: number;
+    maxForce?: number;
+}
+export interface IBoidAccel {
+    build(boids: Boid[]): void;
+    queryNeighborhood<N extends INeighborhood<ReadonlyVec, Boid> & IDeref<Boid[]>>(neighborhood: N): N;
+}
+export interface IBoidBehavior {
+    weight(boid: Boid): number;
+    update(boid: Boid): ReadonlyVec;
 }
+export type ScalarOrField = number | Fn<Boid, number>;
 //# sourceMappingURL=api.d.ts.map

package/api.js

@@ -1 +0,0 @@
-import {} from "@thi.ng/api";

package/behaviors/alignment.d.ts

@@ -0,0 +1,3 @@
+import type { IBoidBehavior, ScalarOrField } from "../api.js";
+export declare const alignment: (maxDist: ScalarOrField, weight?: ScalarOrField) => IBoidBehavior;
+//# sourceMappingURL=alignment.d.ts.map

package/behaviors/alignment.js

@@ -0,0 +1,23 @@
+import { __ensureFn } from "../internal/ensure.js";
+const alignment = (maxDist, weight = 1) => {
+  const $maxDist = __ensureFn(maxDist);
+  const force = [];
+  return {
+    weight: __ensureFn(weight),
+    update: (boid) => {
+      const { add, setN } = boid.api;
+      const neighbors = boid.neighbors($maxDist(boid), boid.pos.curr);
+      const num = neighbors.length;
+      setN(force, 0);
+      for (let i = 0; i < num; i++) {
+        const n = neighbors[i];
+        if (n !== boid)
+          add(force, force, n.vel.curr);
+      }
+      return boid.computeSteer(force, num - 1);
+    }
+  };
+};
+export {
+  alignment
+};

package/behaviors/attraction.d.ts

@@ -0,0 +1,4 @@
+import type { ReadonlyVec } from "@thi.ng/vectors";
+import type { ScalarOrField, IBoidBehavior } from "../api.js";
+export declare const attractPolyline: (points: ReadonlyVec[], closed: boolean, lookahead?: number, weight?: ScalarOrField) => IBoidBehavior;
+//# sourceMappingURL=attraction.d.ts.map

package/behaviors/attraction.js

@@ -0,0 +1,25 @@
+import { closestPointPolyline } from "@thi.ng/geom-closest-point";
+import { __ensureFn } from "../internal/ensure.js";
+const attractPolyline = (points, closed, lookahead = 1, weight = 1) => {
+  const closest = [];
+  const pos = [];
+  return {
+    weight: __ensureFn(weight),
+    update: (boid) => {
+      const { add, normalize } = boid.api;
+      return closestPointPolyline(
+        lookahead !== 0 ? add(
+          pos,
+          normalize(pos, boid.vel.curr, lookahead),
+          boid.pos.curr
+        ) : boid.pos.curr,
+        points,
+        closed,
+        closest
+      ) ? boid.steerTowards(closest) : boid.api.ZERO;
+    }
+  };
+};
+export {
+  attractPolyline
+};

package/behaviors/braitenberg.d.ts

@@ -0,0 +1,18 @@
+import type { Fn } from "@thi.ng/api";
+import type { ReadonlyVec } from "@thi.ng/vectors";
+import type { ScalarOrField, IBoidBehavior } from "../api.js";
+/**
+ * 2D only behavior. Takes a field function to be sampled, a sensor `lookahead`
+ * distance and `angle` between left/right sensors. The returned behavior steers
+ * an agent towards the local maxima of the field function based on a given
+ * agent's position and direction. Steers toward which ever sensor yields the
+ * greater value. If both sensors yield the same reading, the behavior is a
+ * no-op (returns a zero force vector).
+ *
+ * @param field
+ * @param lookahead
+ * @param angle
+ * @param weight
+ */
+export declare const braitenberg2: (field: Fn<ReadonlyVec, number>, lookahead: number, angle: number, weight?: ScalarOrField) => IBoidBehavior;
+//# sourceMappingURL=braitenberg.d.ts.map

package/behaviors/braitenberg.js

@@ -0,0 +1,22 @@
+import { rotate } from "@thi.ng/vectors/rotate";
+import { __ensureFn } from "../internal/ensure.js";
+const braitenberg2 = (field, lookahead, angle, weight = 1) => {
+  const dir = [];
+  const left = [];
+  const right = [];
+  return {
+    weight: __ensureFn(weight),
+    update: (boid) => {
+      const { add, maddN, normalize } = boid.api;
+      normalize(dir, boid.vel.curr, lookahead);
+      const pos = boid.pos.curr;
+      const valC = field(pos);
+      const valL = field(add(left, rotate(left, dir, angle), pos));
+      const valR = field(add(right, rotate(right, dir, -angle), pos));
+      return valC > valL && valC > valR ? boid.steerTowards(maddN(left, boid.vel.curr, -1, pos)) : valL === valR ? boid.api.ZERO : boid.steerTowards(valL > valR ? left : right);
+    }
+  };
+};
+export {
+  braitenberg2
+};

package/behaviors/cohesion.d.ts

@@ -0,0 +1,3 @@
+import type { IBoidBehavior, ScalarOrField } from "../api.js";
+export declare const cohesion: (maxDist: ScalarOrField, weight?: ScalarOrField) => IBoidBehavior;
+//# sourceMappingURL=cohesion.d.ts.map

package/behaviors/cohesion.js

@@ -0,0 +1,23 @@
+import { __ensureFn } from "../internal/ensure.js";
+const cohesion = (maxDist, weight = 1) => {
+  const $maxDist = __ensureFn(maxDist);
+  const centroid = [];
+  return {
+    weight: __ensureFn(weight),
+    update: (boid) => {
+      const { add, mulN, setN } = boid.api;
+      const neighbors = boid.neighbors($maxDist(boid), boid.pos.curr);
+      const num = neighbors.length;
+      setN(centroid, 0);
+      for (let i = 0; i < num; i++) {
+        const n = neighbors[i];
+        if (n !== boid)
+          add(centroid, centroid, n.pos.curr);
+      }
+      return num > 1 ? boid.steerTowards(mulN(centroid, centroid, 1 / (num - 1))) : centroid;
+    }
+  };
+};
+export {
+  cohesion
+};

package/behaviors/dynamic.d.ts

@@ -0,0 +1,19 @@
+import type { Fn, Nullable } from "@thi.ng/api";
+import type { ReadonlyVec } from "@thi.ng/vectors";
+import type { IBoidBehavior, ScalarOrField } from "../api.js";
+import type { Boid } from "../boid.js";
+/**
+ * Boid behavior which steers toward target positions sourced from user provided
+ * `target` fn. That `target` function will be called successively for each boid
+ * update. If it returns a point, it will be used as steer target until a new
+ * one is returned. If the function returns null/undefined the current target
+ * will be kept. The behavior is a no-op for boids outside the configured
+ * `radius` (around the target) and also has no effect until the target function
+ * returns its first point.
+ *
+ * @param target
+ * @param radius
+ * @param weight
+ */
+export declare const dynamicTarget: (target: Fn<Boid, Nullable<ReadonlyVec>>, radius?: ScalarOrField, weight?: ScalarOrField) => IBoidBehavior;
+//# sourceMappingURL=dynamic.d.ts.map

package/behaviors/dynamic.js

@@ -0,0 +1,19 @@
+import { __ensureFn } from "../internal/ensure.js";
+const dynamicTarget = (target, radius = Infinity, weight = 1) => {
+  let currTarget;
+  const $radius = __ensureFn(radius);
+  const force = [];
+  return {
+    weight: __ensureFn(weight),
+    update: (boid) => {
+      currTarget = target(boid) || currTarget;
+      if (!currTarget)
+        return boid.api.ZERO;
+      const r = $radius(boid);
+      return boid.api.distSq(currTarget, boid.pos.curr) < r * r ? boid.steerTowards(currTarget, force) : boid.api.ZERO;
+    }
+  };
+};
+export {
+  dynamicTarget
+};

package/behaviors/follow.d.ts

@@ -0,0 +1,14 @@
+import type { ReadonlyVec } from "@thi.ng/vectors";
+import type { IBoidBehavior, ScalarOrField } from "../api.js";
+/**
+ * Similar to {@link attractPolyline}, but forces steering along the path in the
+ * given order of points, using normalized `lookahead`. If `closed` is false,
+ * the behavior becomes a no-op for boids at the end of the path.
+ *
+ * @param points
+ * @param closed
+ * @param lookahead
+ * @param weight
+ */
+export declare const followPolyline: (points: ReadonlyVec[], closed: boolean, lookahead?: number, weight?: ScalarOrField) => IBoidBehavior;
+//# sourceMappingURL=follow.d.ts.map

package/behaviors/follow.js

@@ -0,0 +1,18 @@
+import { Sampler } from "@thi.ng/geom-resample/sampler";
+import { fract } from "@thi.ng/math/prec";
+import { __ensureFn } from "../internal/ensure.js";
+const followPolyline = (points, closed, lookahead = 0.01, weight = 1) => {
+  const sampler = new Sampler(points, closed);
+  return {
+    weight: __ensureFn(weight),
+    update: (boid) => {
+      const t = sampler.closestT(boid.pos.curr);
+      if (t === void 0 || !closed && t + lookahead > 1)
+        return boid.api.ZERO;
+      return boid.steerTowards(sampler.pointAt(fract(t + lookahead)));
+    }
+  };
+};
+export {
+  followPolyline
+};

package/behaviors/mixed.d.ts

@@ -0,0 +1,4 @@
+import type { Vec } from "@thi.ng/vectors";
+import type { Boid } from "../boid.js";
+export declare const mixedBehaviorUpdate: (boid: Boid) => Vec;
+//# sourceMappingURL=mixed.d.ts.map

package/behaviors/mixed.js

@@ -0,0 +1,13 @@
+const mixedBehaviorUpdate = (boid) => {
+  const { maddN, zeroes } = boid.api;
+  const force = zeroes();
+  for (let behavior of boid.behaviors) {
+    const weight = behavior.weight(boid);
+    if (weight !== 0)
+      maddN(force, behavior.update(boid), weight, force);
+  }
+  return force;
+};
+export {
+  mixedBehaviorUpdate
+};

package/behaviors/path.d.ts

@@ -0,0 +1,4 @@
+import type { ReadonlyVec } from "@thi.ng/vectors";
+import type { ScalarOrField, IBoidBehavior } from "../api.js";
+export declare const followPath: (points: ReadonlyVec[], closed: boolean, weight?: ScalarOrField) => IBoidBehavior;
+//# sourceMappingURL=path.d.ts.map

package/behaviors/path.js

@@ -0,0 +1,18 @@
+import { closestPointPolyline } from "@thi.ng/geom-closest-point";
+import { __ensureFn } from "../internal/ensure.js";
+const followPath = (points, closed, weight = 1) => {
+  const closest = [];
+  const pos = [];
+  return {
+    weight: __ensureFn(weight),
+    update: (boid) => closestPointPolyline(
+      boid.api.add(pos, boid.pos.curr, boid.vel.curr),
+      points,
+      closed,
+      closest
+    ) ? boid.steerTowards(closest) : boid.api.ZERO
+  };
+};
+export {
+  followPath
+};

package/behaviors/probabilistic.d.ts

@@ -0,0 +1,4 @@
+import type { Vec } from "@thi.ng/vectors";
+import type { Boid } from "../boid.js";
+export declare const probabilisticBehaviorUpdate: (boid: Boid) => Vec;
+//# sourceMappingURL=probabilistic.d.ts.map

package/behaviors/probabilistic.js

@@ -0,0 +1,24 @@
+import { argSort } from "@thi.ng/arrays/arg-sort";
+const probabilisticBehaviorUpdate = (boid) => {
+  const { maddN, magSq, zeroes } = boid.api;
+  const force = zeroes();
+  const behaviors = boid.behaviors;
+  const num = behaviors.length;
+  const weights = behaviors.map((b) => b.weight(boid));
+  const order = argSort(weights, (a, b) => b - a);
+  for (let i = 0; i < num; i++) {
+    const id = order[i];
+    const weight = weights[id];
+    if (Math.random() < weight) {
+      const f = behaviors[id].update(boid);
+      if (magSq(f) > 0) {
+        maddN(force, f, weight, force);
+        break;
+      }
+    }
+  }
+  return force;
+};
+export {
+  probabilisticBehaviorUpdate
+};

package/behaviors/separation.d.ts

@@ -0,0 +1,3 @@
+import type { IBoidBehavior, ScalarOrField } from "../api.js";
+export declare const separation: (minDist: ScalarOrField, weight?: ScalarOrField) => IBoidBehavior;
+//# sourceMappingURL=separation.d.ts.map

package/behaviors/separation.js

@@ -0,0 +1,28 @@
+import { __ensureFn } from "../internal/ensure.js";
+const separation = (minDist, weight = 1) => {
+  const $minDist = __ensureFn(minDist);
+  const force = [];
+  const delta = [];
+  return {
+    weight: __ensureFn(weight),
+    update: (boid) => {
+      const { maddN, magSq, setN, sub } = boid.api;
+      const pos = boid.pos.curr;
+      const neighbors = boid.neighbors($minDist(boid), pos);
+      const num = neighbors.length;
+      let n;
+      setN(force, 0);
+      for (let i = 0; i < num; i++) {
+        n = neighbors[i];
+        if (n !== boid) {
+          sub(delta, pos, n.pos.curr);
+          maddN(force, delta, 1 / (magSq(delta) + 1e-6), force);
+        }
+      }
+      return boid.computeSteer(force, num - 1);
+    }
+  };
+};
+export {
+  separation
+};

package/behaviors/update.d.ts

@@ -0,0 +1,4 @@
+import type { Vec } from "@thi.ng/vectors";
+import type { Boid } from "../boid.js";
+export declare const blendedBehaviorUpdate: (boid: Boid) => Vec;
+//# sourceMappingURL=update.d.ts.map

package/behaviors/update.js

@@ -0,0 +1,13 @@
+const blendedBehaviorUpdate = (boid) => {
+  const { maddN, zeroes } = boid.api;
+  const force = zeroes();
+  for (let behavior of boid.behaviors) {
+    const weight = behavior.weight(boid);
+    if (weight !== 0)
+      maddN(force, behavior.update(boid), weight, force);
+  }
+  return force;
+};
+export {
+  blendedBehaviorUpdate
+};

package/boid.d.ts

@@ -1,22 +1,18 @@
 import type { IDistance } from "@thi.ng/distance";
-import type { AHashGrid, HashGrid2, HashGrid3 } from "@thi.ng/geom-accel/hash-grid";
 import type { ITimeStep, ReadonlyTimeStep } from "@thi.ng/timestep";
 import { VectorState } from "@thi.ng/timestep/state";
 import type { ReadonlyVec, Vec, VecAPI } from "@thi.ng/vectors";
-import type { BoidOpts } from "./api.js";
+import type { BoidOpts, IBoidAccel, IBoidBehavior } from "./api.js";
 import { Radial } from "./region.js";
 export declare class Boid implements ITimeStep {
-    readonly accel: AHashGrid<Boid>;
-    readonly api: VecAPI;
     pos: VectorState;
     vel: VectorState;
-    opts: BoidOpts;
+    api: VecAPI;
+    accel: IBoidAccel;
+    behaviors: IBoidBehavior[];
     region: Radial<Boid>;
-    protected cachedNeighbors: Boid[];
-    protected tmpSep: Vec;
-    protected tmpAlign: Vec;
-    protected tmpCoh: Vec;
-    constructor(accel: AHashGrid<Boid>, api: VecAPI, distance: IDistance<ReadonlyVec>, pos: Vec, vel: Vec, opts: Partial<BoidOpts>);
+    opts: BoidOpts;
+    constructor(opts: BoidOpts, api: VecAPI, distance: IDistance<ReadonlyVec>, pos: Vec, vel: Vec);
     /**
      * Integration step of the thi.ng/timestep update cycle. See
      * [`ITimeStep`](https://docs.thi.ng/umbrella/timestep/interfaces/ITimeStep.html)
@@ -47,12 +43,9 @@ export declare class Boid implements ITimeStep {
      * @param pos
      */
     neighbors(r: number, pos?: Vec): Boid[];
-    protected separate(): Vec;
-    protected align(): Vec;
-    protected cohesion(): Vec;
-    protected steerTowards(target: ReadonlyVec, out?: Vec): Vec;
-    protected computeSteer(steer: Vec, num: number): Vec;
-    protected limitSteer(steer: Vec): Vec;
+    steerTowards(target: ReadonlyVec, out?: Vec): Vec;
+    computeSteer(steer: Vec, num: number): Vec;
+    limitSteer(steer: Vec): Vec;
 }
 /**
  * Returns a new {@link Boid} instance configured to use optimized 2D vector
@@ -63,7 +56,7 @@ export declare class Boid implements ITimeStep {
  * @param vel
  * @param opts
  */
-export declare const defBoid2: (accel: HashGrid2<Boid>, pos: Vec, vel: Vec, opts: Partial<BoidOpts>) => Boid;
+export declare const defBoid2: (pos: Vec, vel: Vec, opts: BoidOpts) => Boid;
 /**
  * Returns a new {@link Boid} instance configured to use optimized 3D vector
  * operations.
@@ -73,5 +66,5 @@ export declare const defBoid2: (accel: HashGrid2<Boid>, pos: Vec, vel: Vec, opts
  * @param vel
  * @param opts
  */
-export declare const defBoid3: (accel: HashGrid3<Boid>, pos: Vec, vel: Vec, opts: Partial<BoidOpts>) => Boid;
+export declare const defBoid3: (pos: Vec, vel: Vec, opts: BoidOpts) => Boid;
 //# sourceMappingURL=boid.d.ts.map

package/boid.js

@@ -2,59 +2,38 @@ import { identity } from "@thi.ng/api";
 import { DIST_SQ2, DIST_SQ3 } from "@thi.ng/distance/squared";
 import { VectorState, defVector } from "@thi.ng/timestep/state";
 import { integrateAll, interpolateAll } from "@thi.ng/timestep/timestep";
-import { addW4 } from "@thi.ng/vectors/addw";
 import { VEC2 } from "@thi.ng/vectors/vec2-api";
 import { VEC3 } from "@thi.ng/vectors/vec3-api";
+import { blendedBehaviorUpdate } from "./behaviors/update.js";
 import { Radial } from "./region.js";
 class Boid {
-  constructor(accel, api, distance, pos, vel, opts) {
-    this.accel = accel;
+  pos;
+  vel;
+  api;
+  accel;
+  behaviors;
+  region;
+  opts;
+  constructor(opts, api, distance, pos, vel) {
     this.api = api;
-    this.opts = {
-      constrain: identity,
-      maxSpeed: 10,
-      maxForce: 1,
-      minDist: 20,
-      maxDist: 50,
-      separation: 2,
-      alignment: 1,
-      cohesion: 1,
-      ...opts
-    };
+    this.opts = { maxForce: 1, ...opts };
+    this.accel = this.opts.accel;
+    this.behaviors = this.opts.behaviors;
+    const update = this.opts.update || blendedBehaviorUpdate;
+    const constrain = this.opts.constrain || identity;
+    const { add, limit, maddN } = api;
     this.vel = defVector(
       api,
       vel,
-      (vel2) => api.limit(
-        vel2,
-        addW4(
-          vel2,
-          vel2,
-          this.separate(),
-          this.align(),
-          this.cohesion(),
-          1,
-          this.opts.separation,
-          this.opts.alignment,
-          this.opts.cohesion
-        ),
-        this.opts.maxSpeed
-      )
+      (vel2) => limit(vel2, add(vel2, vel2, update(this)), this.opts.maxSpeed)
     );
     this.pos = defVector(
       api,
       pos,
-      (pos2, dt) => this.opts.constrain(api.maddN(pos2, this.vel.curr, dt, pos2))
+      (pos2, dt) => constrain(maddN(pos2, this.vel.curr, dt, pos2), this)
     );
     this.region = new Radial(distance, pos, 1);
   }
-  pos;
-  vel;
-  opts;
-  region;
-  cachedNeighbors;
-  tmpSep = [];
-  tmpAlign = [];
-  tmpCoh = [];
   /**
    * Integration step of the thi.ng/timestep update cycle. See
    * [`ITimeStep`](https://docs.thi.ng/umbrella/timestep/interfaces/ITimeStep.html)
@@ -63,10 +42,6 @@ class Boid {
    * @param ctx
    */
   integrate(dt, ctx) {
-    this.cachedNeighbors = this.neighbors(
-      this.opts.maxDist,
-      this.pos.value
-    );
     integrateAll(dt, ctx, this.vel, this.pos);
   }
   /**
@@ -99,49 +74,6 @@ class Boid {
     region.setRadius(r);
     return this.accel.queryNeighborhood(region).deref();
   }
-  separate() {
-    const { maddN, magSq, setN, sub } = this.api;
-    const pos = this.pos.value;
-    const neighbors = this.neighbors(this.opts.minDist);
-    const num = neighbors.length;
-    const delta = [];
-    const steer = setN(this.tmpSep, 0);
-    let n;
-    for (let i = 0; i < num; i++) {
-      n = neighbors[i];
-      if (n !== this) {
-        sub(delta, pos, n.pos.curr);
-        maddN(steer, delta, 1 / (magSq(delta) + 1e-6), steer);
-      }
-    }
-    return this.computeSteer(steer, num);
-  }
-  align() {
-    const { add, setN } = this.api;
-    const neighbors = this.cachedNeighbors;
-    const num = neighbors.length;
-    const sum = setN(this.tmpAlign, 0);
-    let n;
-    for (let i = 0; i < num; i++) {
-      n = neighbors[i];
-      if (n !== this)
-        add(sum, sum, n.vel.curr);
-    }
-    return this.computeSteer(sum, num);
-  }
-  cohesion() {
-    const { add, mulN, setN } = this.api;
-    const neighbors = this.cachedNeighbors;
-    const num = neighbors.length;
-    const sum = setN(this.tmpCoh, 0);
-    let n;
-    for (let i = 0; i < num; i++) {
-      n = neighbors[i];
-      if (n !== this)
-        add(sum, sum, n.pos.curr);
-    }
-    return num > 0 ? this.steerTowards(mulN(sum, sum, 1 / num)) : sum;
-  }
   steerTowards(target, out = target) {
     return this.limitSteer(this.api.sub(out, target, this.pos.curr));
   }
@@ -158,15 +90,15 @@ class Boid {
       msubN(
         steer,
         steer,
-        this.opts.maxSpeed ** 2 / m,
+        this.opts.maxSpeed / Math.sqrt(m),
         this.vel.curr
       ),
       this.opts.maxForce
     ) : steer;
   }
 }
-const defBoid2 = (accel, pos, vel, opts) => new Boid(accel, VEC2, DIST_SQ2, pos, vel, opts);
-const defBoid3 = (accel, pos, vel, opts) => new Boid(accel, VEC3, DIST_SQ3, pos, vel, opts);
+const defBoid2 = (pos, vel, opts) => new Boid(opts, VEC2, DIST_SQ2, pos, vel);
+const defBoid3 = (pos, vel, opts) => new Boid(opts, VEC3, DIST_SQ3, pos, vel);
 export {
   Boid,
   defBoid2,

package/constrain.d.ts

@@ -0,0 +1,7 @@
+import type { ReadonlyVec } from "@thi.ng/vectors";
+import type { GlobalConstraint } from "./api.js";
+export declare const clamp2: (min: ReadonlyVec, max: ReadonlyVec) => GlobalConstraint;
+export declare const clamp3: (min: ReadonlyVec, max: ReadonlyVec) => GlobalConstraint;
+export declare const wrap2: (min: ReadonlyVec, max: ReadonlyVec) => GlobalConstraint;
+export declare const wrap3: (min: ReadonlyVec, max: ReadonlyVec) => GlobalConstraint;
+//# sourceMappingURL=constrain.d.ts.map

package/constrain.js

@@ -0,0 +1,44 @@
+import { wrapOnce } from "@thi.ng/math/interval";
+import { clamp2 as $clamp2, clamp3 as $clamp3 } from "@thi.ng/vectors/clamp";
+const clamp2 = (min, max) => (p) => $clamp2(p, p, min, max);
+const clamp3 = (min, max) => (p) => $clamp3(p, p, min, max);
+const wrap2 = (min, max) => (p, boid) => {
+  const [x, y] = p;
+  let wrap = false;
+  if (x < min[0] || x > max[0]) {
+    p[0] = wrapOnce(x, min[0], max[0]);
+    wrap = true;
+  }
+  if (y < min[1] || y > max[1]) {
+    p[1] = wrapOnce(y, min[1], max[1]);
+    wrap = true;
+  }
+  if (wrap)
+    boid.pos.reset(p);
+  return p;
+};
+const wrap3 = (min, max) => (p, boid) => {
+  let [x, y, z] = p;
+  let wrap = false;
+  if (x < min[0] || x > max[0]) {
+    p[0] = wrapOnce(x, min[0], max[0]);
+    wrap = true;
+  }
+  if (y < min[1] || y > max[1]) {
+    p[1] = wrapOnce(y, min[1], max[1]);
+    wrap = true;
+  }
+  if (z < min[2] || z > max[2]) {
+    p[2] = wrapOnce(z, min[2], max[2]);
+    wrap = true;
+  }
+  if (wrap)
+    boid.pos.reset(p);
+  return p;
+};
+export {
+  clamp2,
+  clamp3,
+  wrap2,
+  wrap3
+};

package/flock.d.ts

@@ -0,0 +1,27 @@
+import type { ITimeStep, ReadonlyTimeStep } from "@thi.ng/timestep";
+import type { IBoidAccel } from "./api.js";
+import type { Boid } from "./boid.js";
+/**
+ * Returns a new {@link Flock} instance.
+ *
+ * @param accel
+ * @param boids
+ */
+export declare const defFlock: (accel: IBoidAccel, boids?: Boid[]) => Flock;
+/**
+ * Convenience class for managing a number of boids (can be added
+ * dynamically) and their {@link IBoidAccel} structure. Like {@link Boid}
+ * itself, this class implements the `ITimeStep` interface too and the
+ * {@link ITimeStep.integrate} phase will automatically update the
+ * acceleration structure before integrating the boids.
+ */
+export declare class Flock implements ITimeStep {
+    accel: IBoidAccel;
+    boids: Boid[];
+    constructor(accel: IBoidAccel, boids?: Boid[]);
+    add(boid: Boid): void;
+    remove(boid: Boid): void;
+    integrate(dt: number, ctx: ReadonlyTimeStep): void;
+    interpolate(alpha: number, ctx: ReadonlyTimeStep): void;
+}
+//# sourceMappingURL=flock.d.ts.map

package/flock.js

@@ -0,0 +1,27 @@
+import { integrateAll, interpolateAll } from "@thi.ng/timestep/timestep";
+const defFlock = (accel, boids) => new Flock(accel, boids);
+class Flock {
+  constructor(accel, boids = []) {
+    this.accel = accel;
+    this.boids = boids;
+  }
+  add(boid) {
+    this.boids.push(boid);
+  }
+  remove(boid) {
+    const idx = this.boids.indexOf(boid);
+    if (idx >= 0)
+      this.boids.splice(idx, 1);
+  }
+  integrate(dt, ctx) {
+    this.accel.build(this.boids);
+    integrateAll(dt, ctx, ...this.boids);
+  }
+  interpolate(alpha, ctx) {
+    interpolateAll(alpha, ctx, ...this.boids);
+  }
+}
+export {
+  Flock,
+  defFlock
+};

package/index.d.ts

@@ -1,4 +1,15 @@
+export * from "./accel.js";
 export * from "./api.js";
 export * from "./boid.js";
+export * from "./constrain.js";
+export * from "./flock.js";
 export * from "./region.js";
+export * from "./behaviors/alignment.js";
+export * from "./behaviors/attraction.js";
+export * from "./behaviors/braitenberg.js";
+export * from "./behaviors/cohesion.js";
+export * from "./behaviors/dynamic.js";
+export * from "./behaviors/follow.js";
+export * from "./behaviors/separation.js";
+export * from "./behaviors/update.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,3 +1,14 @@
+export * from "./accel.js";
 export * from "./api.js";
 export * from "./boid.js";
+export * from "./constrain.js";
+export * from "./flock.js";
 export * from "./region.js";
+export * from "./behaviors/alignment.js";
+export * from "./behaviors/attraction.js";
+export * from "./behaviors/braitenberg.js";
+export * from "./behaviors/cohesion.js";
+export * from "./behaviors/dynamic.js";
+export * from "./behaviors/follow.js";
+export * from "./behaviors/separation.js";
+export * from "./behaviors/update.js";

package/internal/ensure.d.ts

@@ -0,0 +1,3 @@
+import type { ScalarOrField } from "../api.js";
+export declare const __ensureFn: (x: ScalarOrField) => import("@thi.ng/api").Fn<import("../boid.js").Boid, number>;
+//# sourceMappingURL=ensure.d.ts.map

package/internal/ensure.js

@@ -0,0 +1,5 @@
+import { isNumber } from "@thi.ng/checks/is-number";
+const __ensureFn = (x) => isNumber(x) ? () => x : x;
+export {
+  __ensureFn
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thi.ng/boids",
-  "version": "0.1.15",
-  "description": "n-dimensional boids simulation with highly configurable behaviors",
+  "version": "1.0.0",
+  "description": "n-dimensional boids simulation with modular behavior system",
   "type": "module",
   "module": "./index.js",
   "typings": "./index.d.ts",
@@ -35,11 +35,14 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.9.16",
-    "@thi.ng/distance": "^2.4.40",
-    "@thi.ng/geom-accel": "^3.5.40",
-    "@thi.ng/timestep": "^0.5.15",
-    "@thi.ng/vectors": "^7.8.15"
+    "@thi.ng/api": "^8.9.17",
+    "@thi.ng/checks": "^3.4.17",
+    "@thi.ng/distance": "^2.4.41",
+    "@thi.ng/geom-closest-point": "^2.1.95",
+    "@thi.ng/geom-resample": "^2.3.21",
+    "@thi.ng/math": "^5.7.12",
+    "@thi.ng/timestep": "^0.5.16",
+    "@thi.ng/vectors": "^7.9.0"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.39.0",
@@ -52,12 +55,26 @@
     "nd",
     "2d",
     "3d",
+    "acceleration",
+    "align",
+    "attractor",
     "behavior",
+    "braitenberg",
     "boids",
+    "constraint",
     "flocking",
+    "follow",
+    "force",
+    "modular",
+    "path",
+    "physics",
+    "polyline",
+    "polygon",
     "points",
+    "separation",
     "simulation",
     "spatial",
+    "steering",
     "time",
     "typescript",
     "vector"
@@ -74,22 +91,57 @@
   },
   "files": [
     "./*.js",
-    "./*.d.ts"
+    "./*.d.ts",
+    "behaviors",
+    "internal"
   ],
   "exports": {
     ".": {
       "default": "./index.js"
     },
+    "./accel": {
+      "default": "./accel.js"
+    },
     "./api": {
       "default": "./api.js"
     },
+    "./behaviors/alignment": {
+      "default": "./behaviors/alignment.js"
+    },
+    "./behaviors/attraction": {
+      "default": "./behaviors/attraction.js"
+    },
+    "./behaviors/braitenberg": {
+      "default": "./behaviors/braitenberg.js"
+    },
+    "./behaviors/cohesion": {
+      "default": "./behaviors/cohesion.js"
+    },
+    "./behaviors/dynamic": {
+      "default": "./behaviors/dynamic.js"
+    },
+    "./behaviors/follow": {
+      "default": "./behaviors/follow.js"
+    },
+    "./behaviors/separation": {
+      "default": "./behaviors/separation.js"
+    },
+    "./behaviors/update": {
+      "default": "./behaviors/update.js"
+    },
     "./boid": {
       "default": "./boid.js"
+    },
+    "./constrain": {
+      "default": "./constrain.js"
+    },
+    "./flock": {
+      "default": "./flock.js"
     }
   },
   "thi.ng": {
     "status": "alpha",
     "year": 2023
   },
-  "gitHead": "b3db173682e1148cf08a6bd907b8d90b47b7c066\n"
+  "gitHead": "417b5a7ea7bd54a3b4f086fe0fc2ce8e8933c9b2\n"
 }