add migration guide

blog/2024-10-03-pixi-v8-particle-container.md

@@ -16,7 +16,7 @@ PixiJS v8 has taken speed to the next level with the release of its new `Particl
 
 <!--truncate-->
 
-## New ParticleContainer Design
+## 🚀 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. 
 
@@ -31,6 +31,8 @@ Yes, that’s a _million_ bunnies on-screen, and honestly the main bottleneck at
 
 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:
@@ -89,7 +91,7 @@ This is ideal for projects where frame rate and rendering volume matter—such a
 
 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
+## 🎉 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!
 

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,69 @@ import { AdjustmentFilter } from '@pixi/filter-adjustment';
 import { AdjustmentFilter } from 'pixi-filters/adjustment';
 ```
 
+Here’s the grammar-corrected version of your text:
+
+---
+
+### 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`.
+
+---
+
+This version corrects the grammar and improves clarity while maintaining the original meaning.
+
+**OLD**
+```
+const container = new ParticleContainer();
+
+for (let i = 0; i < 100000; i++) {
+    const particle = new Sprite(texture);
+    container.addChild(particle);
+}
+```
+
+**NEW**
+```
+const container = new ParticleContainer();
+
+for (let i = 0; i < 100000; i++) {
+    const particle = new Particle(texture);
+    container.addParticle(particle);
+}
+```
+with a bounds area
+```
+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 +742,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.