@docyrus/animaguru 0.6.0

package/vendor/pixijs-skills/skills/pixijs-scene-mesh/references/mesh-simple.md

@@ -0,0 +1,144 @@
+# MeshSimple
+
+A thin `Mesh` subclass that handles geometry construction for you. Pass `vertices`, optional `uvs`, and optional `indices`, and it builds the `MeshGeometry` internally and auto-updates the vertex buffer each frame. Use `MeshSimple` for quick textured quads, triangles, or any shape where you plan to animate vertex positions.
+
+## Quick Start
+
+```ts
+const texture = await Assets.load("sprite.png");
+
+const triangle = new MeshSimple({
+  texture,
+  vertices: new Float32Array([0, 0, 100, 0, 50, 100]),
+  uvs: new Float32Array([0, 0, 1, 0, 0.5, 1]),
+  topology: "triangle-list",
+});
+
+app.stage.addChild(triangle);
+```
+
+`MeshSimple` wraps `MeshGeometry` creation, exposes `vertices` directly, and auto-updates the position buffer each frame via `onRender`.
+
+## Constructor options
+
+`new MeshSimple(options: SimpleMeshOptions)`
+
+| Option     | Type           | Default           | Description                                                                                                           |
+| ---------- | -------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `texture`  | `Texture`      | —                 | Texture sampled by the mesh. Required.                                                                                |
+| `vertices` | `Float32Array` | `undefined`       | Flat `x, y` pairs for each vertex. Passed through to `MeshGeometry` as `positions`.                                   |
+| `uvs`      | `Float32Array` | `undefined`       | Flat `u, v` pairs matching `vertices`. Without UVs the geometry fills zeros and the mesh samples only pixel `(0, 0)`. |
+| `indices`  | `Uint32Array`  | `undefined`       | Triangle indices into `vertices`. Omit for unindexed rendering in vertex order.                                       |
+| `topology` | `Topology`     | `'triangle-list'` | `'triangle-list' \| 'triangle-strip' \| 'line-list' \| 'line-strip' \| 'point-list'`.                                 |
+
+`MeshSimple` builds its own `MeshGeometry`, so `geometry` is omitted from the options type. Note the option is named `vertices` here (converted to `positions` internally), matching the `mesh.vertices` getter. Other `MeshOptions` fields (`shader`, `state`, `roundPixels`) are inherited from `mesh.md` and behave identically.
+
+All `Container` options (`position`, `scale`, `tint`, `label`, `filters`, `zIndex`, etc.) are also valid here — see `skills/pixijs-scene-core-concepts/references/constructor-options.md`.
+
+`autoUpdate` is a runtime property (defaults to `true`), not a constructor option. Set `mesh.autoUpdate = false` after construction to suppress the per-frame position-buffer upload.
+
+## Core Patterns
+
+### Animated vertices
+
+```ts
+app.ticker.add(() => {
+  const verts = triangle.vertices;
+  verts[5] = 100 + Math.sin(performance.now() / 500) * 20;
+  triangle.vertices = verts;
+});
+```
+
+Because `autoUpdate` defaults to `true`, assigning to `vertices` or mutating the array in place is enough; the buffer is pushed to the GPU automatically during the next render pass.
+
+### Indexed quad
+
+```ts
+const quad = new MeshSimple({
+  texture,
+  vertices: new Float32Array([0, 0, 100, 0, 100, 100, 0, 100]),
+  uvs: new Float32Array([0, 0, 1, 0, 1, 1, 0, 1]),
+  indices: new Uint32Array([0, 1, 2, 0, 2, 3]),
+});
+```
+
+Indices are optional; omit them and the mesh uses unindexed vertex order. Useful for a small, simple shape where explicit indexing adds no value.
+
+### Manual update mode
+
+```ts
+triangle.autoUpdate = false;
+
+app.ticker.add(() => {
+  const verts = triangle.vertices;
+  verts[1] = Math.sin(performance.now() / 1000) * 20;
+  triangle.vertices = verts;
+  triangle.geometry.getBuffer("aPosition").update();
+});
+```
+
+Set `autoUpdate = false` when you want explicit control over when the GPU sees new vertex data; for example, when you only update once per several frames, or when you want to batch multiple vertex mutations before a single upload.
+
+### Alternative topologies
+
+```ts
+const lineStrip = new MeshSimple({
+  texture,
+  vertices: new Float32Array([0, 0, 50, 50, 100, 0, 150, 50]),
+  topology: "line-strip",
+});
+```
+
+`MeshSimple` accepts any topology supported by `MeshGeometry` (`'triangle-list'`, `'triangle-strip'`, `'line-list'`, `'line-strip'`, `'point-list'`). The default is `'triangle-list'`.
+
+## Common Mistakes
+
+### [HIGH] Using the old `SimpleMesh` name
+
+Wrong:
+
+```ts
+import { SimpleMesh } from "pixi.js";
+const mesh = new SimpleMesh(texture, vertices, uvs, indices);
+```
+
+Correct:
+
+```ts
+import { MeshSimple } from "pixi.js";
+const mesh = new MeshSimple({ texture, vertices, uvs, indices });
+```
+
+`SimpleMesh` was renamed to `MeshSimple` in v8. The old name is not exported; the class also switched to an options-object constructor.
+
+
+### [MEDIUM] Forgetting UVs on a textured mesh
+
+Wrong:
+
+```ts
+const mesh = new MeshSimple({
+  texture,
+  vertices: new Float32Array([0, 0, 100, 0, 50, 100]),
+});
+```
+
+Correct:
+
+```ts
+const mesh = new MeshSimple({
+  texture,
+  vertices: new Float32Array([0, 0, 100, 0, 50, 100]),
+  uvs: new Float32Array([0, 0, 1, 0, 0.5, 1]),
+});
+```
+
+Omitting `uvs` makes the underlying `MeshGeometry` fill a zero array, sampling only pixel `(0, 0)` of the texture. Always provide UVs when you want the texture to map across the geometry.
+
+
+## API Reference
+
+- [MeshSimple](https://pixijs.download/release/docs/scene.MeshSimple.html.md)
+- [SimpleMeshOptions](https://pixijs.download/release/docs/scene.SimpleMeshOptions.html.md)
+- [Mesh](https://pixijs.download/release/docs/scene.Mesh.html.md)
+- [MeshGeometry](https://pixijs.download/release/docs/scene.MeshGeometry.html.md)

package/vendor/pixijs-skills/skills/pixijs-scene-mesh/references/mesh.md

@@ -0,0 +1,213 @@
+# Mesh
+
+The base mesh class. Combines a `Geometry` (vertex positions, UVs, indices, topology) with a `Texture` or custom `Shader` to render arbitrary 2D (or perspective-projected) graphics. Use `Mesh` when you need vertex-level control, custom shaders, or batched draw calls for geometry that doesn't fit the Sprite / Graphics / Particle model.
+
+## Quick Start
+
+```ts
+const texture = await Assets.load("pattern.png");
+
+const geometry = new MeshGeometry({
+  positions: new Float32Array([0, 0, 100, 0, 100, 100, 0, 100]),
+  uvs: new Float32Array([0, 0, 1, 0, 1, 1, 0, 1]),
+  indices: new Uint32Array([0, 1, 2, 0, 2, 3]),
+  topology: "triangle-list",
+});
+
+const mesh = new Mesh({
+  geometry,
+  texture,
+  roundPixels: false,
+});
+app.stage.addChild(mesh);
+```
+
+`Mesh` is a leaf; `allowChildren` is `false`. It owns a reference to its geometry (shareable across meshes) and either a texture or a custom shader.
+
+## Constructor options
+
+`new Mesh<GEOMETRY, SHADER>(options: MeshOptions<GEOMETRY, SHADER>)`
+
+| Option        | Type                            | Default         | Description                                                                                             |
+| ------------- | ------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------- |
+| `geometry`    | `GEOMETRY extends Geometry`     | —               | Vertex buffers, indices, UVs, and topology. Required. Shareable across meshes.                          |
+| `shader`      | `SHADER extends Shader \| null` | `null`          | Custom vertex/fragment shader. When set, the mesh skips batching and the shader decides what to sample. |
+| `state`       | `State`                         | `State.for2d()` | GPU state (blend, depth, culling). Depth or culling flags disable batching.                             |
+| `texture`     | `Texture`                       | `Texture.WHITE` | Texture sampled by the default shader. Ignored if a custom `shader` provides its own texture.           |
+| `roundPixels` | `boolean`                       | `false`         | Snap `x`/`y` to integer pixels at render time.                                                          |
+
+All `Container` options (`position`, `scale`, `tint`, `label`, `filters`, `zIndex`, etc.) are also valid here — see `skills/pixijs-scene-core-concepts/references/constructor-options.md`.
+
+The constructor assigns `texture` from `shader.texture` when a custom shader is passed without an explicit `texture` option. Passing `null`/`undefined` to the `texture` setter at runtime coerces it to `Texture.EMPTY`.
+
+## Core Patterns
+
+### MeshGeometry anatomy
+
+```ts
+const geometry = new MeshGeometry({
+  positions: new Float32Array([
+    0,
+    0, // vertex 0: x, y
+    100,
+    0, // vertex 1
+    100,
+    100, // vertex 2
+    0,
+    100, // vertex 3
+  ]),
+  uvs: new Float32Array([0, 0, 1, 0, 1, 1, 0, 1]),
+  indices: new Uint32Array([0, 1, 2, 0, 2, 3]),
+  topology: "triangle-list",
+});
+```
+
+- `positions`: flat x,y pairs in local space.
+- `uvs`: flat u,v pairs in `[0, 1]` texture space. If omitted, defaults to zero-filled.
+- `indices`: triangle indices. If omitted, defaults to a quad `[0, 1, 2, 0, 2, 3]`.
+- `topology`: how indices are interpreted (see below).
+
+After construction, read or replace the typed arrays via the getters `geometry.positions`, `geometry.uvs`, `geometry.indices`. They return the underlying buffers' `data` directly; mutating in place is equivalent to mutating `getBuffer('aPosition').data`.
+
+### Topology
+
+```ts
+new MeshGeometry({ positions, uvs, indices, topology: "triangle-list" });
+```
+
+Five topology types:
+
+| Topology                    | Meaning                                          |
+| --------------------------- | ------------------------------------------------ |
+| `'triangle-list'` (default) | Every 3 indices form one triangle                |
+| `'triangle-strip'`          | Each new index extends the strip by one triangle |
+| `'line-list'`               | Pairs of indices form independent lines          |
+| `'line-strip'`              | Connected line segments                          |
+| `'point-list'`              | Each index renders a point                       |
+
+Topology is set on the **geometry**, not the mesh. The default is `'triangle-list'`; any other data layout needs an explicit topology or the mesh renders garbage.
+
+### Batching
+
+```ts
+geometry.batchMode = "auto"; // default
+geometry.batchMode = "batch"; // always batched
+geometry.batchMode = "no-batch"; // never batched
+```
+
+A mesh is batched (combined with other draw calls) only when:
+
+- It uses `MeshGeometry` (not a custom geometry subclass).
+- It has no custom `shader`.
+- Its `state` has no depth test or culling.
+- The `'auto'` rule: geometry has 100 or fewer vertices.
+
+Custom shaders always render independently. For large static meshes, set `batchMode = 'no-batch'` to skip the batch-eligibility check overhead.
+
+### Custom shader
+
+```ts
+import { Shader } from "pixi.js";
+
+const shader = Shader.from({
+  gl: { vertex: vertSrc, fragment: fragSrc },
+  resources: { uTexture: texture.source, uSampler: texture.source.style },
+});
+
+const mesh = new Mesh({ geometry, shader });
+```
+
+When a shader is provided, `texture` is optional; the shader decides what to sample. Custom shaders bypass batching entirely. See the `pixijs-custom-rendering` skill for full shader authoring detail.
+
+### Shared geometry
+
+```ts
+const sharedGeom = new MeshGeometry({ positions, uvs, indices });
+
+const mesh1 = new Mesh({ geometry: sharedGeom, texture: tex1 });
+const mesh2 = new Mesh({ geometry: sharedGeom, texture: tex2 });
+```
+
+Geometry is reference-counted. Multiple meshes can share one geometry, saving memory for instances that share a shape but differ in transform or texture.
+
+### Updating vertices at runtime
+
+```ts
+mesh.geometry.positions[1] = Math.sin(performance.now() / 500) * 20;
+mesh.geometry.getBuffer("aPosition").update();
+```
+
+`MeshGeometry` exposes `positions`, `uvs`, and `indices` getters that return the underlying `Float32Array` / `Uint32Array` directly; they point at the same data as `getBuffer('aPosition').data` / `getBuffer('aUV').data` / `getIndex().data`. Mutate in place for the common case, or assign a whole new array via the setter (the setters do `buffer.data = value` with no length check; the real invariant is `uvs.length >= positions.length` so every vertex has a UV).
+
+Call `update()` on the buffer after mutating its `data` array to push changes to the GPU. For auto-update behavior, use `MeshSimple` which handles this for you.
+
+## Common Mistakes
+
+### [HIGH] Positional constructor args
+
+Wrong:
+
+```ts
+const mesh = new Mesh(geometry, shader);
+```
+
+Correct:
+
+```ts
+const mesh = new Mesh({ geometry, shader });
+```
+
+v8 uses an options object. The positional form is deprecated and logs a warning. Note also that the `drawMode` argument was removed; use `geometry.topology` instead.
+
+
+### [HIGH] `vertices` instead of `positions`
+
+Wrong:
+
+```ts
+const geometry = new MeshGeometry({
+  vertices: new Float32Array([0, 0, 100, 0, 50, 100]),
+});
+```
+
+Correct:
+
+```ts
+const geometry = new MeshGeometry({
+  positions: new Float32Array([0, 0, 100, 0, 50, 100]),
+});
+```
+
+The `MeshGeometry` option is `positions`. `vertices` is the convenience name used only by `MeshSimple`, where it's converted internally.
+
+
+### [MEDIUM] Forgetting to set topology
+
+Wrong:
+
+```ts
+const geometry = new MeshGeometry({
+  positions: stripPositions,
+  indices: stripIndices,
+});
+```
+
+Correct:
+
+```ts
+const geometry = new MeshGeometry({
+  positions: stripPositions,
+  indices: stripIndices,
+  topology: "triangle-strip",
+});
+```
+
+The default topology is `'triangle-list'`. If your data is organized as a strip or line list, the mesh renders garbage without an explicit topology.
+
+
+## API Reference
+
+- [Mesh](https://pixijs.download/release/docs/scene.Mesh.html.md)
+- [MeshOptions](https://pixijs.download/release/docs/scene.MeshOptions.html.md)
+- [MeshGeometry](https://pixijs.download/release/docs/scene.MeshGeometry.html.md)
+- [MeshGeometryOptions](https://pixijs.download/release/docs/scene.MeshGeometryOptions.html.md)

package/vendor/pixijs-skills/skills/pixijs-scene-particle-container/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: pixijs-scene-particle-container
+description: "Use this skill when rendering thousands of lightweight sprites in PixiJS v8. Covers ParticleContainer with Particle instances, addParticle/removeParticle, particleChildren array, dynamicProperties (vertex, position, rotation, uvs, color), boundsArea, roundPixels, update, inherited alpha/tint/blendMode from ancestors. Triggers on: ParticleContainer, Particle, IParticle, addParticle, particleChildren, dynamicProperties, boundsArea, particle effects, particle alpha, particle tint, fade particles, constructor options, ParticleContainerOptions, ParticleOptions."
+license: MIT
+---
+
+`ParticleContainer` is a specialized container for rendering hundreds to tens of thousands of lightweight sprites in a single draw call. Use it for particle effects, bullet patterns, or any case where you need a large number of similar-looking objects with minimal per-object overhead. Particles share a single base texture and have a restricted transform set; they are not full `Container` children.
+
+Assumes familiarity with `pixijs-scene-core-concepts`. `ParticleContainer` is a special leaf in a different sense: it contains `Particle` instances in its own `particleChildren` array and rejects normal PixiJS children. Use `addParticle`, not `addChild`, and wrap the whole `ParticleContainer` in a `Container` if you need to group it with other scene objects.
+
+The Particle API is new in v8 but is stable for production use.
+
+## Quick Start
+
+```ts
+const texture = await Assets.load("particle.png");
+
+const container = new ParticleContainer({
+  texture,
+  boundsArea: new Rectangle(0, 0, app.screen.width, app.screen.height),
+  dynamicProperties: {
+    position: true,
+    rotation: false,
+    color: false,
+  },
+});
+
+for (let i = 0; i < 10000; i++) {
+  container.addParticle(
+    new Particle({
+      texture,
+      x: Math.random() * app.screen.width,
+      y: Math.random() * app.screen.height,
+    }),
+  );
+}
+
+app.stage.addChild(container);
+```
+
+**Related skills:** `pixijs-scene-core-concepts` (scene graph basics), `pixijs-scene-sprite` (when you need full features per object), `pixijs-assets` (shared textures, atlases), `pixijs-performance` (batching, texture optimization), `pixijs-scene-container` (wrap with other display objects).
+
+## Constructor options
+
+### ParticleContainerOptions
+
+All `Container` options (`position`, `scale`, `tint`, `label`, `filters`, `zIndex`, etc.) are also valid here — see `skills/pixijs-scene-core-concepts/references/constructor-options.md`. Note that `children` is omitted: use `particles` instead.
+
+| Option              | Type                 | Default                                                                        | Description                                                                                                                                                                     |
+| ------------------- | -------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `texture`           | `Texture`            | `null`                                                                         | Shared base texture for all particles. If omitted, the container falls back to the texture of the first particle added; every particle must share the same base texture source. |
+| `particles`         | `T[]`                | `[]`                                                                           | Initial array of `Particle` (or `IParticle`) instances. Equivalent to calling `addParticle` for each, but skips per-call view updates.                                          |
+| `dynamicProperties` | `ParticleProperties` | `{ vertex: false, position: true, rotation: false, uvs: false, color: false }` | Flags for which particle attributes re-upload to the GPU every frame. Only `position` is dynamic by default; mark what you animate, leave the rest static for speed.            |
+| `roundPixels`       | `boolean`            | `false`                                                                        | Rounds particle positions to the nearest pixel. Produces crisper rendering for pixel-art styles at the cost of smooth sub-pixel motion.                                         |
+| `shader`            | `Shader`             | default particle shader                                                        | Replaces the default particle shader. The custom shader must declare `aPosition`, `aUV`, `aColor`, plus any dynamic-only attributes enabled via `dynamicProperties`.            |
+
+`boundsArea` is inherited from `Container` but is effectively required on `ParticleContainer`: the container returns empty bounds `(0, 0, 0, 0)` by default for performance, so without `boundsArea` it is culled as invisible when culling is active and `containsPoint` always misses.
+
+### ParticleOptions
+
+`Particle` is a lightweight struct, not a `Container` subclass — none of the `ContainerOptions` fields apply. The full option list:
+
+| Option     | Type          | Default    | Description                                                                                                                            |
+| ---------- | ------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `texture`  | `Texture`     | —          | Required. Texture used to render this particle. All particles in the same `ParticleContainer` must share the same base texture source. |
+| `x`        | `number`      | `0`        | X position in the container's local space.                                                                                             |
+| `y`        | `number`      | `0`        | Y position in the container's local space.                                                                                             |
+| `scaleX`   | `number`      | `1`        | Horizontal scale factor.                                                                                                               |
+| `scaleY`   | `number`      | `1`        | Vertical scale factor.                                                                                                                 |
+| `anchorX`  | `number`      | `0`        | Horizontal anchor in 0–1 range; `0` is left, `0.5` is center, `1` is right.                                                            |
+| `anchorY`  | `number`      | `0`        | Vertical anchor in 0–1 range; `0` is top, `0.5` is center, `1` is bottom.                                                              |
+| `rotation` | `number`      | `0`        | Rotation in radians.                                                                                                                   |
+| `tint`     | `ColorSource` | `0xffffff` | Tint color as hex number or CSS color string. Combined with `alpha` into the internal `color` field.                                   |
+| `alpha`    | `number`      | `1`        | Transparency (0–1). Values outside the range are clamped. Combined with `tint` into the internal `color` field.                        |
+
+The constructor also accepts a bare `Texture` as its sole argument (`new Particle(texture)`), which is shorthand for `new Particle({ texture })` using the defaults above.
+
+`Particle.defaultOptions` is a static object you can reassign to change defaults globally; see the "Particle creation" section below.
+
+## Core Patterns
+
+### Particle creation
+
+```ts
+const particle = new Particle({
+  texture,
+  x: 100,
+  y: 200,
+  scaleX: 0.5,
+  scaleY: 0.5,
+  anchorX: 0.5,
+  anchorY: 0.5,
+  rotation: Math.PI / 4,
+  tint: 0xff0000,
+  alpha: 0.8,
+});
+
+container.addParticle(particle);
+```
+
+`Particle` is a lightweight struct with flat numeric fields: `x`, `y`, `scaleX`, `scaleY`, `anchorX`, `anchorY`, `rotation`, `color`, `texture`. It also exposes `tint` (hex/CSS color) and `alpha` (0-1) as setters that combine into the internal `color` field. No transform hierarchy, no events, no filters.
+
+You can pass a `Texture` directly as the sole argument: `new Particle(texture)`.
+
+Override `Particle.defaultOptions` to change defaults globally:
+
+```ts
+Particle.defaultOptions = {
+  ...Particle.defaultOptions,
+  anchorX: 0.5,
+  anchorY: 0.5,
+};
+```
+
+### Pre-populating with the particles option
+
+```ts
+const particles = Array.from(
+  { length: 10000 },
+  () =>
+    new Particle({
+      texture,
+      x: Math.random() * 800,
+      y: Math.random() * 600,
+    }),
+);
+
+const container = new ParticleContainer({
+  texture,
+  boundsArea: new Rectangle(0, 0, 800, 600),
+  particles,
+});
+```
+
+Passing `particles` in the constructor is equivalent to creating the container empty and calling `addParticle` for each one, but avoids per-call view updates.
+
+### Dynamic vs static properties and update()
+
+```ts
+const container = new ParticleContainer({
+  dynamicProperties: {
+    rotation: true,
+  },
+});
+```
+
+`dynamicProperties` controls which particle attributes re-upload to the GPU every frame. The defaults on `ParticleContainer.defaultOptions.dynamicProperties` are:
+
+```ts
+{ vertex: false, position: true, rotation: false, uvs: false, color: false }
+```
+
+You only need to override the properties you are animating; the rest inherit the defaults (position dynamic, everything else static). Five properties in total:
+
+- `vertex`: scale/anchor vertices
+- `position`
+- `rotation`
+- `uvs`: texture coordinates (for frame-swapped particles)
+- `color`: tint and alpha
+
+Mark only what you animate; static properties are cheaper. If you change a static property at runtime, call `container.update()` to re-upload:
+
+```ts
+container.particleChildren.forEach((p) => {
+  p.tint = 0x00ff00;
+});
+container.update();
+```
+
+### Batch operations on particleChildren
+
+```ts
+// Bulk add
+const batch = [];
+for (let i = 0; i < 5000; i++) {
+  batch.push(
+    new Particle({ texture, x: Math.random() * 800, y: Math.random() * 600 }),
+  );
+}
+container.particleChildren.push(...batch);
+container.update();
+
+// Bulk remove
+container.particleChildren.length = 0;
+container.update();
+```
+
+`addParticle`, `addParticleAt`, `removeParticle`, `removeParticleAt`, and `removeParticles` all trigger view updates per call. For large batch operations, direct array manipulation plus a single `update()` is faster.
+
+### Texture and shader options
+
+`texture` in `ParticleContainerOptions` is optional. If omitted, the container falls back to the texture of the first particle added; every subsequent particle must share the same base texture source. Set it explicitly when you want to declare the atlas up front, or when the first particle might change mid-run:
+
+```ts
+const container = new ParticleContainer({ texture });
+```
+
+`shader` lets you replace the default particle shader with any `Shader` instance. The custom shader must declare the attributes the particle pipe uploads (`aPosition`, `aUV`, `aColor`, plus any dynamic-only attributes enabled via `dynamicProperties`). Use this for custom blending math, distance-field sprites, or non-standard effects:
+
+```ts
+const container = new ParticleContainer({ texture, shader: myCustomShader });
+```
+
+### Fading or tinting a whole particle system
+
+```ts
+const burst = new ParticleContainer({ texture, particles });
+const layer = new Container();
+layer.addChild(burst);
+
+app.ticker.add(() => {
+  layer.alpha -= 0.01; // fades every particle
+});
+burst.tint = 0x66ccff; // tints every particle
+```
+
+Container `alpha`, `tint`, and `blendMode` cascade into particles the same way they cascade into sprites, so you can fade or recolor an entire system without touching `particleChildren`.
+
+### Limitations
+
+`ParticleContainer` intentionally sacrifices features for speed:
+
+- No filters, masks, or per-particle blend modes. Blend modes apply at the container level: set `blendMode` on the `ParticleContainer` or let it inherit from a parent `Container` (the default `"inherit"` resolves to the ancestor's blend mode, like `Sprite` and `Mesh`). The whole particle batch shares one blend mode. `alpha` and `tint` on the container or any ancestor multiply into every particle, on top of each particle's own `alpha`/`tint`.
+- No nested children on particles.
+- No automatic bounds calculation.
+- All particles must share the same base texture source (atlases work; multiple unrelated textures do not).
+- Custom shaders are supported via the `shader` option.
+
+### Container method migration
+
+`ParticleContainer` uses a separate child management API optimized for GPU buffer updates. The standard `Container` child methods throw when called on a `ParticleContainer`.
+
+| Standard Container method    | ParticleContainer equivalent                        |
+| ---------------------------- | --------------------------------------------------- |
+| `addChild(child)`            | `addParticle(particle)`                             |
+| `removeChild(child)`         | `removeParticle(particle)`                          |
+| `addChildAt(child, index)`   | `addParticleAt(particle, index)`                    |
+| `removeChildAt(index)`       | `removeParticleAt(index)`                           |
+| `removeChildren(begin, end)` | `removeParticles(begin, end)`                       |
+| `getChildAt(index)`          | Access `container.particleChildren[index]` directly |
+| `swapChildren()`             | Not available                                       |
+| `reparentChild()`            | Not available                                       |
+
+## Common Mistakes
+
+### [CRITICAL] Adding Sprites to ParticleContainer
+
+Wrong:
+
+```ts
+const container = new ParticleContainer();
+const sprite = new Sprite(texture);
+container.addChild(sprite);
+```
+
+Correct:
+
+```ts
+const container = new ParticleContainer();
+const particle = new Particle(texture);
+container.addParticle(particle);
+```
+
+`ParticleContainer` does not accept `Sprite` children. `addChild` throws an error. Particles must be `Particle` instances (or any object implementing `IParticle`), added via `addParticle`. This is a complete rework from v7, where `ParticleContainer` accepted `Sprite` children.
+
+
+### [HIGH] Not setting boundsArea on ParticleContainer
+
+Wrong:
+
+```ts
+const container = new ParticleContainer();
+// bounds is always (0, 0, 0, 0) — culling and hit testing fail
+```
+
+Correct:
+
+```ts
+const container = new ParticleContainer({
+  boundsArea: new Rectangle(0, 0, 800, 600),
+});
+```
+
+`ParticleContainer` returns empty bounds `(0, 0, 0, 0)` by default for performance. Without `boundsArea`, the container is culled as invisible when culling is active, and `containsPoint` always misses. Set `boundsArea` to the region your particles occupy.
+
+
+### [HIGH] Using children instead of particleChildren
+
+Wrong:
+
+```ts
+container.addParticle(new Particle(texture));
+console.log(container.children.length); // 0
+```
+
+Correct:
+
+```ts
+container.addParticle(new Particle(texture));
+console.log(container.particleChildren.length); // 1
+```
+
+Particles are stored in the `particleChildren` array, not `children`. The standard `Container.children` array is empty on a `ParticleContainer`. All particle enumeration, counting, and manipulation must use `particleChildren` plus the `*Particle` methods.
+
+
+### [MEDIUM] Do not use ParticleContainer as a normal container
+
+`ParticleContainer` contains particles, not display objects. If you need to group a particle system with a background sprite or UI overlay, wrap the `ParticleContainer` itself inside a plain `Container`:
+
+```ts
+const world = new Container();
+world.addChild(backgroundSprite, particleContainer, uiLayer);
+```
+
+
+## API Reference
+
+- [ParticleContainer](https://pixijs.download/release/docs/scene.ParticleContainer.html.md)
+- [ParticleContainerOptions](https://pixijs.download/release/docs/scene.ParticleContainerOptions.html.md)
+- [Particle](https://pixijs.download/release/docs/scene.Particle.html.md)
+- [ParticleOptions](https://pixijs.download/release/docs/scene.ParticleOptions.html.md)
+- [IParticle](https://pixijs.download/release/docs/scene.IParticle.html.md)
+- [ParticleProperties](https://pixijs.download/release/docs/scene.ParticleProperties.html.md)