@thi.ng/boids 1.0.78 → 1.1.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-04-30T12:52:32Z
+- **Last updated**: 2025-05-08T15:13:02Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,21 @@ 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.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/boids@1.1.0) (2025-05-08)
+
+#### 🚀 Features
+
+- add optional amp param for behaviors ([74720a5](https://github.com/thi-ng/umbrella/commit/74720a5))
+  - update alignment(), cohesion(), separation() behaviors
+- add optional `BoidOpts.id` ([965c2ad](https://github.com/thi-ng/umbrella/commit/965c2ad))
+
+#### ♻️ Refactoring
+
+- rename Boid internals ([8bdd9cd](https://github.com/thi-ng/umbrella/commit/8bdd9cd))
+  - rename `.computeSteer()` => `.averageForce()`
+  - rename `.limitSteer()` => `.limitForce()`
+  - add docs
+
 ### [1.0.34](https://github.com/thi-ng/umbrella/tree/@thi.ng/boids@1.0.34) (2024-06-21)
 
 #### ♻️ Refactoring

package/README.md

@@ -111,7 +111,7 @@ For Node.js REPL:
 const boids = await import("@thi.ng/boids");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.91 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 1.92 KB
 
 ## Dependencies
 

package/api.d.ts

@@ -4,6 +4,10 @@ import type { ReadonlyVec, Vec } from "@thi.ng/vectors";
 import type { Boid } from "./boid.js";
 export type GlobalConstraint = Fn2<Vec, Boid, Vec>;
 export interface BoidOpts {
+    /**
+     * Optional ID for this boid.
+     */
+    id?: number;
     /**
      * Boid behaviors
      */

package/behaviors/alignment.d.ts

@@ -1,3 +1,5 @@
+import type { FnU2 } from "@thi.ng/api";
 import type { IBoidBehavior, ScalarOrField } from "../api.js";
-export declare const alignment: (maxDist: ScalarOrField, weight?: ScalarOrField) => IBoidBehavior;
+import type { Boid } from "../boid.js";
+export declare const alignment: (maxDist: ScalarOrField, weight?: ScalarOrField, amp?: FnU2<Boid, number>) => IBoidBehavior;
 //# sourceMappingURL=alignment.d.ts.map

package/behaviors/alignment.js

@@ -1,19 +1,21 @@
 import { __ensureFn } from "../internal/ensure.js";
-const alignment = (maxDist, weight = 1) => {
+const alignment = (maxDist, weight = 1, amp) => {
   const $maxDist = __ensureFn(maxDist);
   const force = [];
   return {
     weight: __ensureFn(weight),
     update: (boid) => {
-      const { add, setN } = boid.api;
+      const { add, maddN, 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);
+        if (n !== boid) {
+          amp ? maddN(force, n.vel.curr, amp(boid, n), force) : add(force, force, n.vel.curr);
+        }
       }
-      return boid.computeSteer(force, num - 1);
+      return boid.averageForce(force, num - 1);
     }
   };
 };

package/behaviors/cohesion.d.ts

@@ -1,3 +1,5 @@
+import type { FnU2 } from "@thi.ng/api";
 import type { IBoidBehavior, ScalarOrField } from "../api.js";
-export declare const cohesion: (maxDist: ScalarOrField, weight?: ScalarOrField) => IBoidBehavior;
+import type { Boid } from "../boid.js";
+export declare const cohesion: (maxDist: ScalarOrField, weight?: ScalarOrField, amp?: FnU2<Boid, number>) => IBoidBehavior;
 //# sourceMappingURL=cohesion.d.ts.map

package/behaviors/cohesion.js

@@ -1,17 +1,19 @@
 import { __ensureFn } from "../internal/ensure.js";
-const cohesion = (maxDist, weight = 1) => {
+const cohesion = (maxDist, weight = 1, amp) => {
   const $maxDist = __ensureFn(maxDist);
   const centroid = [];
   return {
     weight: __ensureFn(weight),
     update: (boid) => {
-      const { add, mulN, setN } = boid.api;
+      const { add, maddN, 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);
+        if (n !== boid) {
+          amp ? maddN(centroid, n.pos.curr, amp(boid, n), centroid) : add(centroid, centroid, n.pos.curr);
+        }
       }
       return num > 1 ? boid.steerTowards(mulN(centroid, centroid, 1 / (num - 1))) : centroid;
     }

package/behaviors/separation.d.ts

@@ -1,3 +1,16 @@
+import type { FnU2 } from "@thi.ng/api";
 import type { IBoidBehavior, ScalarOrField } from "../api.js";
-export declare const separation: (minDist: ScalarOrField, weight?: ScalarOrField) => IBoidBehavior;
+import type { Boid } from "../boid.js";
+/**
+ * Separation behavior. Attempts to repel other boids closer the given
+ * `minDist`. The behavior itself can be weighted via `weight`. The force for
+ * resolving individual boid "collisions" can be amplified via optional `amp`
+ * function, which receives current boid as first arg and current neighbor as
+ * second. The default `amp` is uniformly 1.
+ *
+ * @param minDist
+ * @param weight
+ * @param amp
+ */
+export declare const separation: (minDist: ScalarOrField, weight?: ScalarOrField, amp?: FnU2<Boid, number>) => IBoidBehavior;
 //# sourceMappingURL=separation.d.ts.map

package/behaviors/separation.js

@@ -1,5 +1,5 @@
 import { __ensureFn } from "../internal/ensure.js";
-const separation = (minDist, weight = 1) => {
+const separation = (minDist, weight = 1, amp) => {
   const $minDist = __ensureFn(minDist);
   const force = [];
   const delta = [];
@@ -16,10 +16,15 @@ const separation = (minDist, weight = 1) => {
         n = neighbors[i];
         if (n !== boid) {
           sub(delta, pos, n.pos.curr);
-          maddN(force, delta, 1 / (magSq(delta) + 1e-6), force);
+          maddN(
+            force,
+            delta,
+            (amp?.(boid, n) ?? 1) / (magSq(delta) + 1e-6),
+            force
+          );
         }
       }
-      return boid.computeSteer(force, num - 1);
+      return boid.averageForce(force, num - 1);
     }
   };
 };

package/boid.d.ts

@@ -44,8 +44,21 @@ export declare class Boid implements ITimeStep {
      */
     neighbors(r: number, pos?: Vec): Boid[];
     steerTowards(target: ReadonlyVec, out?: Vec): Vec<number>;
-    computeSteer(steer: Vec, num: number): Vec<number>;
-    limitSteer(steer: Vec): Vec<number>;
+    /**
+     * Mutably divides given `force` by `num` (if > 0) and limits result via
+     * {@link Boid.limitForce}.
+     *
+     * @param force
+     * @param num
+     */
+    averageForce(force: Vec, num: number): Vec<number>;
+    /**
+     * If force > 0, computes: `limit(normalize(force, maxSpeed) - vel, maxForce)`.
+     * Otherwise, returns input as is.
+     *
+     * @param force
+     */
+    limitForce(force: Vec): Vec<number>;
 }
 /**
  * Returns a new {@link Boid} instance configured to use optimized 2D vector

package/boid.js

@@ -74,26 +74,39 @@ class Boid {
     return this.accel.queryNeighborhood(region).deref();
   }
   steerTowards(target, out = target) {
-    return this.limitSteer(this.api.sub(out, target, this.pos.curr));
+    return this.limitForce(this.api.sub(out, target, this.pos.curr));
   }
-  computeSteer(steer, num) {
-    return this.limitSteer(
-      num > 0 ? this.api.mulN(steer, steer, 1 / num) : steer
+  /**
+   * Mutably divides given `force` by `num` (if > 0) and limits result via
+   * {@link Boid.limitForce}.
+   *
+   * @param force
+   * @param num
+   */
+  averageForce(force, num) {
+    return this.limitForce(
+      num > 0 ? this.api.mulN(force, force, 1 / num) : force
     );
   }
-  limitSteer(steer) {
+  /**
+   * If force > 0, computes: `limit(normalize(force, maxSpeed) - vel, maxForce)`.
+   * Otherwise, returns input as is.
+   *
+   * @param force
+   */
+  limitForce(force) {
     const { limit, magSq, msubN } = this.api;
-    const m = magSq(steer);
+    const m = magSq(force);
     return m > 0 ? limit(
-      steer,
+      force,
       msubN(
-        steer,
-        steer,
+        force,
+        force,
         this.opts.maxSpeed / Math.sqrt(m),
         this.vel.curr
       ),
       this.opts.maxForce
-    ) : steer;
+    ) : force;
   }
 }
 const defBoid2 = (pos, vel, opts) => new Boid(opts, VEC2, DIST_SQ2, pos, vel);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/boids",
-  "version": "1.0.78",
+  "version": "1.1.0",
   "description": "n-dimensional boids simulation with modular behavior system",
   "type": "module",
   "module": "./index.js",
@@ -147,5 +147,5 @@
     "status": "alpha",
     "year": 2023
   },
-  "gitHead": "21e1e46f087a0b8e53b7eafa38ac38a83596ef8f\n"
+  "gitHead": "8e61726779260744ea70bfe38438e755d6b53844\n"
 }