@docyrus/animaguru 0.6.0

package/vendor/pixijs-skills/skills/pixijs-scene-core-concepts/references/render-groups.md

@@ -0,0 +1,140 @@
+# Render Groups
+
+A render group is a `Container` whose transform (position, scale, rotation, alpha, tint) is applied on the GPU as a single operation rather than being recalculated per-child on the CPU every frame. Use render groups for large stable sub-trees such as a game world, a HUD, or a parallax strip. Each render group owns its own instruction set and cannot batch with other groups.
+
+## Quick Start
+
+```ts
+const world = new Container({ isRenderGroup: true });
+const hud = new Container({ isRenderGroup: true });
+
+app.stage.addChild(world, hud);
+
+for (let i = 0; i < 5000; i++) {
+  const bunny = new Sprite(bunnyTexture);
+  bunny.x = Math.random() * 2000;
+  bunny.y = Math.random() * 2000;
+  world.addChild(bunny);
+}
+
+world.x = 100; // applied once on the GPU, not 5000 times on the CPU
+```
+
+Flag a container with `isRenderGroup: true` at construction, or call `enableRenderGroup()` at runtime.
+
+## Core Patterns
+
+### Construction options
+
+```ts
+const world = new Container({ isRenderGroup: true });
+
+const hud = new Container();
+hud.enableRenderGroup();
+```
+
+Both forms work. Pre-declare via the options object for static setups; call `enableRenderGroup()` when you want to flip the flag at runtime.
+
+### The three transform levels
+
+When a render group is in the chain, PixiJS composes three matrices:
+
+1. `localTransform`; from the container's own position, scale, rotation, pivot, skew.
+2. `groupTransform`; the child's position relative to the render group it belongs to.
+3. `worldTransform`; the scene-root-space matrix.
+
+For children inside a render group, the CPU only maintains `localTransform` and `groupTransform`. The GPU applies the group's own `worldTransform` once, then draws all the children. This is the performance win: the per-child CPU matrix math is cut from "one full walk per frame" to "one walk when children move."
+
+### When to use render groups
+
+Good fits:
+
+- Game world with thousands of static entities.
+- UI layer that mostly stays put.
+- Parallax background strips.
+- A menu or HUD overlay that scales or translates as a whole.
+
+Bad fits:
+
+- Small sub-trees (a dozen children). Overhead outweighs the save.
+- Constantly-changing structure (children being added / removed per frame).
+- Sub-trees that need to batch with other objects outside the group.
+
+### Profile before adding
+
+```ts
+// Start without explicit render groups
+const world = new Container();
+
+// Measure frames, identify bottleneck
+
+// Add if CPU transform updates dominate
+world.enableRenderGroup();
+```
+
+Most scenes don't need explicit render groups beyond the auto-created root. The scene root container passed to `renderer.render()` is automatically a render group. Add explicit groups only when profiling shows CPU transform costs dominating.
+
+### Render groups vs cacheAsTexture
+
+```ts
+const hud = new Container();
+hud.cacheAsTexture({ antialias: true });
+
+const world = new Container({ isRenderGroup: true });
+```
+
+- `cacheAsTexture()` rasterizes the sub-tree once to a texture and draws that texture each frame. Best for things that don't change visually.
+- `isRenderGroup` keeps normal drawing but moves the group transform work to the GPU. Best for sub-trees whose children animate freely but whose structure is stable.
+
+Render groups are lighter than cacheAsTexture and preserve dynamic children. Use cacheAsTexture only when the sub-tree is genuinely static.
+
+## Common Mistakes
+
+### [MEDIUM] Overusing render groups
+
+Wrong:
+
+```ts
+for (const enemy of enemies) {
+  enemy.enableRenderGroup();
+}
+```
+
+Each render group has its own instruction set and can't batch with other groups. A scene with many small render groups generates many separate draw buckets, which is slower than a single batched draw. Apply render groups at a coarse level (world, HUD), not per-entity.
+
+
+### [HIGH] Nesting many render groups
+
+Wrong:
+
+```ts
+const world = new Container({ isRenderGroup: true });
+const section = new Container({ isRenderGroup: true });
+const tile = new Container({ isRenderGroup: true });
+world.addChild(section);
+section.addChild(tile);
+```
+
+Correct:
+
+```ts
+const world = new Container({ isRenderGroup: true });
+const section = new Container();
+const tile = new Container();
+world.addChild(section);
+section.addChild(tile);
+```
+
+Deep nesting of render groups multiplies the instruction set overhead. Pick a single level (usually one per "subsystem") and let the children be normal containers.
+
+
+### [MEDIUM] Constantly adding/removing from a render group
+
+If the sub-tree structure changes every frame (not just child transforms), the render group's instruction set is rebuilt each time, negating the performance benefit. Render groups help stable structures with animated children; not dynamic structures.
+
+
+## API Reference
+
+- [RenderGroup](https://pixijs.download/release/docs/rendering.RenderGroup.html.md)
+- [Container](https://pixijs.download/release/docs/scene.Container.html.md)
+- [ContainerOptions](https://pixijs.download/release/docs/scene.ContainerOptions.html.md)

package/vendor/pixijs-skills/skills/pixijs-scene-core-concepts/references/scene-management.md

@@ -0,0 +1,169 @@
+# Scene Management: Render Groups, Layers, and Culling
+
+Organize PixiJS scenes with render groups (GPU-level transforms), RenderLayer (decoupled render order), culling (offscreen optimization), zIndex sorting, and boundsArea optimization.
+
+## Quick Start
+
+```ts
+const world = new Container({ isRenderGroup: true });
+const hud = new Container({ isRenderGroup: true });
+app.stage.addChild(world, hud);
+
+const bgLayer = new RenderLayer();
+const entityLayer = new RenderLayer();
+const uiLayer = new RenderLayer();
+app.stage.addChild(bgLayer, entityLayer, uiLayer);
+
+const player = new Sprite(texture);
+world.addChild(player);
+entityLayer.attach(player);
+```
+
+## Core Patterns
+
+### Render groups for GPU-level transforms
+
+A render group is a container whose transform (position, scale, rotation, alpha, tint) is applied on the GPU as a single operation rather than being recalculated per-child on the CPU. The root container passed to `renderer.render()` is automatically a render group.
+
+```ts
+const gameWorld = new Container({ isRenderGroup: true });
+const uiLayer = new Container({ isRenderGroup: true });
+
+scene.addChild(gameWorld, uiLayer);
+
+gameWorld.x += 10;
+
+const panel = new Container();
+panel.enableRenderGroup();
+```
+
+Use render groups for large stable sub-trees (the structure stays the same even though children move/rotate). Children inside can still animate freely; "stable" means children are not being constantly added/removed.
+
+The scene has three matrix levels:
+
+1. `localTransform` - based on the container's own position/scale/rotation
+2. `groupTransform` - relative to the render group it belongs to
+3. `worldTransform` - relative to the scene root
+
+### RenderLayer for decoupled render order
+
+RenderLayer separates render order from scene graph hierarchy. Objects keep their logical parent for transforms but render at the layer's position in the scene.
+
+```ts
+const bgLayer = new RenderLayer();
+const entityLayer = new RenderLayer();
+const uiLayer = new RenderLayer();
+
+app.stage.addChild(bgLayer, entityLayer, uiLayer);
+
+const player = new Sprite(texture);
+const world = new Container();
+world.addChild(player);
+entityLayer.attach(player);
+
+entityLayer.detach(player);
+entityLayer.detachAll();
+
+const sortedLayer = new RenderLayer({
+  sortableChildren: true,
+  sortFunction: (a, b) => a.position.y - b.position.y,
+});
+```
+
+Key constraints:
+
+- `addChild()` / `removeChild()` on RenderLayer throws an error. Use `attach()` / `detach()`.
+- Objects removed from their scene graph parent via `removeChild()` are automatically detached from their layer.
+- Re-adding an object to the scene graph does NOT automatically re-attach it to the layer. You must call `attach()` again.
+- Layers and their children must belong to the same render group.
+
+### Culling
+
+Culling skips rendering objects outside the visible area. In v8, culling is manual; it does not happen automatically during render.
+
+```ts
+const stage = new Container();
+
+for (let i = 0; i < 1000; i++) {
+  const sprite = Sprite.from("bunny.png");
+  sprite.x = Math.random() * 5000;
+  sprite.y = Math.random() * 5000;
+  sprite.cullable = true;
+  stage.addChild(sprite);
+}
+
+const view = { x: 0, y: 0, width: 800, height: 600 };
+Culler.shared.cull(stage, view);
+renderer.render(stage);
+```
+
+For automatic culling with Application, register CullerPlugin:
+
+```ts
+import { extensions, CullerPlugin } from "pixi.js";
+extensions.add(CullerPlugin);
+
+const app = new Application();
+await app.init({ width: 800, height: 600 });
+```
+
+Set `cullArea` on a container to define a custom cull region instead of computing bounds:
+
+```ts
+container.cullArea = new Rectangle(0, 0, 1000, 1000);
+container.cullable = true;
+```
+
+### zIndex sorting
+
+```ts
+const parent = new Container({ sortableChildren: true });
+
+const bg = new Sprite(bgTexture);
+bg.zIndex = 0;
+
+const player = new Sprite(playerTexture);
+player.zIndex = 10;
+
+const fg = new Sprite(fgTexture);
+fg.zIndex = 20;
+
+parent.addChild(fg, bg, player);
+```
+
+Setting `zIndex` on a child automatically enables `sortableChildren` on its parent, so the explicit constructor option is only needed when you want sorting enabled before any child sets a zIndex.
+
+### boundsArea optimization
+
+Setting `boundsArea` on a container prevents recursive bounds measurement of all children. Useful for containers with many children whose aggregate bounds are known.
+
+```ts
+const particles = new Container();
+particles.boundsArea = new Rectangle(0, 0, 800, 600);
+```
+
+## Common Mistakes
+
+### MEDIUM: Overusing render groups
+
+Each render group has its own instruction set and cannot batch with other groups. Use render groups at a broad level (game world, HUD), not per-child. Profile before adding them; most scenes do not need any explicit render groups beyond the auto-created root.
+
+### HIGH: Expecting automatic culling
+
+v8 culling is explicit. Setting `cullable=true` only marks the container as eligible. You must call `Culler.shared.cull()` before rendering, or register `CullerPlugin` for automatic culling with Application.
+
+### MEDIUM: Expecting filters on ancestors to apply to layer children
+
+RenderLayer children are rendered outside their parent's filter scope. Filters capture children into a texture via push/pop, but layer-attached children skip their parent's collection and render at the layer's position instead. Apply filters directly to the child when using RenderLayer.
+
+### HIGH: Using addChild on RenderLayer
+
+RenderLayer overrides `addChild`, `removeChild`, and related methods to throw errors. Use `attach()` and `detach()` for layer membership. The object still needs a scene graph parent via `addChild` on a regular Container for transforms.
+
+## API Reference
+
+- [RenderLayer](https://pixijs.download/release/docs/scene.RenderLayer.html.md)
+- [Container](https://pixijs.download/release/docs/scene.Container.html.md)
+- [Culler](https://pixijs.download/release/docs/scene.Culler.html.md)
+- [CullerPlugin](https://pixijs.download/release/docs/app.CullerPlugin.html.md)
+- [RenderGroup](https://pixijs.download/release/docs/rendering.RenderGroup.html.md)

package/vendor/pixijs-skills/skills/pixijs-scene-core-concepts/references/transforms.md

@@ -0,0 +1,198 @@
+# Transforms and Coordinate Spaces
+
+Every `Container` has a transform: position, scale, rotation, pivot, skew, and origin. These combine into a `localTransform` matrix, which compounds with ancestors to produce the `worldTransform`. Use this reference for coordinate-space conversion and the details of setting vs. animating transforms. For matrix math, see `pixijs-math`.
+
+## Quick Start
+
+```ts
+const hero = new Container();
+hero.x = 100;
+hero.y = 200;
+hero.scale.set(2);
+hero.rotation = Math.PI / 4;
+
+const worldPoint = hero.toGlobal({ x: 0, y: 0 });
+const localPoint = hero.toLocal({ x: 300, y: 300 });
+```
+
+Transforms are local to the parent. `toGlobal` and `toLocal` convert between coordinate spaces.
+
+## Core Patterns
+
+### Position, scale, rotation
+
+```ts
+container.x = 100;
+container.y = 200;
+container.position.set(100, 200);
+
+container.scale.set(2); // uniform
+container.scale.set(1.5, 0.8); // non-uniform
+container.scale.x = 2;
+
+container.rotation = Math.PI / 4; // radians
+container.angle = 45; // degrees (convenience)
+```
+
+`position`, `scale`, and `pivot` are `ObservablePoint` instances; direct assignment via `x` / `y` works, or call `set(x, y?)`. Setting them triggers the parent's transform update flag.
+
+### Pivot
+
+```ts
+sprite.pivot.set(sprite.width / 2, sprite.height / 2);
+sprite.x = 200;
+sprite.y = 200;
+sprite.rotation += 0.01;
+```
+
+`pivot` is the point around which rotation and scale apply; in the **container's own local pixel space**. A pivot of `(w/2, h/2)` rotates around the center.
+
+For `Sprite`, prefer `anchor` (normalized 0–1) which only shifts the texture draw origin without offsetting the position. Pivot shifts the position too.
+
+### Origin (new in v8)
+
+```ts
+container.origin.set(100, 50);
+```
+
+`origin` is an alternative transform origin that shifts the rotation/scale pivot **without offsetting the visual position**. Think of it as "pivot, but without the position shift." Useful when you want to spin a large container around an off-center point while keeping it visually anchored to its `x` / `y`.
+
+### Skew
+
+```ts
+container.skew.set(0.1, 0);
+```
+
+Rarely used. Skew shears the coordinate space by `x` / `y` radians. Useful for fake perspective and isometric effects.
+
+### Coordinate conversion
+
+```ts
+const globalPoint = container.toGlobal({ x: 10, y: 20 });
+
+const localPoint = container.toLocal({ x: 400, y: 300 });
+
+const localFromSprite = container.toLocal({ x: 0, y: 0 }, otherSprite);
+
+const cached = container.getGlobalPosition();
+```
+
+- `toGlobal(localPoint)`: convert from this container's local space to global (scene root) space.
+- `toLocal(point, from?)`: convert from global (or another container's) space to this container's local space.
+- `getGlobalPosition()`: shortcut for `toGlobal({ x: 0, y: 0 })`; this container's origin in global space.
+
+All three accept an optional `point` argument to write into (reduces allocation in hot paths) and a `skipUpdate` flag that uses the cached transform (faster but can be stale).
+
+### The three matrices
+
+```ts
+container.localTransform; // from this node's own position/scale/rotation/pivot/skew
+container.groupTransform; // relative to the render group it belongs to
+container.worldTransform; // relative to the scene root
+```
+
+Each frame, PixiJS composes these three levels:
+
+1. `localTransform`; derived from the container's own transform setters.
+2. `groupTransform`; if an ancestor is a render group, this is the transform relative to that group.
+3. `worldTransform`; relative to the scene root; what the renderer consumes.
+
+For normal code, set `x` / `y` / `scale` / `rotation` and let the renderer compose the rest. Reading `worldTransform` directly is useful for hit testing, custom rendering, or integrating with physics.
+
+### Sizing via width, height, setSize
+
+```ts
+container.width = 100;
+container.height = 200;
+
+container.setSize(100, 200);
+const { width, height } = container.getSize();
+```
+
+Setting `width` and `height` scales the container to fit the requested dimensions; internally they assign `scale.x` / `scale.y` based on the measured bounds. Assigning the two setters independently re-measures the subtree twice, which is wasteful. Use `setSize(width, height?)` to assign both in a single pass, and `getSize()` to read them back as `{ width, height }`.
+
+### Bounds in different spaces
+
+```ts
+const localBounds = container.getLocalBounds();
+const globalBounds = container.getBounds();
+
+const reusable = new Bounds();
+container.getBounds(true, reusable); // skipUpdate + in-place
+
+const rect = container.getBounds().rectangle;
+rect.contains(pointerX, pointerY);
+```
+
+- `getLocalBounds()`: rectangle in the container's own local space.
+- `getBounds(skipUpdate?, bounds?)`: rectangle in world space (accounts for all ancestor transforms). Pass `true` for `skipUpdate` to reuse the cached transform instead of forcing a fresh pass, and pass an existing `Bounds` instance as the second argument to avoid allocating a new one.
+
+Both methods return a `Bounds` instance, not a `Rectangle`. `Bounds` exposes `x`, `y`, `width`, and `height` getters plus a `.rectangle` accessor for APIs like `Rectangle.contains()`.
+
+Bounds are recalculated lazily. Call them sparingly; each call walks the container's sub-tree. For containers with many cheap children (particles, tile layers), set `container.boundsArea = new Rectangle(0, 0, w, h)` so `getBounds()` returns that rectangle directly without recursing.
+
+### Global, local, and screen coordinates
+
+PixiJS uses three coordinate spaces:
+
+- **Local**: relative to the object's parent. This is what `container.x` / `container.y` and `position.set()` always operate on.
+- **Global** (a.k.a. "world"): relative to the scene root. `toGlobal()`, `toLocal()`, and `getGlobalPosition()` convert between local and global space.
+- **Screen** (a.k.a. "viewport"): relative to the top-left of the canvas element PixiJS is rendering into. DOM events and native mouse clicks use screen space.
+
+Global and screen usually match, but they diverge when the canvas is CSS-scaled or rendered at a non-1 resolution. PixiJS's event system handles this conversion automatically for pointer events, so `onPointerDown` handlers always receive global coordinates. When you need raw screen coordinates, read `renderer.events.pointer`; use `toLocal` / `toGlobal` for the world side.
+
+### Cumulative alpha (getGlobalAlpha)
+
+`container.alpha` is local to the container; the cumulative alpha (parent × this × ancestors) is exposed via `container.getGlobalAlpha(skipUpdate?)`. It's computed during render, so reading it before the first frame returns 1 on a freshly-added subtree. Useful for custom render hooks that need to know how transparent the renderer will actually draw this node.
+
+## Common Mistakes
+
+### [HIGH] Setting scale to 0
+
+Wrong:
+
+```ts
+container.scale.set(0);
+```
+
+Correct:
+
+```ts
+container.scale.set(0.01); // or use visible = false
+container.visible = false;
+```
+
+Scale of exactly 0 collapses the transform matrix to zero, and any subsequent `toLocal` / `toGlobal` / inverse calculations divide by zero. Use `visible = false` to hide, or scale to a tiny non-zero value if you need an animation.
+
+
+### [MEDIUM] Reading world transform before first render
+
+Wrong:
+
+```ts
+const pos = container.getGlobalPosition();
+console.log(pos); // { x: 0, y: 0 } even though container.x is set
+```
+
+Correct:
+
+```ts
+app.stage.addChild(container);
+await new Promise((r) => requestAnimationFrame(r));
+const pos = container.getGlobalPosition();
+```
+
+`worldTransform` is computed during render. Before the first render, it's identity. If you need a live position before rendering, use `container.toGlobal({x:0, y:0})` which walks the transforms explicitly.
+
+
+### [MEDIUM] Confusing anchor and pivot
+
+On `Sprite`, `anchor` is normalized (0–1) and shifts only the draw origin. `pivot` is in pixel space and shifts both the transform origin AND the visual position. For centering a sprite, use `anchor`. For off-center rotation of a Container (which has no `anchor`), use `pivot`.
+
+
+## API Reference
+
+- [Container](https://pixijs.download/release/docs/scene.Container.html.md)
+- [ToLocalGlobalMixin](https://pixijs.download/release/docs/scene.ToLocalGlobalMixin.html.md)
+- [Matrix](https://pixijs.download/release/docs/maths.Matrix.html.md)
+- [ObservablePoint](https://pixijs.download/release/docs/maths.ObservablePoint.html.md)