@docyrus/animaguru 0.6.0

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

@@ -0,0 +1,120 @@
+---
+name: pixijs-scene-sprite
+description: "Use this skill when drawing images in PixiJS v8. Covers Sprite with anchor/tint/texture, AnimatedSprite for frame animation, NineSliceSprite for resizable UI panels, TilingSprite for scrolling/repeating backgrounds. Triggers on: Sprite, AnimatedSprite, NineSliceSprite, TilingSprite, Sprite.from, anchor, tint, tilePosition, animationSpeed, gotoAndPlay, leftWidth, topHeight, constructor options, SpriteOptions, AnimatedSpriteOptions, NineSliceSpriteOptions, TilingSpriteOptions."
+license: MIT
+---
+
+PixiJS has three sprite classes for different drawing tasks. `Sprite` is the default image-drawing leaf; `NineSliceSprite` is a resizable UI-panel variant that preserves corner art; `TilingSprite` repeats a texture across an area. The `AnimatedSprite` subclass of `Sprite` cycles through texture frames for frame-based animation.
+
+Assumes familiarity with `pixijs-scene-core-concepts`. All sprite classes are leaf nodes; they cannot have children. Wrap multiple sprites in a `Container` to group them.
+
+## Quick Start
+
+```ts
+const texture = await Assets.load("bunny.png");
+
+const sprite = new Sprite({
+  texture,
+  anchor: 0.5,
+  tint: 0xff8888,
+});
+sprite.x = app.screen.width / 2;
+sprite.y = app.screen.height / 2;
+
+app.stage.addChild(sprite);
+```
+
+Position is set after construction because `app.screen.width / 2` depends on the live renderer size. Literal positions can go directly in the options object via `x`/`y` (inherited from `Container`).
+
+**Related skills:** `pixijs-scene-core-concepts` (leaves, transforms), `pixijs-assets` (texture loading), `pixijs-scene-particle-container` (thousands of sprites), `pixijs-performance` (spritesheets, batching).
+
+## Variants
+
+| Variant           | Use when                                                  | Trade-offs                                      | Reference                                                        |
+| ----------------- | --------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------- |
+| `Sprite`          | Draw a single texture at a position                       | Fixed size = texture size                       | [references/sprite.md](references/sprite.md)                     |
+| `AnimatedSprite`  | Frame-based animation from a texture array or spritesheet | Pre-rendered frames only; no tweening           | [references/animated-sprite.md](references/animated-sprite.md)   |
+| `NineSliceSprite` | Resizable UI panels, buttons, dialog frames               | Border width is fixed; center stretches         | [references/nineslice-sprite.md](references/nineslice-sprite.md) |
+| `TilingSprite`    | Scrolling backgrounds, parallax, repeating patterns       | Single texture repeated; `tilePosition` scrolls | [references/tiling-sprite.md](references/tiling-sprite.md)       |
+
+`AnimatedSprite` is a subclass of `Sprite`; all `Sprite` properties (anchor, tint, position) apply.
+
+Each variant's constructor options are documented in its sub-reference file (`references/{variant}.md`). All variants also accept the `Container` options (`position`, `scale`, `tint`, `label`, `filters`, `zIndex`, etc.) — see `skills/pixijs-scene-core-concepts/references/constructor-options.md`.
+
+## When to use what
+
+- **"I want to draw a single image at a position"** → `Sprite`. The default choice for 90% of 2D game and app content.
+- **"I want to animate a character through a series of frames"** → `AnimatedSprite`. Load a spritesheet via Assets and pass `sheet.animations['walk']`. See `references/animated-sprite.md`.
+- **"I want a UI button/panel that resizes without stretching the borders"** → `NineSliceSprite`. Set border widths, then set `width`/`height`. See `references/nineslice-sprite.md`.
+- **"I want a scrolling repeating background"** → `TilingSprite`. Animate `tilePosition` to scroll. See `references/tiling-sprite.md`.
+- **"I want thousands of identical sprites"** → Use `ParticleContainer` with `Particle` instances (see `pixijs-scene-particle-container`), not plain sprites.
+- **"I want to draw shapes or paths"** → Use `Graphics` (see `pixijs-scene-graphics`), not a sprite.
+
+## Quick concepts
+
+### Anchor vs pivot
+
+`Sprite.anchor` is normalized `[0, 1]` and shifts only the texture draw origin; no position offset. `Container.pivot` is pixel-space and shifts both the transform origin and the visual position. For centering a sprite, always use `anchor.set(0.5)`.
+
+### Loading before creating
+
+`Sprite.from(id)` only reads the Assets cache; it does not fetch. Always `await Assets.load(...)` first, or pass the returned `Texture` directly to `new Sprite(texture)`.
+
+### Dynamic textures
+
+Once a texture is loaded, modifying its `frame` or swapping its source does not automatically notify sprites. Set `texture.dynamic = true` once, or call `sprite['onViewUpdate']()` manually after changes.
+
+## Common Mistakes
+
+### [HIGH] Using `Texture.from(url)` to load
+
+Wrong:
+
+```ts
+const texture = Texture.from("https://example.com/image.png");
+```
+
+Correct:
+
+```ts
+const texture = await Assets.load("https://example.com/image.png");
+```
+
+`Texture.from()` only reads the cache in v8. Use `Assets.load()` first; its return value is the texture.
+
+
+### [HIGH] Confusing anchor and pivot
+
+Wrong:
+
+```ts
+sprite.pivot.set(sprite.width / 2, sprite.height / 2);
+```
+
+Correct:
+
+```ts
+sprite.anchor.set(0.5);
+```
+
+`anchor` shifts only the draw origin. `pivot` shifts the transform origin AND the visual position, causing the sprite to move unexpectedly.
+
+
+### [HIGH] Old `NineSlicePlane` name
+
+`NineSlicePlane` was renamed to `NineSliceSprite` in v8 and switched to an options-object constructor: `new NineSliceSprite({ texture, leftWidth, topHeight, rightWidth, bottomHeight })`.
+
+
+### [MEDIUM] Adding children to a sprite
+
+`Sprite`, `NineSliceSprite`, and `TilingSprite` all set `allowChildren = false`. Wrap in a `Container` to group sprites with other content.
+
+
+## API Reference
+
+- [Sprite](https://pixijs.download/release/docs/scene.Sprite.html.md)
+- [SpriteOptions](https://pixijs.download/release/docs/scene.SpriteOptions.html.md)
+- [AnimatedSprite](https://pixijs.download/release/docs/scene.AnimatedSprite.html.md)
+- [NineSliceSprite](https://pixijs.download/release/docs/scene.NineSliceSprite.html.md)
+- [TilingSprite](https://pixijs.download/release/docs/scene.TilingSprite.html.md)
+- [Texture](https://pixijs.download/release/docs/rendering.Texture.html.md)

package/vendor/pixijs-skills/skills/pixijs-scene-sprite/references/animated-sprite.md

@@ -0,0 +1,262 @@
+# AnimatedSprite
+
+A `Sprite` subclass that cycles through an array of textures for frame-based animation. Use for character walk cycles, explosions, UI icon loops, or any sequence driven by pre-rendered frames from a spritesheet.
+
+## Quick Start
+
+```ts
+const sheet = await Assets.load("character.json");
+
+const walk = new AnimatedSprite({
+  textures: sheet.animations["walk"],
+  animationSpeed: 0.15,
+  loop: true,
+  autoPlay: true,
+});
+
+app.stage.addChild(walk);
+```
+
+`AnimatedSprite` extends `Sprite`, so anchor, tint, position, and scale all work the same way. It adds frame playback on top. Inherits `allowChildren = false` from `Sprite`.
+
+## Core Patterns
+
+### Construction
+
+```ts
+new AnimatedSprite(frames, autoUpdate?);
+new AnimatedSprite({ textures, autoUpdate, autoPlay, loop, animationSpeed });
+```
+
+Two constructor forms are supported. The options form accepts all `SpriteOptions` (anchor, tint, position, etc.) plus the animation-specific fields below. The positional form takes a frames array and an optional `autoUpdate` flag.
+
+```ts
+const sheet = await Assets.load("character.json");
+
+const walk = new AnimatedSprite({
+  textures: sheet.animations["walk"],
+  animationSpeed: 0.2,
+  loop: true,
+  autoPlay: true,
+  anchor: 0.5,
+  x: 200,
+  y: 300,
+});
+```
+
+#### AnimatedSpriteOptions
+
+| Option           | Type                             | Default | Description                                                                                                       |
+| ---------------- | -------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
+| `textures`       | `AnimatedSpriteFrames`           | —       | Frame list: a `Texture[]` or `FrameObject[]` (each `{ texture, time }` with `time` in ms). Required.              |
+| `animationSpeed` | `number`                         | `1`     | Playback multiplier; negative values reverse direction.                                                           |
+| `autoPlay`       | `boolean`                        | `false` | Start playback immediately on construction.                                                                       |
+| `autoUpdate`     | `boolean`                        | `true`  | Drive playback from `Ticker.shared`; set `false` to call `update(ticker)` manually.                               |
+| `loop`           | `boolean`                        | `true`  | Restart after the last frame; set `false` for one-shot animations.                                                |
+| `onComplete`     | `() => void`                     | `null`  | Fires when a non-looping animation reaches its end.                                                               |
+| `onFrameChange`  | `(currentFrame: number) => void` | `null`  | Fires every time the displayed texture changes.                                                                   |
+| `onLoop`         | `() => void`                     | `null`  | Fires when a looping animation wraps back to the start.                                                           |
+| `updateAnchor`   | `boolean`                        | `false` | Copy `texture.defaultAnchor` onto the sprite's anchor on every frame change. Overrides any previously set anchor. |
+
+Also inherits `SpriteOptions` minus `texture` (use `textures` for frames) — see `sprite.md`. All `Container` options (`position`, `scale`, `tint`, `label`, `filters`, `zIndex`, etc.) are also valid here — see `skills/pixijs-scene-core-concepts/references/constructor-options.md`.
+
+### Playback control
+
+```ts
+walk.play();
+walk.stop();
+walk.gotoAndStop(3);
+walk.gotoAndPlay(0);
+
+walk.currentFrame = 2;
+console.log(walk.totalFrames);
+console.log(walk.playing);
+```
+
+- `play()` / `stop()`: start or freeze playback at the current frame.
+- `gotoAndStop(frame)` / `gotoAndPlay(frame)`: jump to a specific frame index.
+- `currentFrame`: readable and writable. The setter throws if the value is outside `[0, totalFrames - 1]`.
+- `totalFrames` (readonly): number of frames in the current texture list.
+- `playing` (readonly): current playback state.
+
+### Speed and looping
+
+```ts
+walk.animationSpeed = 0.15;
+walk.animationSpeed = -1;
+walk.loop = false;
+```
+
+- `animationSpeed` (default `1`): playback multiplier. Negative reverses direction.
+- `loop` (default `true`): restart after last frame. Set to `false` and use `onComplete` for one-shot animations.
+
+### Callbacks
+
+```ts
+walk.onComplete = () => console.log("animation done");
+walk.onFrameChange = (frame) => console.log(`now on frame ${frame}`);
+walk.onLoop = () => console.log("looped back to start");
+```
+
+- `onComplete`: fires when a non-looping animation reaches its end.
+- `onFrameChange(frameIndex)`: fires every time the displayed texture changes.
+- `onLoop`: fires when a looping animation wraps around to the start.
+
+### Auto update
+
+```ts
+const walk = new AnimatedSprite({
+  textures: sheet.animations["walk"],
+  autoUpdate: false,
+});
+
+app.ticker.add((ticker) => {
+  walk.update(ticker);
+});
+```
+
+`autoUpdate` (default `true`): uses `Ticker.shared`. Set `false` and call `update(ticker)` manually to drive playback from a custom ticker or pause it with game logic.
+
+### Per-frame timing
+
+```ts
+const explosion = new AnimatedSprite({
+  textures: [
+    { texture: frame0, time: 100 },
+    { texture: frame1, time: 200 },
+    { texture: frame2, time: 300 },
+  ],
+});
+```
+
+`FrameObject` entries use `{ texture, time }` where `time` is in **milliseconds**, not seconds. Mix per-frame timing for effects that linger on key frames (impact, reveal, pause).
+
+Spritesheets loaded via `Assets.load` expose per-frame `duration` values at `sheet.data.frames[key].duration`. Build a `FrameObject[]` from those durations when you need pre-authored timing:
+
+```ts
+const sheet = await Assets.load("0123456789.json");
+const frames = [];
+for (let i = 0; i < 10; i++) {
+  const key = `0123456789 ${i}.ase`;
+  frames.push({
+    texture: Texture.from(key),
+    time: sheet.data.frames[key].duration,
+  });
+}
+const sprite = new AnimatedSprite(frames);
+```
+
+### Factories
+
+```ts
+const walk = AnimatedSprite.fromFrames(["walk0.png", "walk1.png", "walk2.png"]);
+const idle = AnimatedSprite.fromImages(["idle0.png", "idle1.png"]);
+```
+
+- `fromFrames(aliases)`: builds textures via `Texture.from` from Assets cache aliases. Requires the spritesheet to already be loaded.
+- `fromImages(urls)`: builds textures from URLs. Does not await loading; textures resolve asynchronously.
+
+Prefer `new AnimatedSprite({ textures: sheet.animations[...] })` after `await Assets.load(...)` for deterministic loading.
+
+### updateAnchor
+
+```ts
+const walk = new AnimatedSprite({
+  textures: sheet.animations["walk"],
+  updateAnchor: true,
+});
+```
+
+`updateAnchor` (default `false`): when `true`, the sprite's anchor is copied from the current texture's `defaultAnchor` on every frame change. Useful when exporting frames with per-frame pivot points (e.g., to pin the animation to a moving foot or hand). Overrides any previously set anchor on each frame change.
+
+## Common Mistakes
+
+### [HIGH] Using `Texture.from` on unloaded frames
+
+Wrong:
+
+```ts
+const walk = new AnimatedSprite([
+  Texture.from("walk0.png"),
+  Texture.from("walk1.png"),
+]);
+```
+
+Correct:
+
+```ts
+const sheet = await Assets.load("character.json");
+const walk = new AnimatedSprite(sheet.animations["walk"]);
+```
+
+`Texture.from()` only reads the cache in v8. If the spritesheet has not been loaded, the textures resolve to `Texture.EMPTY` and the sprite shows nothing. Always `await Assets.load()` the spritesheet first, then use `sheet.animations[key]`.
+
+
+### [HIGH] Forgetting to call `play()` or set `autoPlay`
+
+Wrong:
+
+```ts
+const walk = new AnimatedSprite({ textures: sheet.animations["walk"] });
+app.stage.addChild(walk);
+```
+
+Correct:
+
+```ts
+const walk = new AnimatedSprite({
+  textures: sheet.animations["walk"],
+  autoPlay: true,
+});
+app.stage.addChild(walk);
+```
+
+`autoPlay` defaults to `false`. Without `autoPlay: true` or a manual `walk.play()` call, the sprite displays only the first frame.
+
+
+### [MEDIUM] Using seconds instead of milliseconds for `FrameObject.time`
+
+Wrong:
+
+```ts
+new AnimatedSprite([
+  { texture: frame0, time: 0.1 },
+  { texture: frame1, time: 0.2 },
+]);
+```
+
+Correct:
+
+```ts
+new AnimatedSprite([
+  { texture: frame0, time: 100 },
+  { texture: frame1, time: 200 },
+]);
+```
+
+`FrameObject.time` is in milliseconds. A value of `0.1` will advance frames almost instantly.
+
+
+### [MEDIUM] Setting `currentFrame` out of range
+
+Wrong:
+
+```ts
+walk.currentFrame = walk.totalFrames;
+```
+
+Correct:
+
+```ts
+walk.currentFrame = walk.totalFrames - 1;
+```
+
+The setter throws if the value is outside `[0, totalFrames - 1]`. Use `totalFrames - 1` for the last frame.
+
+
+## API Reference
+
+- [AnimatedSprite](https://pixijs.download/release/docs/scene.AnimatedSprite.html.md)
+- [AnimatedSpriteOptions](https://pixijs.download/release/docs/scene.AnimatedSpriteOptions.html.md)
+- [FrameObject](https://pixijs.download/release/docs/scene.FrameObject.html.md)
+- [Spritesheet](https://pixijs.download/release/docs/assets.Spritesheet.html.md)

package/vendor/pixijs-skills/skills/pixijs-scene-sprite/references/nineslice-sprite.md

@@ -0,0 +1,202 @@
+# NineSliceSprite
+
+A sprite variant that stretches a texture using 9-slice scaling. The four corner regions stay unscaled, the top and bottom edges stretch horizontally, the left and right edges stretch vertically, and the center stretches both ways. Use this for resizable UI panels, buttons, and dialog frames where you want the border art to remain crisp at any size.
+
+## Quick Start
+
+```ts
+const texture = await Assets.load("panel.png");
+
+const panel = new NineSliceSprite({
+  texture,
+  leftWidth: 20,
+  topHeight: 20,
+  rightWidth: 20,
+  bottomHeight: 20,
+  width: 400,
+  height: 200,
+});
+
+app.stage.addChild(panel);
+```
+
+All four border values default to `10`. Assign `width` / `height` on the sprite (not the texture) to control the stretch region.
+
+## Construction
+
+```ts
+const panel = new NineSliceSprite({
+  texture,
+  leftWidth: 20,
+  topHeight: 20,
+  rightWidth: 20,
+  bottomHeight: 20,
+  width: 400,
+  height: 200,
+  anchor: 0.5,
+});
+```
+
+### NineSliceSpriteOptions
+
+| Option         | Type                  | Default                       | Description                                                        |
+| -------------- | --------------------- | ----------------------------- | ------------------------------------------------------------------ |
+| `texture`      | `Texture`             | `Texture.EMPTY`               | Source texture for the 9-slice.                                    |
+| `leftWidth`    | `number`              | `10`                          | Width of the left border column that stays unscaled.               |
+| `topHeight`    | `number`              | `10`                          | Height of the top border row that stays unscaled.                  |
+| `rightWidth`   | `number`              | `10`                          | Width of the right border column that stays unscaled.              |
+| `bottomHeight` | `number`              | `10`                          | Height of the bottom border row that stays unscaled.               |
+| `width`        | `number`              | `texture.width` (else `100`)  | Width of the stretched sprite region; modifies vertices, not UVs.  |
+| `height`       | `number`              | `texture.height` (else `100`) | Height of the stretched sprite region; modifies vertices, not UVs. |
+| `anchor`       | `PointData \| number` | `0`                           | Normalized draw origin in `[0, 1]`.                                |
+| `roundPixels`  | `boolean`             | `false`                       | Snap rendering coordinates to integers for crisp pixel art.        |
+
+All `Container` options (`position`, `scale`, `tint`, `label`, `filters`, `zIndex`, etc.) are also valid here — see `skills/pixijs-scene-core-concepts/references/constructor-options.md`.
+
+Border values fall back to `texture.defaultBorders` if set on the texture; see the Texture-defined borders section below.
+
+## Core Patterns
+
+### The 9-slice grid
+
+```
+         leftWidth                rightWidth
+    +---+--------------------+---+
+    | 1 |         2          | 3 |   topHeight
+    +---+--------------------+---+
+    |   |                    |   |
+    | 4 |         5          | 6 |
+    |   |                    |   |
+    +---+--------------------+---+
+    | 7 |         8          | 9 |   bottomHeight
+    +---+--------------------+---+
+```
+
+- Corners (1, 3, 7, 9): unscaled
+- Top and bottom edges (2, 8): stretched horizontally
+- Left and right edges (4, 6): stretched vertically
+- Center (5): stretched both ways
+
+### Runtime resize
+
+```ts
+panel.width = 600;
+panel.height = 300;
+
+panel.setSize(600, 300);
+const size = panel.getSize();
+```
+
+Setting `width` / `height` modifies the sprite's vertices directly. It does not scale the underlying texture. The corners stay fixed-size regardless of how small or large you make the panel. `setSize(value, height?)` and `getSize(out?)` are the override pair used to avoid recomputing bounds twice when both axes change.
+
+### Texture-defined borders
+
+```ts
+const texture = new Texture({
+  source: baseSource,
+  defaultBorders: { left: 15, top: 15, right: 15, bottom: 15 },
+});
+
+const panel = new NineSliceSprite({ texture, width: 400, height: 200 });
+```
+
+`defaultBorders` is a readonly Texture property. Pass it in the constructor options (or set it on the spritesheet data so `Assets.load` bakes it into the loaded texture). If the texture has borders set, the sprite picks them up automatically when no explicit border values are passed to the `NineSliceSprite` constructor. Define them once per texture and reuse across multiple panels.
+
+
+### Border updates
+
+```ts
+panel.leftWidth = 25;
+panel.rightWidth = 25;
+panel.topHeight = 15;
+panel.bottomHeight = 15;
+```
+
+All four border values are mutable at runtime. The sprite rebuilds its geometry on the next render.
+
+### Source texture dimensions
+
+```ts
+console.log(panel.originalWidth, panel.originalHeight);
+panel.setSize(panel.originalWidth, panel.originalHeight);
+```
+
+`originalWidth` and `originalHeight` are readonly getters that return the underlying `texture.width` / `texture.height`. Use them to reset a panel to its source size or to compute scaled sizes relative to the unstretched texture.
+
+### Global defaults
+
+```ts
+NineSliceSprite.defaultOptions.texture = Texture.from("defaultPanel.png");
+```
+
+`NineSliceSprite.defaultOptions` is a mutable static object, but only its `texture` field is read as a fallback. Border defaults come from `texture.defaultBorders` (per-texture) or `NineSliceGeometry.defaultOptions` (global), and size defaults fall back to `texture.width` / `texture.height` or `NineSliceGeometry.defaultOptions.width` / `.height`.
+
+### Round pixels for crisp borders
+
+```ts
+const panel = new NineSliceSprite({
+  texture,
+  leftWidth: 10,
+  topHeight: 10,
+  rightWidth: 10,
+  bottomHeight: 10,
+  roundPixels: true,
+});
+```
+
+Use with pixel-art UI textures to avoid sub-pixel seams at the slice boundaries.
+
+## Common Mistakes
+
+### [HIGH] Using the old `NineSlicePlane` name
+
+Wrong:
+
+```ts
+import { NineSlicePlane } from "pixi.js";
+const panel = new NineSlicePlane(texture, 10, 10, 10, 10);
+```
+
+Correct:
+
+```ts
+import { NineSliceSprite } from "pixi.js";
+const panel = new NineSliceSprite({
+  texture,
+  leftWidth: 10,
+  topHeight: 10,
+  rightWidth: 10,
+  bottomHeight: 10,
+});
+```
+
+`NineSlicePlane` was renamed in v8 and switched to an options-object constructor. The old `NineSlicePlane` name is deprecated — use `NineSliceSprite` instead.
+
+
+### [HIGH] Setting `texture.scale` to resize the panel
+
+Wrong:
+
+```ts
+panel.scale.set(2);
+```
+
+Correct:
+
+```ts
+panel.width = 400;
+panel.height = 200;
+```
+
+`scale` stretches the entire geometry including corners, defeating the purpose of 9-slice. Always use `width` / `height` to resize a `NineSliceSprite`; this preserves corner art.
+
+
+### [MEDIUM] Borders larger than half the texture
+
+If `leftWidth + rightWidth >= texture.width` (or `topHeight + bottomHeight >= texture.height`), no texture pixels are left for the center strip, so it is filled by stretching the seam between the two borders instead of the texture's middle. Keep the sum of opposing borders less than the corresponding texture dimension.
+
+
+## API Reference
+
+- [NineSliceSprite](https://pixijs.download/release/docs/scene.NineSliceSprite.html.md)
+- [NineSliceGeometry](https://pixijs.download/release/docs/scene.NineSliceGeometry.html.md)