{"id":13716898,"url":"https://github.com/AtlasEngineCa/ParticleEmitter","last_synced_at":"2025-05-07T06:31:45.212Z","repository":{"id":63164306,"uuid":"551735602","full_name":"AtlasEngineCa/ParticleEmitter","owner":"AtlasEngineCa","description":"Library for drawing particle effects in Minecraft java edition using bedrock json files","archived":false,"fork":false,"pushed_at":"2025-05-05T03:18:42.000Z","size":1083,"stargazers_count":59,"open_issues_count":2,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-05T04:26:21.090Z","etag":null,"topics":["minecraft","minecraft-java-edition","minestom-library","snowstorm"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AtlasEngineCa.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,"zenodo":null}},"created_at":"2022-10-15T01:47:10.000Z","updated_at":"2025-05-05T03:18:45.000Z","dependencies_parsed_at":"2024-08-21T23:34:03.946Z","dependency_job_id":"ef7626e9-69bf-4fa7-b89c-2f58b02f39ee","html_url":"https://github.com/AtlasEngineCa/ParticleEmitter","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AtlasEngineCa%2FParticleEmitter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AtlasEngineCa%2FParticleEmitter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AtlasEngineCa%2FParticleEmitter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AtlasEngineCa%2FParticleEmitter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AtlasEngineCa","download_url":"https://codeload.github.com/AtlasEngineCa/ParticleEmitter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252826878,"owners_count":21810197,"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":["minecraft","minecraft-java-edition","minestom-library","snowstorm"],"created_at":"2024-08-03T00:01:15.513Z","updated_at":"2025-05-07T06:31:45.201Z","avatar_url":"https://github.com/AtlasEngineCa.png","language":"Java","readme":"\u003cdiv id=\"top\"\u003e\u003c/div\u003e\n\n\u003c!-- PROJECT SHIELDS --\u003e\n\u003c!--\n*** I'm using markdown \"reference style\" links for readability.\n*** Reference links are enclosed in brackets [ ] instead of parentheses ( ).\n*** See the bottom of this document for the declaration of the reference variables\n*** for contributors-url, forks-url, etc. This is an optional, concise syntax you may use.\n*** https://www.markdownguide.org/basic-syntax/#reference-style-links\n--\u003e\n[![Contributors][contributors-shield]][contributors-url]\n[![Forks][forks-shield]][forks-url]\n[![Stargazers][stars-shield]][stars-url]\n[![Issues][issues-shield]][issues-url]\n[![APACHE-2.0 License][license-shield]][license-url]\n\n\u003c!-- PROJECT LOGO --\u003e\n\u003cbr /\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/WorldSeedGames/ParticleEmitter\"\u003e\n    \u003cimg src=\".github/icon.png\" alt=\"Logo\" width=\"180\" height=\"180\"\u003e\n  \u003c/a\u003e\n\n\u003ch3 align=\"center\"\u003eParticleEmitter\u003c/h3\u003e\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/WorldSeedGames/ParticleEmitter/issues\"\u003eReport Bug\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/WorldSeedGames/ParticleEmitter/issues\"\u003eRequest Feature\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n\u003c!-- ABOUT THE PROJECT --\u003e\n## About The Project\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/WorldSeedGames/ParticleEmitter\"\u003e\n    \u003cimg src=\".github/demo.gif\" alt=\"Logo\" width=\"720\" height=\"404\"\u003e\n  \u003c/a\u003e\n  \u003c/div\u003e\n\nWith this library, you can design particle animations with [snowstorm](https://snowstorm.app/) and draw them in a Minecraft world.\n\nCurrently only [Minestom](https://github.com/Minestom/Minestom) is supported.\n\n\u003c!-- GETTING STARTED --\u003e\n## Getting Started\n\nA full, runnable example server can be found in [here](https://github.com/WorldSeedGames/ParticleEmitter/blob/master/src/test/java/Demo.java)\n\nParticle examples can be found [here](https://github.com/WorldSeedGames/ParticleEmitter/tree/master/src/test/resources/particles)\n\n### Adding as a dependency\n\nAdd the following to your `build.gradle.kts` file:\n\n```\nrepositories {\n    maven(\"https://reposilite.atlasengine.ca/public\")\n}\n```\n\nAdd the library as a dependency\n```\ndependencies {\n    implementation(\"net.worldseed.particleemitter:ParticleEmitter:\u003cversion\u003e\")\n}\n```\n\nThe lastest version number can be found [here](https://reposilite.atlasengine.ca/#/public/net/worldseed/particleemitter/ParticleEmitter)\n\n### JAVA FLAGS\n\nTo execute the code you must add the java VM flag `--add-opens java.base/java.lang=ALL-UNNAMED`.\n\n## Features\n\nParticleEmitter supports the following features\n- Emitter lifetime expression, loop and once\n- Emitter rate instant and steady\n- Emitter shape box, disc, point and sphere\n- Particle tinting (colour)\n\n## Limitations\n\n[Minecraft Query Language](https://github.com/hollow-cube/common/tree/main/modules/mql) (MQL) does not fully support Molang\n- Variables do not work\n- Functions do not work\n\nParticle Restrictions\n- Velocity only works on certain particles and acceleration don't work on any particles\n- Custom particle textures don't work\n- Curves have not been implemented\n- Particle lifetimes have not been implemented\n\n## Usage notes\n\n### Particle amounts\nYou may notice in practice that only one particle gets spawned per `emitter.tick()`. \nIn some cases, this may be a problem as you may want to have more control over the amount of particles spawned for the same animation as demonstrated in the following video where the same animation is being played in 4 different positions with differing particle amounts:\nhttps://github.com/user-attachments/assets/8fd4f277-eb8d-4a3e-b068-18533f72346a\n\nThis can be achieved by using a for loop around the `emitter.tick()` like so:\n```java\nCollection\u003cParticlePacket\u003e packets = new ArrayList\u003c\u003e();\nfor (int i = 0; i \u003c amount; i++) {\n    packets.addAll(emitter.tick());\n}\nif (emitter.status() != EmitterLifetime.LifetimeState.DEAD) {\n    packets.forEach(packet -\u003e {\n        instance.getPlayers().forEach(p -\u003e p.sendPackets(packet));\n    });\n}\n```\nHowever, this method will require each emitter to have a different `updatesPerSecond` parameter equal to `x*amount` for the animations to be synchronised and play at the same time with differing particle counts, otherwise the animation may speed up or slow down.\n```java\nList\u003cParticleEmitter\u003e emitters = new ArrayList\u003c\u003e();\n{\n    var emitter = ParticleParser.parse(Particle.DUST_COLOR_TRANSITION, 1000*amount, map);\n    emitters.add(emitter);\n}\n```\nSample code for how this can be done in practice can be found in the `src/test/java/ParticleManagerDemo.java` file, where the video demonstration above was created with these calls:\n```java\nParticleManager.playParticle(\"rect.particle.json\", new Vec(0, 45, 0), 1, instanceContainer, false);\nParticleManager.playParticle(\"rect.particle.json\", new Vec(3, 45, 0), 2, instanceContainer, false);\nParticleManager.playParticle(\"rect.particle.json\", new Vec(6, 45, 0), 3, instanceContainer, false);\nParticleManager.playParticle(\"rect.particle.json\", new Vec(9, 45, 0), 4, instanceContainer, false);\n```\n\n### Playing a particle animation \"once\" over its lifetime\nIf you want to have an animation play just once over its lifetime, you will need to use a Timer that gets cancelled once the emitter state is \"DEAD\" (meaning the animation completed successfully). Here is how that would be done in practice:\n\n```java\nnew Timer().schedule(new TimerTask() {\n    public void run()  {\n        try {\n            for (var emitter : emitters) {\n                for (int i = 0; i \u003c amount; i++) {\n                    Collection\u003cParticlePacket\u003e packets = emitter.tick();\n                    if (emitter.status() != EmitterLifetime.LifetimeState.DEAD) {\n                        packets.forEach(packet -\u003e {\n                            instance.getPlayers().forEach(p -\u003e p.sendPackets(packet));\n                        });\n                    } else {\n                        emitter.reset();\n                        // Cancel the timer so it doesn't keep looping\n                        this.cancel();\n                    }\n                }\n            }\n        } catch (InvocationTargetException | NoSuchMethodException | InstantiationException |\n                 IllegalAccessException e) {\n            throw new RuntimeException(e);\n        }\n    }\n}, 1, 1);\n```\n\n\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- MARKDOWN LINKS \u0026 IMAGES --\u003e\n\u003c!-- https://www.markdownguide.org/basic-syntax/#reference-style-links --\u003e\n[contributors-shield]: https://img.shields.io/github/contributors/WorldSeedGames/ParticleEmitter.svg?style=for-the-badge\n[contributors-url]: https://github.com/WorldSeedGames/ParticleEmitter/graphs/contributors\n[forks-shield]: https://img.shields.io/github/forks/WorldSeedGames/ParticleEmitter.svg?style=for-the-badge\n[forks-url]: https://github.com/othneildrew/Best-README-Template/network/members\n[stars-shield]: https://img.shields.io/github/stars/WorldSeedGames/ParticleEmitter.svg?style=for-the-badge\n[stars-url]: https://github.com/WorldSeedGames/ParticleEmitter/stargazers\n[issues-shield]: https://img.shields.io/github/issues/WorldSeedGames/ParticleEmitter.svg?style=for-the-badge\n[issues-url]: https://github.com/WorldSeedGames/ParticleEmitter/issues\n[license-shield]: https://img.shields.io/github/license/WorldSeedGames/ParticleEmitter?style=for-the-badge\n[license-url]: https://github.com/WorldSeedGames/ParticleEmitter/blob/master/LICENSE\n","funding_links":[],"categories":["Libraries"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAtlasEngineCa%2FParticleEmitter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAtlasEngineCa%2FParticleEmitter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAtlasEngineCa%2FParticleEmitter/lists"}