first draft pixi particle post! (#124)

* Create 2024-10-03-pixi-v8-particle-container.md * Update blog/2024-10-03-pixi-v8-particle-container.md Co-authored-by: Matt Karl <[email protected]> * Update blog/2024-10-03-pixi-v8-particle-container.md Co-authored-by: Matt Karl <[email protected]> * Update blog/2024-10-03-pixi-v8-particle-container.md Co-authored-by: Matt Karl <[email protected]> * Update blog/2024-10-03-pixi-v8-particle-container.md Co-authored-by: Matt Karl <[email protected]> * Update blog/2024-10-03-pixi-v8-particle-container.md Co-authored-by: Matt Karl <[email protected]> * Update blog/2024-10-03-pixi-v8-particle-container.md Co-authored-by: Matt Karl <[email protected]> * Update blog/2024-10-03-pixi-v8-particle-container.md Co-authored-by: Matt Karl <[email protected]> * add migration guide * Update docs/guides/migrations/v8.md Co-authored-by: Matt Karl <[email protected]> * Update docs/guides/migrations/v8.md Co-authored-by: Matt Karl <[email protected]> * Update docs/guides/migrations/v8.md Co-authored-by: Matt Karl <[email protected]> * Update docs/guides/migrations/v8.md Co-authored-by: Matt Karl <[email protected]> * Update docs/guides/migrations/v8.md Co-authored-by: Matt Karl <[email protected]> --------- Co-authored-by: Matt Karl <[email protected]>
pixijs · Oct 7, 2024 · 6950453 · 6950453
1 parent ae1d98b
commit 6950453
Show file tree

Hide file tree

Showing 2 changed files with 163 additions and 8 deletions.
diff --git a/blog/2024-10-03-pixi-v8-particle-container.md b/blog/2024-10-03-pixi-v8-particle-container.md
@@ -0,0 +1,103 @@
+---
+title: ParticleContainer - The New Speed Demon in PixiJS v8  
+description: Introducing the new ParticleContainer in PixiJS v8—faster than ever, optimized for rendering millions of particles effortlessly.  
+slug: particlecontainer-v8  
+authors:  
+  - name: Mat Groves  
+    title: PixiJS 
+    url: https://github.com/GoodboyDigital  
+    image_url: https://github.com/GoodboyDigital.png  
+tags: [PixiJS, ParticleContainer, WebGL, Games, Performance, Optimization]  
+hide_table_of_contents: true  
+keywords: ['PixiJS', 'ParticleContainer', 'game development', 'web graphics', 'optimization', 'WebGL']  
+---
+
+PixiJS v8 has taken speed to the next level with the release of its new `ParticleContainer`. This new feature brings a jaw-dropping performance boost, capable of rendering 100K+ without breaking a sweat. If you’ve got tons of elements to throw on the screen, you’re in for a treat!
+
+<!--truncate-->
+
+## 🚀 New ParticleContainer Design
+
+The key difference in PixiJS v8 is that the `ParticleContainer` doesn’t deal with sprites any more, it works with lightweight **particles**. While particles share many properties with sprites (like texture, position, anchor, scale, rotation, alpha and color), they cut out unnecessary overhead. The result is **speed**, pure and simple. 
+
+How fast, you ask? Well, take a look on my machine (Macbook Pro M3):
+
+- **Sprites + Container**: 200,000 at 60fps.
+- **Particles + ParticleContainer**: 1,000,000 at 60fps!
+
+Yes, that’s a _million_ bunnies on-screen, and honestly the main bottleneck at that point wasn’t even rendering but the logic behind the bouncing movement! Give this a spin and see for yourself:
+
+<iframe src="https://goodboydigital.github.io/pixi-bunnymark/dist/?asParticles=true&count=1000&renderer=webgl" width="700" height="500" frameborder="0"></iframe>
+
+The key takeaway is that you can now render **huge volumes of elements** absurdly fast, making PixiJS v8 a perfect choice for high-performance games or visually intensive projects. And yes this is faster than the v7 particle container by **over 3x**!
+
+Please checkout the [migration guide](../8.x/guides/migrations/v8#particlecontainer) for more information on how to migrate your code to the new particle container.
+
+### Speed Secret: Static vs. Dynamic Properties
+
+To get the most out of this performance beast, it’s essential to understand **static** vs. **dynamic** properties. PixiJS gives you full control over which properties update every frame (dynamic) and which don’t need constant updates (static). Here’s how they work:
+
+- **Static properties**: Once set, they stay the same unless explicitly changed. By keeping them static, you reduce computational load, meaning faster rendering. This is your responsibility to update :)
+- **Dynamic properties**: These are recalculated and uploaded to the GPU every frame regardless.
+
+By default, **only the position** is dynamic, but you can configure others if needed. The fewer dynamic properties you have, the faster the rendering will be!
+
+### PixiJS v8 Particle Container Usage
+
+Let’s walk through a simple example of how to get started:
+
+```javascript
+import { ParticleContainer, Particle, Texture } from 'pixi.js';
+
+// Create a particle container with default options
+const container = new ParticleContainer({
+    // this is the default, but we show it here for clarity
+    dynamicProperties: {
+        position: true,  // Allow dynamic position changes (default)
+        scale: false,    // Static scale for extra performance
+        rotation: false, // Static rotation
+        color: false     // Static color
+    }
+});
+
+// Add particles
+const texture = Texture.from('path/to/bunny.png');
+
+for (let i = 0; i < 100000; ++i) {
+    let particle = new Particle({
+        texture,
+        x: Math.random() * 800,
+        y: Math.random() * 600,
+    });
+
+    container.addParticle(particle);
+}
+
+// Add container to the Pixi stage
+app.stage.addChild(container);
+```
+
+In this example, we create a `ParticleContainer`, set properties to static where possible, and generate a million particles. By using a shared texture (hello, sprite sheets!), we ensure that all particles share the same graphical assets, making rendering even more efficient.
+
+### Reasons to Use ParticleContainer
+
+The `ParticleContainer` shines when you need **insane numbers** of visual elements on-screen, especially when you want them moving and interacting in real time. Whether you're building particle effects, swarms of characters, or abstract art installations, PixiJS v8 has you covered. The static vs. dynamic property system gives you granular control over performance, allowing you to fine-tune the balance between flexibility and speed.
+
+This is basically the fastest we could make it by still keeping allowing for different textures (via sprite sheets) and still empowering devs to manipulate the particles via JS and not having to move the movement to the GPU (which might be faster, but is more complex and less flexible). So even though we are choosing to call them particles, they are more like something in between a traditional particle and a classic sprite.
+
+This is ideal for projects where frame rate and rendering volume matter—such as games, interactive apps, and high-volume data visualization. By controlling the dynamic properties of your particles, you can optimize your application’s performance to fit your needs.
+
+### Next Steps
+
+The new `ParticleContainer` is a game-changer, but there are still some areas for improvement! For one, there is room to optimise further the static uploading of properties (you may notice the example above is slower when adding bunnys - but then speeds up once stable). We plan to expose how the particles are batched so that developers can add / remove attributes from the batch to make it even faster or add more flexibility and customization. But for now, this is a great starting point and we hope you enjoy the new `ParticleContainer`!
+
+## 🎉 Conclusion
+
+PixiJS v8’s `ParticleContainer` is a game-changer when it comes to rendering at scale. Its ability to push **millions** of particles at full speed opens up a world of possibilities for game developers, animators, and creative coders. Get in, experiment with the new API, and see just how fast your visuals can fly!
+
+Ready to give it a spin? Try out the new `ParticleContainer` in PixiJS v8, and push the limits of performance in your projects!
+
+
+## 🌐 Stay Connected
+
+Follow [Doormat23](https://twitter.com/Doormat23) and [PixiJS](https://twitter.com/PixiJS) on social media for the latest updates. Join our vibrant community on [Discord](https://discord.gg/nrnDP9wtyX) for real-time discussions and support.
diff --git a/docs/guides/migrations/v8.md b/docs/guides/migrations/v8.md
@@ -19,12 +19,7 @@ Before diving into the migration process, let's review the breaking changes intr
 
 ### Should I Upgrade?
 
-Generally, the answer is yes! But currently, there may be reasons that suggest it's best not to upgrade just yet. Ask yourself the following questions:
-
-- **Do I *need* the ParticleContainer?** We have removed this from v8 because, in most cases, a regular container is faster. However, this is not the case when the number of particles begins to exceed the 10,000s range. We do plan on creating a new particle container optimized for this high level of elements. Ideally, we would like to make it even faster and also less memory intensive. Creating 100,000 sprites consumes a lot of memory, and instead, creating a much lighter particle container + particle class would help here. If you need tens of thousands of particles right now and performance is key, then it's best to continue leveraging v7 until we release the new Particle Container.
-
-- **Do you make use of custom batch renderers?**
-The logic for batch rendering has been extensively reworked for speed! Custom batching can be achieved by creating your own batcher, but the ability to build one and slot it into the existing batching architecture has not been directly exposed just yet. If you are making extensive use of custom batchers, there is no high level analogous alternative in v8 just yet. You would need to go a layer deeper. Exposing the ability for custom batching is on our roadmap, and we hope that our new approach will be even easier to use. Watch this space for that update.
+Generally, the answer is yes! But currently, there may be reasons that suggest it's best not to upgrade just yet. Ask yourself the following question:
 
 - **Does your project leverage existing Pixi libraries that have not yet been migrated to v8?**
 We are working hard to migrate our key libraries to v8 but did not want this to be a blocker for those who are using pure Pixi. This means some libraries will not have a v8 counterpart just yet. It's best to hold off on migration if this is the case for you.
@@ -428,6 +423,65 @@ import { AdjustmentFilter } from '@pixi/filter-adjustment';
 import { AdjustmentFilter } from 'pixi-filters/adjustment';
 ```
 
+---
+
+### ParticleContainer
+
+`ParticleContainer` has been reworked in v8 to allow for far more particles than before. There are a few key changes you should be aware of:
+
+A `ParticleContainer` no longer accepts sprites as its children. Instead, it requires a `Particle` class (or an object that implements the `IParticle` interface), which follows this interface:
+
+```
+export interface IParticle
+{
+    x: number;
+    y: number;
+    scaleX: number;
+    scaleY: number;
+    anchorX: number;
+    anchorY: number;
+    rotation: number;
+    color: number;
+    texture: Texture;
+}
+```
+
+The reason for this change is that sprites come with many extra properties and events that are generally unnecessary when dealing with large numbers of particles. This approach explicitly removes any ambiguity we had in v7, such as "Why doesn't my sprite work with filters?" or "Why can't I nest children in my sprites?" It’s a bit more predictable. Additionally, due to the lightweight nature of particles, this means we can render far more of them! 
+
+So, no functionality is lost—just an API tweak with a massive performance boost!
+
+Particles are also not stored in the `children` array of the `ParticleContainer`, as particles are not technically part of the scene graph (for performance reasons). Instead, they are stored in a flat list called `particleChildren`, which is part of the `ParticleContainer` class. You can modify this array directly for extra speed, or you can use the `addParticle` and `removeParticle` methods to manage your particles.
+
+Another optimization is that `ParticleContainer` does not calculate its own bounds, as doing so would negate the performance gains we've created! Instead, it's up to you to provide a `boundsArea` when initializing the `ParticleContainer`.
+
+---
+
+**OLD**
+```ts
+const container = new ParticleContainer();
+
+for (let i = 0; i < 100000; i++) {
+    const particle = new Sprite(texture);
+    container.addChild(particle);
+}
+```
+
+**NEW**
+```ts
+const container = new ParticleContainer();
+
+for (let i = 0; i < 100000; i++) {
+    const particle = new Particle(texture);
+    container.addParticle(particle);
+}
+```
+with a bounds area
+```ts
+const container = new ParticleContainer({
+  boundsArea:new Rectangle(0,0,500,500)
+});
+```
+
 ### Other Breaking Changes
 
 - `DisplayObject` has been removed. `Container` is now the base class for all PixiJS objects.
@@ -684,8 +738,6 @@ The act of adding and removing the event when a sprite's texture was changed led
   const bounds = container.getBounds().rectangle;
   ```
 
-- `ParticleContainer` has been removed, you should use normal a regular `Container` instead. The performance improvements that `ParticleContainer` provided are no longer necessary due to the new rendering architecture.
-
 ## 3. Deprecated Features
 
 Certain features from PixiJS v7 have been deprecated in v8. While they will still work, it's recommended to update your code to use the new alternatives. Refer to the deprecated features section for details on what to replace them with.