{"id":23907480,"url":"https://github.com/Str4y-Cat/three-boids","last_synced_at":"2025-09-10T15:31:34.353Z","repository":{"id":249846528,"uuid":"832699714","full_name":"Str4y-Cat/three-boids","owner":"Str4y-Cat","description":"A tool for simulating flocking entities/boids on the web","archived":false,"fork":false,"pushed_at":"2024-08-03T16:14:54.000Z","size":75074,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-02T19:52:09.435Z","etag":null,"topics":["boids","boids-simulation","three-js","webgl"],"latest_commit_sha":null,"homepage":"https://boidsimulation-leo-kamhoots-projects.vercel.app","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Str4y-Cat.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-23T14:44:08.000Z","updated_at":"2025-08-09T17:29:11.000Z","dependencies_parsed_at":"2024-10-30T05:27:19.646Z","dependency_job_id":null,"html_url":"https://github.com/Str4y-Cat/three-boids","commit_stats":{"total_commits":101,"total_committers":1,"mean_commits":101.0,"dds":0.0,"last_synced_commit":"7f9be3f61b0deaf2d0ff1a659a877f50f4b27f86"},"previous_names":["str4y-cat/boids","str4y-cat/three-boids-js","str4y-cat/three-boids"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Str4y-Cat/three-boids","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Str4y-Cat%2Fthree-boids","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Str4y-Cat%2Fthree-boids/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Str4y-Cat%2Fthree-boids/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Str4y-Cat%2Fthree-boids/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Str4y-Cat","download_url":"https://codeload.github.com/Str4y-Cat/three-boids/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Str4y-Cat%2Fthree-boids/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274482364,"owners_count":25293627,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-10T02:00:12.551Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boids","boids-simulation","three-js","webgl"],"created_at":"2025-01-05T03:12:06.254Z","updated_at":"2025-09-10T15:31:29.312Z","avatar_url":"https://github.com/Str4y-Cat.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 3D Boids Simulation Tool\n[![NPM Package][npm-img]][npm-url]\n[![DeepScan][deepscan]][deepscan-url]\n\n\n![Boid Simulation](https://github.com/Str4y-Cat/three-boids-js/blob/main/examples/boidvideo.gif)\n## Description\nthree-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.\n\n## Features\n- **Easy Setup:** Quickly initialize boid simulations with a simple configuration.\n- **Customizable Behavior:** Take controll over a variety parameters to tweak the boid behavior, update parameters in real time using the debug panel.\n-  **Performance Optimized:** Efficiently handles large numbers of boids with smooth animations.\n-  - _Instanced Meshes_ All boid meshes are dynamically instanced, resulting in only 1 draw call\n-  - _Octree and BVH Optimized raycasting_ takes advantage of special datastructures to effectively nullify cost\n- **Object Avoidance:** Easily add objects for boids to avoid. Uses Optimized raycasting algorithms with tweakable parameters\n\n## Quick Start\n\nInstall three-boids npm package:\n```js\nnpm i three-boids\n```\n\nthen \n\n```js\nimport BOIDS from 'three-boids'\n```\n\nCreate a standard three.js project, then \n\n```js\n//create a boundning box and new boids instance\nconst box = new THREE.Box3(new THREE.Vector3(-5,-5,-5),new THREE.Vector3(5,5,5))\nconst boids = new BOIDS(scene,box)\n\n//initiate the boid simulation\nboids.initBoids(200)\n\n//add a mesh for the boids\nconst geometry=new THREE.ConeGeometry(0.2,0.9,3)\ngeometry.rotateX(-Math.PI * 0.5);\nconst mesh= new THREE.Mesh(geometry,new THREE.MeshBasicMaterial({color:\"blue\"}))\nboids.setModelMesh(mesh,2)\n\n//initiate the boids vision and add objects to avoid\nboids.initVision()\nconst environmentObject= new THREE.Mesh(new THREE.BoxGeometry(1,1,1), new THREE.MeshBasicMaterial())\nboids.addEnvironmentObjects([environmentObject],true)\n\n//within your tick function, update the simulation\nboids.update(elapsedTime,deltaTime)\n\n\n```\n\n## API Reference\n\n### Initialisation\n| Method | Description | Default |\n|----------|----------|----------|\n|\u003cb\u003e setParameters\u003c/b\u003e({_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}`|\n| \u003cb\u003e initBoids\u003c/b\u003e(_count_) | Creates a new Boids instance, setting up the logic and setting the simulation running  | `200` |\n| \u003cb\u003e initVision\u003c/b\u003e() | Creates a new raycasting instance | |\n### General\n| Method | Description | Default |\n|----------|----------|----------|\n| \u003cb\u003e setModelMesh\u003c/b\u003e(_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 |  |\n| \u003cb\u003e changeModelMesh\u003c/b\u003e(_model,scale,customMaterial_) | Changes the mesh for every boid. Add a custom material if you want a different material to the supplied mesh | |\n| \u003cb\u003e addBoid\u003c/b\u003e(_count_)|Adds _count_ amount of boids to the simulation||\n|\u003cb\u003e removeBoid\u003c/b\u003e(_count_)|Removes _count_ amount of boids to the simulation||\n|\u003cb\u003e getBoidArray\u003c/b\u003e()|Exposes an array containing boid positions and directions||\n| \u003cb\u003e addEnvironmentObjects\u003cb\u003e(_enviromentObjects,reset_) | Adds new objects for boids to see | `reset = false` |\n### Each Frame\n| Method | Description | Default |\n|----------|----------|----------|\n| \u003cb\u003e update\u003c/b\u003e(_elapsedTime,deltaTime_) | Updates the Simulation | |\n\n### Debug\n| Method | Description | Default |\n|----------|----------|----------|\n| \u003cb\u003e addDebug\u003c/b\u003e(_gui_) | Adds debug panel to the scene | |\n| \u003cb\u003e resetDebug\u003c/b\u003e(_gui_) | Resets the debug panel | |\n\n\n\n    \n\n## Controls\n### General Controls:\n- **View FPS:** Toggles \"Frames Per Second\" display\n- **Pause Simulation:** Pauses Simulation\n\n### Boid Controls:\n- **Show Bounding Box:** Shows/Hides the Bounding box\n- **Entity Count:** The amount of boids currently on screen\n- **Object Avoid Factor:** The force at which boids avoid world objects\n- **Object Visual Range:** The distance at which boids see world objects\n- **Cohesion Factor:** Adjust how strongly boids are attracted to the center of the flock.\n- **Alignment Factor:** Control how much boids try to match the velocity of neighbor boids within their _visual range_\n- **Separation Factor:** The force at which boids avoid neighbor boids within their _protected range_\n- **Matching Factor:** The force at which boids align velociy with neighbor boids within their _visual range_\n- **Turn Factor:** The force at which boids turn around when out of bounds\n- **Min Speed:** Set the minimum speed of boids.\n- **Max Speed:** Set the maximum speed of boids.\n- **Visual Range:** Adjust the range in which boids detect and react to nearby flockmates.\n- **Protected Range:** Define the area in which boids are protected from external disturbances.\n\n### Environment Vision Controls:\n- **Show Rays:** Toggles display of ray targets. This represents the angle that the boid can see\n- **Ray Count:** How many rays the boid casts per environment check\n- **Ray Angle:** The angle at which the boid casts rays\n- **Ray Distance:** The distance at which a collision is counted\n\n\n## Future Goals\n- Move the boid logic onto the gpu, using THREE.js/webGL GPGPU\n- Add support for attraction/repulsion objects\n\n\n\n## Performance \nThis implementation of the boids algorithm runs on the cpu. As such it has a O(N\u003csup\u003e2\u003c/sup\u003e) time complexity. \nFPS does take a hit once you pass 500 entities. Onced moved onto the gpu, we should be able to handle orders of magnitude more\n\n\n## References\n- [Cornell University Lab](https://people.ece.cornell.edu/land/courses/ece4760/labs/s2021/Boids/Boids.html)\n- [Original Paper by C.W.Reynolds](https://www.cs.toronto.edu/~dt/siggraph97-course/cwr87/)\n- [distributing n points on a sphere](https://stackoverflow.com/questions/9600801/evenly-distributing-n-points-on-a-sphere)\n- [Measurement of areas on a sphere using Fibonacci and latitude–longitude lattices](https://arxiv.org/pdf/0912.4540)\n\n\n[npm-img]: https://img.shields.io/npm/v/three-boids\n[npm-url]: https://npmjs.org/package/three-boids\n\u003c!-- [npm-downloads-img]: https://img.shields.io/npm/dt/3d-force-graph\n[npm-downloads-url]: https://www.npmtrends.com/3d-force-graph --\u003e\n\n\n[deepscan]: https://deepscan.io/api/teams/24470/projects/27658/branches/887097/badge/grade.svg\n[deepscan-url]: https://deepscan.io/dashboard#view=project\u0026tid=24470\u0026pid=27658\u0026bid=887097\n\u003c!-- [![DeepScan grade](https://deepscan.io/api/teams/24470/projects/27658/branches/887097/badge/grade.svg)](https://deepscan.io/dashboard#view=project\u0026tid=24470\u0026pid=27658\u0026bid=887097) --\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStr4y-Cat%2Fthree-boids","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FStr4y-Cat%2Fthree-boids","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStr4y-Cat%2Fthree-boids/lists"}