[!NOTE] This is one of 211 standalone projects, maintained as part of the @thi.ng/umbrella monorepo and anti-framework.

🚀 Please help me to work full-time on these projects by sponsoring me on GitHub. Thank you! ❤️

• About
  • Available behaviors
  • Acceleration structures
• Status
• Installation
• Dependencies
• Usage examples
• API
• Authors
• License

About

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(): Steer towards the average direction of neighbors within given radius
• attractPolyline(): Steer towards the nearest point on a pre-configured polyline (or polygon)
• braitenberg2(): Field-based 3-sensor (left/right/center) Braitenberg vehicle steering
• cohesion(): Steer towards the centroid of neighbors within given radius
• dynamicTarget(): Steer towards user defined (dynamically changeable) location(s)
• followPolyline(): Steer towards the following/next point on a pre-configured polyline (or polygon)
• separation(): Steer away from neighbors within given radius

Acceleration structures

Intended for behaviors requiring neighbor lookups, the package defines & utilizes the IBoidAccel interface. It's recommended to use a compatible spatial acceleration structure such as HashGrid2 or HashGrid3 from the @thi.ng/geom-accel package. For cases where this isn't needed, the noAccel 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() / defBoid3().

Status

ALPHA - bleeding edge / work-in-progress

Search or submit any issues for this package

Installation

yarn add @thi.ng/boids

ESM import:

import * as boids from "@thi.ng/boids";

Browser ESM import:

<script type="module" src="https://esm.run/@thi.ng/boids"></script>

JSDelivr documentation

For Node.js REPL:

const boids = await import("@thi.ng/boids");

Package sizes (brotli'd, pre-treeshake): ESM: 2.00 KB

Dependencies

• @thi.ng/api
• @thi.ng/checks
• @thi.ng/distance
• @thi.ng/geom-closest-point
• @thi.ng/geom-resample
• @thi.ng/math
• @thi.ng/timestep
• @thi.ng/vectors

Note: @thi.ng/api is in most cases a type-only import (not used at runtime)

Usage examples

One project in this repo's /examples directory is using this package:

| Screenshot | Description | Live demo | Source | |:-------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------|:--------------------------------------------------|:-------------------------------------------------------------------------------| | | Basic 2D boid simulation and spatial indexing neighbor lookups | Demo | Source |

API

Generated API docs

TODO

Authors

• Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

@misc{thing-boids,
  title = "@thi.ng/boids",
  author = "Karsten Schmidt",
  note = "https://thi.ng/boids",
  year = 2023
}

License

© 2023 - 2025 Karsten Schmidt // Apache License 2.0