{"id":13402416,"url":"https://github.com/supermedium/aframe-particleplayer-component","last_synced_at":"2025-05-12T03:31:54.413Z","repository":{"id":33027584,"uuid":"145697802","full_name":"supermedium/aframe-particleplayer-component","owner":"supermedium","description":" :sparkles: Play pre-simulated particle systems in A-Frame :boom:","archived":false,"fork":false,"pushed_at":"2024-01-22T19:47:50.000Z","size":31155,"stargazers_count":72,"open_issues_count":10,"forks_count":29,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-22T14:18:12.533Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://supermedium.github.io/aframe-particleplayer-component","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/supermedium.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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-22T11:10:08.000Z","updated_at":"2025-01-07T11:30:40.000Z","dependencies_parsed_at":"2024-06-19T16:59:05.244Z","dependency_job_id":null,"html_url":"https://github.com/supermedium/aframe-particleplayer-component","commit_stats":{"total_commits":63,"total_committers":3,"mean_commits":21.0,"dds":0.5873015873015873,"last_synced_commit":"f7ebaa303bd362040540b4b5c067672901a067f3"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supermedium%2Faframe-particleplayer-component","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supermedium%2Faframe-particleplayer-component/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supermedium%2Faframe-particleplayer-component/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supermedium%2Faframe-particleplayer-component/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/supermedium","download_url":"https://codeload.github.com/supermedium/aframe-particleplayer-component/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253668068,"owners_count":21944972,"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":[],"created_at":"2024-07-30T19:01:15.745Z","updated_at":"2025-05-12T03:31:49.401Z","avatar_url":"https://github.com/supermedium.png","language":"JavaScript","readme":"## aframe-particleplayer-component\n\n[![Version](http://img.shields.io/npm/v/aframe-particleplayer-component.svg?style=flat-square)](https://npmjs.org/package/aframe-particleplayer-component)\n[![License](http://img.shields.io/npm/l/aframe-particleplayer-component.svg?style=flat-square)](https://npmjs.org/package/aframe-particleplayer-component)\n\nThis component allows replaying particle systems with baked behaviour. This is,\ninstead of calculating the position of all particles on each frame using maths,\nthat value is taken from a cache file (JSON format) with the movement of all\nthe particles already calculated.\n\n![magic gif](examples/magic/magic.gif)\n\n**In short:**\n\n1. Install [the particleplayer Blender add-on](https://github.com/supermedium/aframe-particleplayer-component/tree/master/exporters/blender#blender-exporter-add-on).\n2. Design your particle system in Blender, and export a JSON.\n3. Use this component to load the JSON and reproduce same particle system.\n\n![cover gif](header.gif)\n\nFeatures:\n\n* Baked particle system loading\n* Animation speed / duration\n* Frame interpolation (no frame jumps when replaying at slow speeds)\n* Replay only a percentage of particles (randomly picking on each loop)\n* Delay and loop\n* Overall simulation and particle scaling\n* Particles texture, color, shader and blending\n\nReal-time particle systems behaviour (using already made solutions or your own)\nis often good enough but sometimes specific 3D packages (Blender, Maya,\nHoudini, Cinema4D or many others, for example) can give you much more control\nand direction, with lots of parameters, forces and influencers. This is what is\nthis component for, and has some pros and cons that you should be aware of:\n\n#### Pros:\n\n* **Easier, more complex and richer particle system behaviours**. Use all the\nfeatures and power of your 3d package. You can do whatever you want: add\nmultiple sources with arbitrary shapes, use fluid solvers, add multiple\nforces, influencers and collisions... On the cache file only the final\nposition (and rotation) of the particles is exported, so it does not matter\nhow you design them.\n\n* **More performant for complex simulations** Since all the hard work has\nalready been done by the 3D package, when in real-time the component just has\nto replay the animation, not calculate anything. Each particle system takes one\ndraw call (one merged buffer geometry).\n\n#### Cons:\n\n* **Static behaviour**. Since behaviour is already baked in the cache file,\nparticles move always the same. This can be overcome using `count` parameter\nso only a random percentage of the particles are used on each replaying,\nadding a lot of variation effectively.\n\n* **Big cache JSON files**. If you don't take care, cache files can be quite\nbig for big simulations (both in number of particles and duration),\nincreasing downloading times. Here is a table with some example numbers:\n\n|                | 10 frames   | 100 frames  | 500 frames  |\n|----------------|-------------|-------------|-------------|\n| 10 particles   | 1.7K / 2.3K | 19K/ 25K    |  100K/ 130K |\n| 100 particles  | 17K / 22K   | 177K / 236K | 0.9M / 1.3M |\n| 1000 particles | 160K / 222K | 1.8M / 2.3M | 9.5M / 13M  |\n| 10000 particles| 1.6M / 2.2M | 18M / 23M   | 95M / 121M  |\n\n\\* Values using default `precision` = 1000, without / with rotation exported\n\n\\** These are raw sizes, without server compression, which in the case of JSON\nis very significant.\n\nFile size can be drastically reduced by:\n\n+ Exporting less particles and shorter animation :D\n+ Only exporting position, not rotation of particles\n+ Use `step` parameter to export every x frames instead of all frames. Using\nthe `interpolation` parameter of the component can do marvels here, and the\ndifference can be unnoticeable:\n\n![step comparison](examples/step.gif)\n\nSo, as a general rule, you should **use this component for small and short\nsimulations**. Ideal for visual effects like sparks, magic spells, small\ntrails, visual accents, and such.\n\nFor [A-Frame](https://aframe.io).\n\n### API\n\n| Property    | Description                                                                                                                                             | Default Value         |\n| --------    | -----------                                                                                                                                             | -------------         |\n| blending    | Particle's material blending mode. Possible values: 'normal', 'additive', 'multiply' or 'substractive'                                                  | 'additive'            |\n| color       | Particle's material color                                                                                                                               | '#fff'                |\n| count       | Number of particles to draw. If less than total available, they are picked randomly. You can set a specific number or a percentage (using % symbol)     | '100%'                |\n| delay       | Milliseconds of wait until replaying the animation                                                                                                      | 0                     |\n| dur         | Duration (in ms) of the animation                                                                                                                       | 1000                  |\n| img         | Texture to use in particles. None by default (flat plane)                                                                                               |                       |\n| interpolate | Interpolate particle positions among frames on slow replayings (big enough `dur` parameter)                                                             | false                 |\n| loop        | Whether loop the animation (true) or not (false). Alternatively, you can use a number here for a specific number of loops                               | 'false'               |\n| on          | Event that starts the animation                                                                                                                         | 'init' (on app start) |\n| poolSize    | Number of possible simultaneous systems to play at once                                                                                                 | 5                     |\n| protation   | Particle rotation offset. To fine tune their initial rotation                                                                                           | 0 0 0                 |\n| pscale      | Particles scale. By default particles are about 0.1 width (final size depends on texture ratio). You can increase their size changing this scale factor | 1.0                   |\n| scale       | Scale of the overall system. Each particle position is multiplied by this factor                                                                        | 1.0                   |\n| shader      | Particle's material shader. Can be 'flat', 'lambert', 'phong' or 'standard'                                                                             | 'flat'                |\n| src         | File cache JSON resource                                                                                                                                |                       |\n\nEvents emitted:\n\n| event    | Description                                   |\n| -------- | -----------                                   |\n| loop     | last frame reached, will start another loop   |\n| finished | all loops and frames finished, animation ends |\n\n\n### Cache file format\n\nYou can generate a cache file using the [available\nexporters](https://github.com/feiss/aframe-particleplayer-component/tree/master/exporters)\n(only Blender for the moment, you are welcome to add support to other 3D\nPackages).\n\nYou shouldn't care about this section unless you want to implement a new\nexporter. Cache file format is a plain JSON file with these main fields:\n\n**V.1.0**\n\n```\n{\n\tversion: '1.0',\n\tprecision: 1000,\n\trotation: true,\n\tsprite_rotation: [0, 0, 0],\n\tframes: [\u003cframes\u003e]\n}\n```\n\nwhere \u0026lt;frames\u0026gt; is the array of frames of the animation, and each one is\nanother array with the position (and optionally rotation) of all particles, in\narray format:\n\n```\n\tframes: [\n\t\t[particle1_data, particle2_data, ... particleN_data], // frame 0\n\t\t[particle1_data, particle2_data, ... particleN_data], // frame 1\n\t\t...\n\t\t[particle1_data, particle2_data, ... particleN_data] // last frame\n\t]\n\n\t// and each particleX_data has the format:\n\n\t[pos.x, pos.y, pos.z, rot.x, rot.y, rot.z]\n```\n\nTo optimize the final file size, all position and rotation values are\nmultiplied by `precision` value and then trunc() when exported (eg.\n'0.233523523'.length \u003e '233'.length).\n\n### Installation\n\n#### Browser\n\nInstall and use by directly including the [browser files](dist):\n\n```html\n\u003chead\u003e\n  \u003cscript src=\"https://aframe.io/releases/0.8.2/aframe.min.js\"\u003e\u003c/script\u003e\n  \u003cscript src=\"https://unpkg.com/aframe-particleplayer-component/dist/aframe-particleplayer-component.min.js\"\u003e\u003c/script\u003e\n\u003c/head\u003e\n\n\u003cbody\u003e\n  \u003ca-scene\u003e\n  \t\u003ca-assets\u003e\n  \t\t\u003ca-asset-item src=\"particles.json\" id=\"particlesJSON\"\u003e\u003c/a-asset-item\u003e\n  \t\u003c/a-assets\u003e\n    \u003ca-entity particleplayer=\"src: #particlesJSON\"\u003e\u003c/a-entity\u003e\n  \u003c/a-scene\u003e\n\u003c/body\u003e\n```\n\n#### npm\n\nInstall via npm:\n\n```bash\nnpm install aframe-particleplayer-component\n```\n\nThen require and use.\n\n```js\nrequire('aframe');\nrequire('aframe-particleplayer-component');\n```\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupermedium%2Faframe-particleplayer-component","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsupermedium%2Faframe-particleplayer-component","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupermedium%2Faframe-particleplayer-component/lists"}