https://github.com/str4y-cat/three-boids
A tool for simulating flocking entities/boids on the web
https://github.com/str4y-cat/three-boids
boids boids-simulation three-js webgl
Last synced: 4 months ago
JSON representation
A tool for simulating flocking entities/boids on the web
- Host: GitHub
- URL: https://github.com/str4y-cat/three-boids
- Owner: Str4y-Cat
- License: mit
- Created: 2024-07-23T14:44:08.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2024-08-03T16:14:54.000Z (11 months ago)
- Last Synced: 2025-03-02T02:30:51.059Z (4 months ago)
- Topics: boids, boids-simulation, three-js, webgl
- Language: JavaScript
- Homepage: https://boidsimulation-leo-kamhoots-projects.vercel.app
- Size: 71.6 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
# 3D Boids Simulation Tool
[![NPM Package][npm-img]][npm-url]
[![DeepScan][deepscan]][deepscan-url]
## Description
three-boids-js is a JavaScript library that aims to provide a straightforward API to create and control flocking/schooling entities([boids](https://en.wikipedia.org/wiki/Boids)) with minimal setup.
## Features
- **Easy Setup:** Quickly initialize boid simulations with a simple configuration.
- **Customizable Behavior:** Take controll over a variety parameters to tweak the boid behavior, update parameters in real time using the debug panel.
- **Performance Optimized:** Efficiently handles large numbers of boids with smooth animations.
- - _Instanced Meshes_ All boid meshes are dynamically instanced, resulting in only 1 draw call
- - _Octree and BVH Optimized raycasting_ takes advantage of special datastructures to effectively nullify cost
- **Object Avoidance:** Easily add objects for boids to avoid. Uses Optimized raycasting algorithms with tweakable parameters
## Quick Start
Install three-boids npm package:
```js
npm i three-boids
```
then
```js
import BOIDS from 'three-boids'
```
Create a standard three.js project, then
```js
//create a boundning box and new boids instance
const box = new THREE.Box3(new THREE.Vector3(-5,-5,-5),new THREE.Vector3(5,5,5))
const boids = new BOIDS(scene,box)
//initiate the boid simulation
boids.initBoids(200)
//add a mesh for the boids
const geometry=new THREE.ConeGeometry(0.2,0.9,3)
geometry.rotateX(-Math.PI * 0.5);
const mesh= new THREE.Mesh(geometry,new THREE.MeshBasicMaterial({color:"blue"}))
boids.setModelMesh(mesh,2)
//initiate the boids vision and add objects to avoid
boids.initVision()
const environmentObject= new THREE.Mesh(new THREE.BoxGeometry(1,1,1), new THREE.MeshBasicMaterial())
boids.addEnvironmentObjects([environmentObject],true)
//within your tick function, update the simulation
boids.update(elapsedTime,deltaTime)
```
## API Reference
### Initialisation
| Method | Description | Default |
|----------|----------|----------|
| setParameters({_parameters_})|Sets the start up boid parameters|`{visualRange:0.75046, protectedRange:0.38377, enviromentVision:0.5, objectAvoidFactor:1, cohesionFactor:0.00408, matchingFactor:0.06312, seperationFactor:0.19269, minSpeed:2.379, maxSpeed:5.206, turnFactor:0.201}`|
| initBoids(_count_) | Creates a new Boids instance, setting up the logic and setting the simulation running | `200` |
| initVision() | Creates a new raycasting instance | |
### General
| Method | Description | Default |
|----------|----------|----------|
| setModelMesh(_model,scale,customMaterial_) | Create mesh for every boid and add to scene. Add a custom material if you want a different material to the supplied mesh | |
| changeModelMesh(_model,scale,customMaterial_) | Changes the mesh for every boid. Add a custom material if you want a different material to the supplied mesh | |
| addBoid(_count_)|Adds _count_ amount of boids to the simulation||
| removeBoid(_count_)|Removes _count_ amount of boids to the simulation||
| getBoidArray()|Exposes an array containing boid positions and directions||
| addEnvironmentObjects(_enviromentObjects,reset_) | Adds new objects for boids to see | `reset = false` |
### Each Frame
| Method | Description | Default |
|----------|----------|----------|
| update(_elapsedTime,deltaTime_) | Updates the Simulation | |
### Debug
| Method | Description | Default |
|----------|----------|----------|
| addDebug(_gui_) | Adds debug panel to the scene | |
| resetDebug(_gui_) | Resets the debug panel | |
## Controls
### General Controls:
- **View FPS:** Toggles "Frames Per Second" display
- **Pause Simulation:** Pauses Simulation
### Boid Controls:
- **Show Bounding Box:** Shows/Hides the Bounding box
- **Entity Count:** The amount of boids currently on screen
- **Object Avoid Factor:** The force at which boids avoid world objects
- **Object Visual Range:** The distance at which boids see world objects
- **Cohesion Factor:** Adjust how strongly boids are attracted to the center of the flock.
- **Alignment Factor:** Control how much boids try to match the velocity of neighbor boids within their _visual range_
- **Separation Factor:** The force at which boids avoid neighbor boids within their _protected range_
- **Matching Factor:** The force at which boids align velociy with neighbor boids within their _visual range_
- **Turn Factor:** The force at which boids turn around when out of bounds
- **Min Speed:** Set the minimum speed of boids.
- **Max Speed:** Set the maximum speed of boids.
- **Visual Range:** Adjust the range in which boids detect and react to nearby flockmates.
- **Protected Range:** Define the area in which boids are protected from external disturbances.
### Environment Vision Controls:
- **Show Rays:** Toggles display of ray targets. This represents the angle that the boid can see
- **Ray Count:** How many rays the boid casts per environment check
- **Ray Angle:** The angle at which the boid casts rays
- **Ray Distance:** The distance at which a collision is counted
## Future Goals
- Move the boid logic onto the gpu, using THREE.js/webGL GPGPU
- Add support for attraction/repulsion objects
## Performance
This implementation of the boids algorithm runs on the cpu. As such it has a O(N2) time complexity.
FPS does take a hit once you pass 500 entities. Onced moved onto the gpu, we should be able to handle orders of magnitude more
## References
- [Cornell University Lab](https://people.ece.cornell.edu/land/courses/ece4760/labs/s2021/Boids/Boids.html)
- [Original Paper by C.W.Reynolds](https://www.cs.toronto.edu/~dt/siggraph97-course/cwr87/)
- [distributing n points on a sphere](https://stackoverflow.com/questions/9600801/evenly-distributing-n-points-on-a-sphere)
- [Measurement of areas on a sphere using Fibonacci and latitude–longitude lattices](https://arxiv.org/pdf/0912.4540)
[npm-img]: https://img.shields.io/npm/v/three-boids
[npm-url]: https://npmjs.org/package/three-boids
[deepscan]: https://deepscan.io/api/teams/24470/projects/27658/branches/887097/badge/grade.svg
[deepscan-url]: https://deepscan.io/dashboard#view=project&tid=24470&pid=27658&bid=887097