@docyrus/animaguru 0.6.0

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

@@ -0,0 +1,345 @@
+---
+name: pixijs-scene-container
+description: "Use this skill when grouping, positioning, or transforming display objects in PixiJS v8. Covers Container constructor options (isRenderGroup, sortableChildren, boundsArea), addChild/removeChild/addChildAt/swapChildren/setChildIndex, position/scale/rotation/pivot/skew/alpha/tint, getBounds/getGlobalPosition/toLocal/toGlobal, zIndex sorting, cullable, onRender per-frame callback, destroy. Triggers on: Container, addChild, removeChild, addChildAt, swapChildren, sortableChildren, zIndex, position, scale, rotation, pivot, getBounds, toGlobal, toLocal, onRender, destroy, constructor options, ContainerOptions."
+license: MIT
+---
+
+`Container` is the general-purpose node of the PixiJS v8 scene graph. It holds children and applies transforms, alpha, tint, and blend mode to its whole subtree. Every display object you make will either be a `Container` you're building a branch on, or a leaf (`Sprite`, `Graphics`, `Text`, `Mesh`) that you nest inside one.
+
+Assumes familiarity with `pixijs-scene-core-concepts`.
+
+## Quick Start
+
+```ts
+const group = new Container({
+  label: "hero-group",
+  x: 200,
+  y: 150,
+  sortableChildren: true,
+});
+
+const body = new Sprite(await Assets.load("body.png"));
+const head = new Sprite(await Assets.load("head.png"));
+head.position.set(0, -40);
+head.zIndex = 1;
+
+group.addChild(body, head);
+group.pivot.set(group.width / 2, group.height / 2);
+group.scale.set(1.5);
+
+app.stage.addChild(group);
+```
+
+**Related skills:** `pixijs-scene-core-concepts` (scene graph mental model, masking, layers, render groups), `pixijs-scene-sprite` / `pixijs-scene-graphics` / `pixijs-scene-text` / `pixijs-scene-mesh` (leaf objects that go inside containers), `pixijs-events` (`eventMode`, hit testing), `pixijs-math` (Matrix, toGlobal/toLocal detail), `pixijs-performance` (`cacheAsTexture`, culling, render groups).
+
+## Core Patterns
+
+### Constructor options
+
+```ts
+const container = new Container({
+  label: "world",
+  x: 100,
+  y: 50,
+  scale: 2,
+  rotation: Math.PI / 4,
+  alpha: 0.8,
+  visible: true,
+  tint: 0xffaa00,
+  blendMode: "add",
+  sortableChildren: true,
+  isRenderGroup: true,
+  origin: { x: 0, y: 0 },
+  boundsArea: new Rectangle(0, 0, 1920, 1080),
+});
+```
+
+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 `Container` constructor uses `assignWithIgnore` to bulk-copy every field in the options object onto the instance except `children`, `parent`, and `effects`. Any public property of `Container` is a valid constructor option: `cullable`, `cullArea`, `mask`, `filterArea`, `eventMode`, `hitArea`, and so on. The options block above groups the most common ones; see the shared reference above for the full list.
+
+`isRenderGroup: true` promotes the container to its own render group so its transforms are applied on the GPU rather than recomputed per-child on the CPU. Use it on stable sub-trees (large static worlds, UI layers). Don't overuse; most scenes don't need explicit render groups and too many hurts performance. Profile before promoting. See `pixijs-scene-core-concepts/references/scene-management.md`.
+
+`sortableChildren: true` causes children to be re-sorted by `zIndex` at the next render. See `zIndex` below.
+
+`origin` is a first-class v8 transform helper: an `ObservablePoint` that acts as a rotation/scale center **without** moving the container. Where `pivot` shifts the projection of the local origin in parent space (so changing it displaces the object), `origin` leaves position alone and simply rotates/scales around the specified local point. Accepts `PointData`, a single number (applied to both axes), or can be set live via `container.origin.set(x, y)`. Setting both `pivot` and `origin` on the same container produces compounding behavior and is discouraged; pick one.
+
+`boundsArea` forces `getBounds()` to return a fixed rectangle instead of recursively measuring children; it is a performance win for containers with hundreds of cheap, predictable children.
+
+`cullable` and `cullArea` are valid constructor options (the `assignWithIgnore` pass copies them like any other field), but they are documented in `pixijs-performance` because culling setup is a performance concern rather than a scene-graph concern.
+
+### Leaves vs containers
+
+```ts
+const parent = new Container();
+const sprite = new Sprite(texture);
+
+parent.addChild(sprite);
+```
+
+Only `Container` (and subclasses intended to hold children, like `RenderLayer`) should have children. `Sprite`, `Graphics`, `Text`, `Mesh`, `ParticleContainer` particles, and `DOMContainer` content are leaves by convention in PixiJS v8. Wrap them in a `Container` whenever you need to group things: give the container the layout logic and keep the leaves pure visual data. Adding children to a leaf logs a deprecation warning and is scheduled to become a hard error.
+
+### Adding and removing children
+
+```ts
+const parent = new Container();
+
+parent.addChild(a, b, c);
+parent.addChildAt(d, 0);
+parent.swapChildren(a, b);
+parent.setChildIndex(c, 0);
+
+parent.removeChild(b);
+parent.removeChildAt(0);
+parent.removeChildren();
+
+parent.removeChildren(0, 2);
+```
+
+`addChild` accepts any number of children and returns the first one. Children render in array order: index 0 is drawn first (behind), the last index is drawn last (in front). `addChildAt` inserts at a specific index; `setChildIndex` moves an existing child; `swapChildren` exchanges two children's positions.
+
+`removeChildren(beginIndex?, endIndex?)` removes a slice and returns the removed array.
+
+Calling `addChildAt` with a child that already belongs to the same container silently moves it to the new index. No `added` / `childAdded` / `removed` / `childRemoved` events fire, because the parent-child relationship didn't change. Events only fire when the child comes from a different parent (or from no parent).
+
+For reparenting that preserves world transform (so the child doesn't visually jump), use `reparentChild` / `reparentChildAt`. For swapping a child in place while copying the old child's local transform, use `replaceChild`.
+
+### Transform properties
+
+```ts
+const obj = new Container();
+
+obj.x = 100;
+obj.y = 200;
+obj.position.set(100, 200);
+
+obj.scale.set(2);
+obj.scale = 2;
+
+obj.rotation = Math.PI / 4;
+obj.angle = 45;
+
+obj.pivot.set(50, 50);
+obj.skew.set(0.1, 0.2);
+
+obj.alpha = 0.5;
+obj.tint = 0xff0000;
+obj.visible = false;
+obj.renderable = false;
+```
+
+- `position`, `scale`, `pivot`, `skew` are `ObservablePoint`s. Assigning `scale = 2` is valid and sets both axes.
+- `rotation` is radians; `angle` is degrees; they are aliases that stay in sync.
+- `pivot` sets the point in local space that maps to `position` in parent space; changing it both moves and rotates the container.
+- `alpha` and `tint` multiply down through children. `blendMode` applies to this container's draw instructions.
+- `visible = false` skips rendering and transform updates. `renderable = false` skips rendering but still updates transforms (use when you need `getBounds()` or hit-testing without drawing).
+
+### zIndex and sortableChildren
+
+```ts
+const world = new Container({ sortableChildren: true });
+
+const ground = new Sprite(groundTexture);
+ground.zIndex = 0;
+
+const player = new Sprite(playerTexture);
+player.zIndex = 10;
+
+const ui = new Sprite(uiTexture);
+ui.zIndex = 100;
+
+world.addChild(ground, player, ui);
+```
+
+When `sortableChildren` is `true`, the container re-sorts its children by `zIndex` before the next render. Changing any child's `zIndex` automatically re-marks the parent as needing sort. Sort only what you need to sort; leaving `sortableChildren` off is cheaper. If you want full manual control, call `container.sortChildren()` yourself after changing `zIndex` values.
+
+For render-order control that is decoupled from the hierarchy (children keep their logical parent for transforms but render at a different z), use `RenderLayer`. See `pixijs-scene-core-concepts/references/scene-management.md`.
+
+### Bounds and coordinate conversion
+
+```ts
+const bounds = container.getBounds();
+console.log(bounds.x, bounds.y, bounds.width, bounds.height);
+
+const rect = container.getBounds().rectangle;
+
+const local = new Point(10, 20);
+const world = container.toGlobal(local);
+const backToLocal = container.toLocal(world);
+
+const selfPos = container.getGlobalPosition();
+```
+
+`getBounds()` returns a `Bounds` object (not a `Rectangle`); it exposes `x`, `y`, `width`, `height`, and a `.rectangle` getter for APIs that need an actual `Rectangle`. The signature is `getBounds(skipUpdate?: boolean, bounds?: Bounds)` — pass `true` as the first arg to skip the forced transform update, and an optional `Bounds` instance as the second arg to avoid allocating a new one.
+
+`toGlobal(point)` converts a point in this container's local space to scene-root space. `toLocal(point, from?)` converts from another container's local space (or global space if `from` is omitted). `getGlobalPosition()` is shorthand for `parent.toGlobal(this._position)`.
+
+### Sizing
+
+```ts
+const sprite = new Sprite(texture);
+
+sprite.setSize(200, 100);
+const { width, height } = sprite.getSize();
+```
+
+`setSize` adjusts `scale` so the container's bounds fit the requested pixel size, in one operation. Setting `.width` and `.height` individually works, but each assignment triggers a separate bounds recomputation; prefer `setSize` when changing both axes.
+
+### Container events
+
+```ts
+const parent = new Container();
+
+parent.on("childAdded", (child, container, index) => {
+  console.log("added at", index, child.label);
+});
+
+parent.on("childRemoved", (child, container, index) => {
+  console.log("removed from", index);
+});
+
+const child = new Container();
+child.on("added", (newParent) => console.log("entered", newParent.label));
+child.on("removed", (oldParent) => console.log("left", oldParent.label));
+child.on("visibleChanged", (visible) => console.log("visible:", visible));
+child.on("destroyed", (destroyed) => console.log("gone", destroyed.label));
+
+parent.addChild(child);
+```
+
+| Event            | Fires on                              | Arguments                   |
+| ---------------- | ------------------------------------- | --------------------------- |
+| `childAdded`     | the parent receiving the child        | `(child, container, index)` |
+| `childRemoved`   | the parent losing the child           | `(child, container, index)` |
+| `added`          | the child that was attached           | `(parent)`                  |
+| `removed`        | the child that was detached           | `(parent)`                  |
+| `destroyed`      | the destroyed container               | `(container)`               |
+| `visibleChanged` | the container whose `visible` flipped | `(visible)`                 |
+
+These are emitted on the `EventEmitter` side of `Container`; do not confuse them with pointer events from `pixijs-events`.
+
+`destroyed` fires after internal cleanup but before listeners are removed, so by the time your handler runs `position`, `scale`, `pivot`, `origin`, `skew`, and `parent` have already been nulled, and `children` has been emptied (length 0, but the array reference itself is not nulled). Capture any data you need from the container _before_ calling `destroy()`, not inside the handler.
+
+### Per-frame updates with onRender
+
+```ts
+const container = new Container();
+
+container.onRender = (renderer) => {
+  container.rotation += 0.01;
+};
+
+container.onRender = null;
+```
+
+`onRender` runs every frame while the container is being rendered, and receives the active `Renderer`. Use it for lightweight animation or per-frame updates tied to a specific container. In v7 this pattern was done by overriding `updateTransform`, which no longer runs every frame in v8. Set `onRender = null` to detach the callback.
+
+### Finding and removing from parent
+
+```ts
+const player = world.getChildByLabel("player");
+const enemies = world.getChildrenByLabel(/enemy-\d+/, true);
+
+const bounds = hud.getLocalBounds();
+
+oldSprite.removeFromParent();
+```
+
+- `getChildByLabel(label, deep?)` — first match by string or `RegExp`. Pass `true` for a recursive search.
+- `getChildrenByLabel(label, deep?, out?)` — all matches. Accepts an optional reusable output array.
+- `getLocalBounds()` — bounds in this container's own coordinate space, ignoring parent transforms. Cheaper than `getBounds()` for self-contained layout math.
+- `removeFromParent()` — detaches `this` from its current parent (no-op if already orphaned).
+
+### Destroy
+
+```ts
+container.destroy();
+
+container.destroy({
+  children: true,
+  texture: true,
+  textureSource: true,
+});
+
+console.log(container.destroyed);
+```
+
+By default `destroy()` unlinks this container from its parent and tears down its own state. Pass `{ children: true }` to recursively destroy every descendant; this is the usual call for killing a whole subtree. `texture: true` and `textureSource: true` additionally destroy the GPU resources referenced by leaf children (useful for sprites whose textures you loaded just for them). If `cacheAsTexture` is on, disable it with `container.cacheAsTexture(false)` before destroying.
+
+## Common Mistakes
+
+### [CRITICAL] Adding children to leaf scene objects
+
+Wrong:
+
+```ts
+const sprite = new Sprite(texture);
+const overlay = new Sprite(overlayTexture);
+sprite.addChild(overlay);
+```
+
+Correct:
+
+```ts
+const group = new Container();
+const sprite = new Sprite(texture);
+const overlay = new Sprite(overlayTexture);
+group.addChild(sprite, overlay);
+```
+
+Sprites, Graphics, Text, and Mesh are leaves. Adding children to them logs a deprecation warning now and will be an error in a future version. Always wrap them in a `Container` when you need grouping.
+
+### [HIGH] Expecting getBounds() to return a Rectangle
+
+Wrong:
+
+```ts
+const rect = container.getBounds();
+rect.contains(x, y); // TypeError: contains is not a function
+```
+
+Correct:
+
+```ts
+const rect = container.getBounds().rectangle;
+rect.contains(x, y);
+
+const bounds = container.getBounds();
+console.log(bounds.width, bounds.height);
+```
+
+`getBounds()` returns a `Bounds` instance in v8. Its basic getters (`x`, `y`, `width`, `height`) work, but for `Rectangle`-specific methods like `.contains()` or passing to APIs that require a `Rectangle`, read the `.rectangle` property.
+
+### [HIGH] Using cacheAsBitmap instead of cacheAsTexture
+
+Wrong:
+
+```ts
+container.cacheAsBitmap = true;
+```
+
+Correct:
+
+```ts
+container.cacheAsTexture(true);
+```
+
+`cacheAsBitmap` (v7 property) was renamed to `cacheAsTexture()` (a method) in v8. Always disable it with `cacheAsTexture(false)` before calling `destroy()`.
+
+### [MEDIUM] Using container.name instead of container.label
+
+`name` was renamed to `label` in v8. The old property still works as a deprecated alias; `getChildByLabel` is the v8 way to look up children by name.
+
+### [MEDIUM] Setting both pivot and origin on the same container
+
+Pivot shifts the projection of the local origin in parent space (moves the object as a side-effect of changing the rotation center). Origin changes the rotation/scale center without displacement. Setting both on the same container produces unexpected compounding; pick one.
+
+## API Reference
+
+- [Container](https://pixijs.download/release/docs/scene.Container.html.md)
+- [ContainerOptions](https://pixijs.download/release/docs/scene.ContainerOptions.html.md)
+- [ViewContainer](https://pixijs.download/release/docs/scene.ViewContainer.html.md)
+- [Bounds](https://pixijs.download/release/docs/rendering.Bounds.html.md)
+- [Point](https://pixijs.download/release/docs/maths.Point.html.md)
+- [ObservablePoint](https://pixijs.download/release/docs/maths.ObservablePoint.html.md)
+- [RenderGroup](https://pixijs.download/release/docs/rendering.RenderGroup.html.md)

package/vendor/pixijs-skills/skills/pixijs-scene-core-concepts/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: pixijs-scene-core-concepts
+description: "Use this skill when reasoning about the PixiJS v8 scene graph as a whole: how containers, leaves, transforms, and render order fit together. Covers leaf vs container distinction, local/world coordinates, culling, render groups, sortable children, masking, RenderLayer, constructor options shared by every scene node, and which leaf skill covers which display object. Triggers on: scene graph, display list, Container, Sprite, Graphics, Text, Mesh, ParticleContainer, DOMContainer, GifSprite, masking, render group, RenderLayer, world transform, constructor options, ContainerOptions."
+license: MIT
+---
+
+This skill is the shared mental model referenced by all `pixijs-scene-*` leaves. It explains what the scene graph is in PixiJS v8, how a `Container` differs from a leaf, and where each concept lives. It does not go deep on any single API; it frames the pieces and points to the skill or reference file that does.
+
+## Quick Start
+
+```ts
+const world = new Container({ isRenderGroup: true });
+app.stage.addChild(world);
+
+const hero = new Container({ label: "hero" });
+hero.addChild(new Sprite(bodyTexture));
+hero.addChild(new Sprite(faceTexture));
+world.addChild(hero);
+
+const mask = new Graphics().rect(0, 0, 800, 600).fill(0xffffff);
+world.mask = mask;
+world.addChild(mask);
+
+hero.position.set(world.width / 2, world.height / 2);
+```
+
+**Related skills:** `pixijs-scene-container` (Container API in detail), the leaf skills (`pixijs-scene-sprite`, `pixijs-scene-graphics`, `pixijs-scene-text`, `pixijs-scene-mesh`, `pixijs-scene-particle-container`, `pixijs-scene-dom-container`, `pixijs-scene-gif`), `pixijs-events` (hit testing traverses the scene graph), `pixijs-performance` (cache, culling, render groups), `pixijs-math` (Matrix, toGlobal/toLocal detail).
+
+## Core Concepts
+
+### What the scene graph is
+
+The PixiJS scene graph is a tree of display objects rooted at `app.stage`. Each node has a parent, a transform (position, scale, rotation, pivot, skew) relative to its parent, and optional visual state (alpha, tint, blendMode, visibility). Each frame the renderer walks the tree, composes transforms and visual state down to world-space, culls what's offscreen, and emits draw calls. The scene graph is both the layout model and the render order: earlier siblings draw behind later siblings.
+
+Every display object in v8 is a `Container` subclass. `DisplayObject` from earlier versions was removed.
+
+### Container vs leaf (CRITICAL)
+
+There are two roles in the tree:
+
+- **Containers**: nodes that hold children. Use a `Container` (or `RenderLayer`) for any node that groups, positions, or transforms other nodes.
+- **Leaves**: nodes that draw something and have no children. Use `Sprite`, `Graphics`, `Text`, `Mesh`, `ParticleContainer`'s `Particle`, `DOMContainer`, or `GifSprite` as leaves.
+
+In PixiJS v8, leaves must not have children. Adding children to a `Sprite` / `Graphics` / `Text` / `Mesh` logs a deprecation warning and is scheduled to become a hard error. The rule is: **use `Container` for any node that needs children; do not nest children inside leaf scene objects.** If you need to group a leaf with other leaves, wrap them in a `Container`.
+
+This distinction is why the `pixijs-scene-*` skills are split the way they are: `pixijs-scene-container` covers the grouping node, and each leaf gets its own skill focused on its draw behavior.
+
+### Transforms and coordinate spaces
+
+Every container composes a `localTransform` (a `Matrix`) from its `position`, `scale`, `rotation`, `pivot`, and `skew`. The renderer multiplies parents' local transforms together to produce the `worldTransform` (and `groupTransform` if a render group is in the chain), which maps local points to scene-root space. Use `toGlobal(point)` and `toLocal(point, from?)` to convert between spaces, and `getGlobalPosition()` for this object's world position. Full Matrix detail lives in `pixijs-math`; transform setters and `toLocal`/`toGlobal` live in `pixijs-scene-container`.
+
+### Render order and explicit z-ordering
+
+Children render in array order: index 0 first, last index last. For explicit z-ordering on a single container, set `sortableChildren = true` and assign `zIndex` values to children. For render order that is decoupled from the logical hierarchy (e.g., a character's parent is a game world but its drawing happens on a UI layer), use `RenderLayer`. Deep detail, including when to prefer sortable children vs RenderLayer, is in `references/scene-management.md`.
+
+### Render groups
+
+Flagging a container with `isRenderGroup: true` (or calling `container.enableRenderGroup()`) tells PixiJS to apply its transform on the GPU as a single matrix instead of recomputing every descendant's world transform on the CPU each frame. Use render groups on large, stable sub-trees such as worlds, UI layers, or parallax strips. Deep detail in `references/scene-management.md`.
+
+### Culling
+
+`cullable = true` + a `cullArea: Rectangle` tells the `CullerPlugin` (or any culling pass) to skip rendering objects that fall outside the visible area. `cullableChildren = false` short-circuits recursive culling for a sub-tree whose children are always on screen. Culling is a performance topic; `pixijs-performance` and `references/scene-management.md` cover the trade-offs.
+
+### Masking
+
+Set `container.mask` to another display object to clip its rendering. PixiJS picks the mask type automatically: a `Graphics` or `Container` mask uses a stencil buffer, a `Sprite` mask uses an alpha filter, and a number selects a `ColorMask`. All four mask types (AlphaMask, StencilMask, ScissorMask, ColorMask) are covered in `references/masking.md`.
+
+### Visibility, alpha, tint, and blend mode
+
+`visible = false` skips rendering and transform updates; `renderable = false` skips rendering but still updates transforms (use when hit-testing or bounds queries need to stay live). `alpha` and `tint` multiply down through the sub-tree; `blendMode` controls how this container's draw instructions composite against what is already on the target. See `pixijs-blend-modes` for the full blend-mode list and `pixijs-scene-container` for per-node state.
+
+### Destroy semantics
+
+`container.destroy()` unlinks one node. `container.destroy({ children: true })` recursively destroys the whole sub-tree; always use this for killing a branch. `texture: true` and `textureSource: true` additionally tear down GPU resources owned by leaves. If `cacheAsTexture` is on, disable it before destroying. `pixijs-scene-container` documents the full signature.
+
+### Lifecycle events
+
+Containers emit events for hierarchy and visibility changes: `childAdded` / `childRemoved` on the parent, `added` / `removed` on the child, plus `visibleChanged` and `destroyed` on the container itself. Useful for wiring reactive UI updates or resource bookkeeping. Full details in `references/container-hierarchy.md`.
+
+## Leaf comparison: which skill covers which object
+
+| Leaf                                                                 | Primary use                                                                                                                                                                 | Skill                             |
+| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| `Sprite`                                                             | Draw a single texture at a position (with variants `NineSliceSprite` for resizable UI panels and `TilingSprite` for repeating backgrounds).                                 | `pixijs-scene-sprite`             |
+| `Text` / `BitmapText` / `HTMLText` / `SplitText` / `SplitBitmapText` | Render text. Canvas-based `Text` for general use, `BitmapText` for high-volume cheap text, `HTMLText` for rich HTML/CSS layout, split variants for per-character animation. | `pixijs-scene-text`               |
+| `Graphics`                                                           | Vector drawing: shapes, lines, paths, fills, strokes. Backed by a `GraphicsContext`.                                                                                        | `pixijs-scene-graphics`           |
+| `Mesh` / `MeshSimple` / `MeshPlane` / `MeshRope` / `PerspectiveMesh` | Custom geometry with a shader or texture. Use `MeshRope` for textured path-following ribbons and `PerspectiveMesh` for 2D perspective.                                      | `pixijs-scene-mesh`               |
+| `ParticleContainer` + `Particle`                                     | Thousands of lightweight sprites with a restricted transform set, for high-throughput particle effects.                                                                     | `pixijs-scene-particle-container` |
+| `DOMContainer`                                                       | Render an HTML element positioned inside the scene graph (useful for inputs, iframes, accessibility overlays).                                                              | `pixijs-scene-dom-container`      |
+| `GifSprite`                                                          | Animated GIF playback as a display object. Requires `pixi.js/gif`.                                                                                                          | `pixijs-scene-gif`                |
+
+`Container` itself is covered in `pixijs-scene-container` and is the node every leaf lives inside.
+
+## When to use what (quick decisions)
+
+- "I want to group and transform some display objects" → `Container`, see `pixijs-scene-container`.
+- "I want to draw a texture" → `Sprite`, see `pixijs-scene-sprite`.
+- "I want to draw vector shapes or paths" → `Graphics`, see `pixijs-scene-graphics`.
+- "I want to draw text" → `Text` / `BitmapText` / `HTMLText`, see `pixijs-scene-text`.
+- "I want thousands of cheap sprites" → `ParticleContainer`, see `pixijs-scene-particle-container`.
+- "I want a custom-geometry mesh or a deformed sprite" → `Mesh` or one of its variants, see `pixijs-scene-mesh`.
+- "I want to clip a sub-tree" → set `.mask`, see `references/masking.md`.
+- "I want a decoupled render order" → `RenderLayer`, see `references/scene-management.md`.
+- "I want GPU-level transforms for a big stable sub-tree" → `isRenderGroup: true`, see `references/scene-management.md`.
+- "I want to skip offscreen rendering" → `cullable = true` + `CullerPlugin`, see `pixijs-performance`.
+
+## References
+
+- [references/constructor-options.md](references/constructor-options.md): the ~30 fields inherited by every `Container`-derived node (transform, display, hierarchy, sorting, layout, effects, callbacks), with defaults, types, and when line-by-line assignment is appropriate. Shared reference for all leaf skills.
+- [references/container-hierarchy.md](references/container-hierarchy.md): add/remove/swap children, reparenting with transform preservation, label navigation, destroy sub-trees.
+- [references/transforms.md](references/transforms.md): position, scale, rotation, pivot, origin, skew, toGlobal/toLocal, the three matrices (local/group/world), bounds.
+- [references/masking.md](references/masking.md): AlphaMask, StencilMask, ScissorMask, ColorMask, inverse masking, cost comparison.
+- [references/layers.md](references/layers.md): `RenderLayer`, attach/detach, sorted layers, layer + logical parent split.
+- [references/render-groups.md](references/render-groups.md): `isRenderGroup`, GPU-level transforms, when to use, render-groups vs `cacheAsTexture`.
+- [references/scene-management.md](references/scene-management.md): combined view; render groups, `RenderLayer`, culling, zIndex sorting, `boundsArea`.
+
+## Common Mistakes
+
+### [CRITICAL] Adding children to a leaf display object
+
+Wrong:
+
+```ts
+const sprite = new Sprite(texture);
+sprite.addChild(new Graphics().rect(0, 0, 10, 10).fill(0xff0000));
+```
+
+Correct:
+
+```ts
+const group = new Container();
+group.addChild(new Sprite(texture));
+group.addChild(new Graphics().rect(0, 0, 10, 10).fill(0xff0000));
+```
+
+In v8 leaves (`Sprite`, `Graphics`, `Text`, `Mesh`, `ParticleContainer`, `DOMContainer`, `GifSprite`) technically extend `Container` but should not hold children. Adding children to a leaf produces undefined rendering behavior. Wrap the leaf in a `Container` when you need grouping.
+
+### [CRITICAL] Referencing DisplayObject
+
+Wrong:
+
+```ts
+import { DisplayObject } from "pixi.js"; // no such export in v8
+function moveNode(node: DisplayObject) {
+  node.x += 1;
+}
+```
+
+Correct:
+
+```ts
+import { Container } from "pixi.js";
+function moveNode(node: Container) {
+  node.x += 1;
+}
+```
+
+`DisplayObject` was removed in v8. Every display object — including `Sprite`, `Graphics`, `Text`, `Mesh` — is a `Container` subclass now. Use `Container` as the base type.
+
+### [HIGH] Forgetting isRenderGroup on large static subtrees
+
+Wrong:
+
+```ts
+const world = new Container();
+for (let i = 0; i < 5000; i++) {
+  world.addChild(new Sprite(texture));
+}
+app.stage.addChild(world);
+```
+
+Correct:
+
+```ts
+const world = new Container({ isRenderGroup: true });
+for (let i = 0; i < 5000; i++) {
+  world.addChild(new Sprite(texture));
+}
+app.stage.addChild(world);
+```
+
+Without `isRenderGroup: true`, the renderer recomposes every child's transform against its parents every frame. Marking the subtree as a render group caches transforms and draw state until a child changes, which is essential for large or mostly-static trees.
+
+### [HIGH] Treating child.x as world space
+
+Wrong:
+
+```ts
+const enemy = new Container();
+enemy.x = 500;
+world.addChild(enemy);
+world.x = 200;
+console.log(enemy.x); // 500 (local), not 700 (world)
+```
+
+Correct:
+
+```ts
+const worldPos = enemy.toGlobal({ x: 0, y: 0 });
+console.log(worldPos.x); // 700
+```
+
+`Container.x/y/scale/rotation` are LOCAL to the parent. Use `toGlobal(point)` to compute world-space coordinates, or `getGlobalPosition()` for the container's origin in world space. The world transform is not exposed as a simple `x/y` pair.
+
+### [MEDIUM] sortableChildren without zIndex
+
+Wrong:
+
+```ts
+const layer = new Container();
+layer.sortableChildren = true;
+layer.addChild(bg); // no zIndex
+layer.addChild(mid); // no zIndex
+layer.addChild(fg); // no zIndex
+// order is unchanged — all zIndex default to 0
+```
+
+Correct:
+
+```ts
+const layer = new Container();
+layer.sortableChildren = true;
+bg.zIndex = 0;
+mid.zIndex = 10;
+fg.zIndex = 20;
+layer.addChild(bg, mid, fg);
+```
+
+`sortableChildren` re-sorts children by `zIndex` before rendering, but only takes effect when children actually have distinct `zIndex` values. Setting only the parent flag has no visible effect.
+
+## Tooling
+
+The [PixiJS Devtools Chrome extension](https://chromewebstore.google.com/detail/pixijs-devtools/aamddddknhcagpehecnhphigffljadon) lets you inspect and manipulate a running scene graph in real time. Install it for any non-trivial layout or render-order debugging.
+
+## API Reference
+
+- [Container](https://pixijs.download/release/docs/scene.Container.html.md)
+- [ViewContainer](https://pixijs.download/release/docs/scene.ViewContainer.html.md)
+- [RenderLayer](https://pixijs.download/release/docs/scene.RenderLayer.html.md)
+- [RenderGroup](https://pixijs.download/release/docs/rendering.RenderGroup.html.md)
+- [Bounds](https://pixijs.download/release/docs/rendering.Bounds.html.md)
+- [Culler](https://pixijs.download/release/docs/scene.Culler.html.md)
+- [CullerPlugin](https://pixijs.download/release/docs/app.CullerPlugin.html.md)