{"id":21129898,"url":"https://github.com/markuslerner/particular","last_synced_at":"2025-06-12T19:05:38.759Z","repository":{"id":57700110,"uuid":"479983939","full_name":"markuslerner/Particular","owner":"markuslerner","description":"Particle system written in JavaScript","archived":false,"fork":false,"pushed_at":"2024-08-01T09:47:37.000Z","size":908,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-25T10:42:15.734Z","etag":null,"topics":["boids","gpu-acceleration","javascript","particles","physics","simulation","swarm","system","webgl"],"latest_commit_sha":null,"homepage":"","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/markuslerner.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-04-10T10:29:56.000Z","updated_at":"2025-02-28T09:25:00.000Z","dependencies_parsed_at":"2023-11-29T06:39:04.627Z","dependency_job_id":"699d4585-bafa-4bdd-ae1d-c89198bad8f5","html_url":"https://github.com/markuslerner/Particular","commit_stats":{"total_commits":136,"total_committers":2,"mean_commits":68.0,"dds":0.007352941176470562,"last_synced_commit":"742e6f5059d24789b50318b721e2eeed3b34e546"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/markuslerner/Particular","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markuslerner%2FParticular","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markuslerner%2FParticular/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markuslerner%2FParticular/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markuslerner%2FParticular/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markuslerner","download_url":"https://codeload.github.com/markuslerner/Particular/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markuslerner%2FParticular/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259519775,"owners_count":22870364,"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","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","gpu-acceleration","javascript","particles","physics","simulation","swarm","system","webgl"],"created_at":"2024-11-20T05:30:50.119Z","updated_at":"2025-06-12T19:05:38.700Z","avatar_url":"https://github.com/markuslerner.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Particular\n\n[![NPM Package](https://img.shields.io/npm/v/@markuslerner/particular.svg?style=flat)](https://www.npmjs.com/package/@markuslerner/particular)\n\nParticle system written in JavaScript. Heavily inspired by [Punktiert](https://github.com/djrkohler/punktiert) Java library.\n\nWhy yet another physics/particle system libary? I simply didn't find a JavaScript physics/particle system libary that is GPU-accelerated, behavior-based (eg. flocking/swarm, seek/arrive) and works they way I was used to from earlier days in Java/Processing.\n\nCollaborations and improvements welcome.\n\n### Highlights\n\n- GPU-accelerated (currently only Collision behavior) using gpu.js\n- Simple API\n- Behavior-based\n- Vector3 API fully compatible with [THREE.js](https://github.com/mrdoob/three.js/) [Vector3](https://threejs.org/docs/#api/en/math/Vector3)\n\n### Examples\n\n- [All behaviors](https://dev.markuslerner.com/particular/examples/all-behaviors.html)\n- [Collision Starfield](https://dev.markuslerner.com/particular/examples/collision-starfield.html)\n- [Flocking](https://dev.markuslerner.com/particular/examples/flocking.html)\n- [Seek/Arrive](https://dev.markuslerner.com/particular/examples/seek-arrive.html)\n\n### Usage\n\n```console\nyarn add @markuslerner/particular\n```\n\nor\n\n```console\nnpm install @markuslerner/particular\n```\n\n1. Include classes from this package:\n\n```js\nimport {\n  SimplePhysics,\n  Particle,\n  Collision,\n  Seek,\n} from '@markuslerner/particular';\n```\n\n2. Create physics:\n\n```js\nconst physics = new GPUPhysics();\n```\n\n3. Create particle(s) and add to physics:\n\n```js\nconst particle = new Particle(x, y, z);\nphysics.addParticle(particle);\n```\n\n4. Add behavior(s):\n\n```js\nparticle.addBehavior(new Collision());\nparticle.addBehavior(new Seek());\n```\n\n5. Update physics every frame:\n\n```js\nphysics.update();\n```\n\nDone.\n\nCollaborations and improvements are welcome.\n\n### Editing source code and examples\n\nTo edit the source code and the examples, run:\n\n```console\nyarn start\n```\n\nor\n\n```console\nnpm start\n```\n\nA development server will be launched under http://localhost:8000/\n\nThe files from the src folder will we re-built automatically into a virtual build/particular.js upon reloading the page.\n\n### API Docs\n\n#### SimplePhysics class\n\n**Constructor**\n\n`new SimplePhysics({ friction = 0.95, springIterationsCount = 50 } = {});`\n\n**Members:**\n\n| Member                  | Type   |  Default  |  Description                              |\n| :---------------------- | :----- | :-------- | :---------------------------------------- |\n| `behaviors`             | Set    | new Set() | Behaviors for all particles               |\n| `constraints`           | Set    | new Set() |  Constraints for all particles            |\n| `groups`                | Set    | new Set() | Groups of particles (not implemented yet) |\n| `particles`             | Set    | new Set() | All particles                             |\n| `springs`               | Set    | new Set() | All springs (not implemented yet)         |\n| `friction`              | number | 0.95;     |\n| `springIterationsCount` | number | 50;       |\n\n**Public Methods:**\n\n| Method                                 | Return value | Description                                                          |\n| :------------------------------------- | :----------- | :------------------------------------------------------------------- |\n| `addBehavior(behavior: Object)`        |              | Add behavior to all particles                                        |\n| `addParticle(particle: Particle)`      |              | Add particle                                                         |\n| `addSpring(spring: Spring)`            |              | Not implmemented yet                                                 |\n| `addGroup(group: Group)`               |              | Not implmemented yet                                                 |\n| `clear()`                              |              | Clear particles, groups and springs                                  |\n| `getSpring(a: Particle, b: Particle)`  | Spring       | Attempts to find the spring element between the 2 particles supplied |\n| `getnumConnected(spring: Spring)`      | number       | Get the count of how many springs are connected to A                 |\n| `hasBehavior(behavior: Behavior)`      | Behavior     | Check, if physics has this behavior                                  |\n| `hasGroup(group: Group)`               | Group        | Check, if physics has this group                                     |\n| `hasParticle(particle: Particle)`      | Particle     | Check, if physics has this particle                                  |\n| `hasSpring(spring: Spring)`            | Spring       | Check, if physics has this spring                                    |\n| `removeBehavior(behavior: Behavior)`   | boolean      | Remove behavior                                                      |\n| `removeParticle(particle: Particle)`   | boolean      | Remove particle                                                      |\n| `removeSpring(spring: Spring)`         | boolean      | Remove spring                                                        |\n| `removeSpringElements(spring: Spring)` | boolean      | Removes a spring connector and its both end point particles          |\n| `removeGroup(group: Group)`            | boolean      | Remove group                                                         |\n| `update(deltaTime: number = 1)`        |              |  Update simulation                                                   |\n\n#### Particle class\n\nExtends Vector3 class\n\nVector3 API is fully compatible with [THREE.js](https://github.com/mrdoob/three.js/) Vector3.\n\n**Constructor**\n\n`new Particle(x: number = 0.0, y: number = 0.0, z: number = 0.0, mass: number = 1.0, radius: number = 1.0);`\n\n**Members:**\n\n| Member           | Type     |  Default       |  Description                                      |\n| :--------------- | :------- | :------------- | :------------------------------------------------ |\n| `x`              | number   | 0.0            |\n| `y`              | number   | 0.0            |\n| `z`              | number   | 0.0            |\n| `locked`         | boolean  | false          | Particle lock status                              |\n| `behaviors`      | Set      | null           | Particle behaviors                                |\n| `neighbors`      | Set      | null           | Particle neighbors                                |\n| `mass`           |  number  |  1.0           |\n| `radius`         |  number  |  1.0           |\n| `friction`       |  number  |  0.0           |\n| `maxSpeed`       |  number  |  3.0           |\n| `force`          |  Vector3 |  new Vector3() |\n| `velocity`       | Vector3  | new Vector3()  |\n| `velocitySmooth` | Vector3  | new Vector3()  |\n| `followers`      | Set      | new Set()      | Follower which will copy this particle’s position |\n\n**Public Methods:**\n\n| Method                                                            | Return value         | Description                                           |\n| :---------------------------------------------------------------- | :------------------- | :---------------------------------------------------- |\n| `addBehavior(behavior: Object, addEvenIfExists: boolean = false)` | this                 | Add behavior to this particle only                    |\n| `getBehavior(behaviorClass: Class)`                               | Instance of Behavior | Get behavior by behavior class                        |\n| `addFollower(vector: Vector3)`                                    |                      | Will copy this particle’s position                    |\n| `addForce(force: Vector3)`                                        | this                 | Add force to this particle, used by behaviors         |\n| `clearForce()`                                                    | this                 | Clear force                                           |\n| `clearVelocity()`                                                 | this                 | Clear velocity                                        |\n| `getVelocity()`                                                   | Vector3              | Get velocity                                          |\n| `lock()`                                                          | this                 | Lock this particle’s position                         |\n| `removeBehavior(behavior: Object)`                                | boolean              |  Remove behavior, returns true, if behavior was found |\n| `removeFollower(follower: Object)`                                | boolean              |  Remove follower, returns true, if follower was found |\n| `unlock()`                                                        | this                 | Unlock this particle’s position                       |\n| `constrainX(min: number, max: number)`                            |                      | Constrain x                                           |\n| `constrainY(min: number, max: number)`                            |                      | Constrain y                                           |\n| `constrainZ(min: number, max: number)`                            |                      | Constrain z                                           |\n\n### Available Behaviors:\n\n- Align: align movement with neighbors\n- Avoid: avoid single target\n- Bounce: bounce off world box\n- Cohesion: keep close to neighbors\n- Collision: avoid collision with neighbors\n- Constrain: keep within world box\n- Seek: seek single target\n- SeekRandom: seek single random target\n- Separate: separate from neighbors\n- Wander: random wander movment\n- Wrap: wrap around word box\n\n### Editing source\n\nIn order to edit the source code, run:\n\n```console\nyarn start\n```\n\nAnd open http://127.0.0.1:8000/ in your browers.\n\nThe files in the `build` folder will automatically be rebuilt when modified.\n\n### To Do\n\n- Add gpu acceleration for Align, Cohesion and Separate behaviors as well\n- Create 3D flocking example\n- Add missing behaviors and params to all behaviors example\n- Consider writing behaviors as a plugin for matter.js\n- Create other shapes (box, polygon)\n\n### License\n\nMIT licensed\n\nCreated by [Markus Lerner](http://www.markuslerner.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkuslerner%2Fparticular","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkuslerner%2Fparticular","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkuslerner%2Fparticular/lists"}