Skip to content

Latest commit

 

History

History
 
 

boids

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
src
src
 
 
test
test
 
 
CHANGELOG.md
CHANGELOG.md
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
api-extractor.json
api-extractor.json
 
 
package.json
package.json
 
 
tpl.readme.md
tpl.readme.md
 
 
tsconfig.json
tsconfig.json
 
 

README.md

@thi.ng/boids

npm version npm downloads Mastodon Follow

Note

This is one of 199 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

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: 1.91 KB

Dependencies

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

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 - 2024 Karsten Schmidt // Apache License 2.0