@docyrus/animaguru 0.6.0

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

@@ -0,0 +1,181 @@
+# Sprite
+
+The core image-drawing leaf. Displays a single `Texture` at a transform. Use `Sprite` whenever you want to draw a static image that isn't animated (`AnimatedSprite`), repeating (`TilingSprite`), or resizable with borders (`NineSliceSprite`).
+
+## 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);
+```
+
+`Sprite` is a leaf; `allowChildren` is `false`. Wrap sprites in a `Container` if you need to group or nest them.
+
+Position is set after construction because `app.screen.width / 2` depends on the live renderer; literal positions can go directly in the options as `x`/`y`.
+
+## Core Patterns
+
+### Construction
+
+```ts
+const fromTexture = new Sprite(texture);
+
+const fromCache = Sprite.from("bunny.png");
+
+const fromCanvasNoCache = Sprite.from(canvas, true);
+
+const withOptions = new Sprite({
+  texture,
+  anchor: 0.5,
+  x: 100,
+  y: 200,
+  tint: 0xffcc00,
+  alpha: 0.8,
+  roundPixels: true,
+});
+```
+
+#### SpriteOptions
+
+| Option        | Type                  | Default         | Description                                                                           |
+| ------------- | --------------------- | --------------- | ------------------------------------------------------------------------------------- |
+| `texture`     | `Texture`             | `Texture.EMPTY` | Texture to draw.                                                                      |
+| `anchor`      | `PointData \| number` | `0`             | Normalized draw origin in `[0, 1]`; falls back to `texture.defaultAnchor` when unset. |
+| `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`.
+
+`Sprite.from(source, skipCache?)` accepts a `Texture` or a `TextureSourceLike` (canvas, video, URL). With a cached alias it only reads the cache and returns `Texture.EMPTY` if the texture was not loaded first; always `await Assets.load(...)` for images. The optional second `skipCache` argument forwards to `Texture.from` to avoid storing ephemeral textures in the global cache.
+
+Video and canvas elements work as texture sources too. Load a video file via `await Assets.load('clip.mp4')` and pass the returned texture to `new Sprite(texture)`; on mobile platforms, start playback from a user gesture to satisfy autoplay policies.
+
+### Sizing helpers
+
+```ts
+sprite.setSize(200); // square: both axes
+sprite.setSize(200, 120); // width and height
+sprite.setSize({ width: 200, height: 120 });
+
+const size = sprite.getSize(); // { width, height }
+const reused = { width: 0, height: 0 };
+sprite.getSize(reused); // write into an existing object
+```
+
+`setSize` avoids the double bounds recalculation of setting `width` and `height` separately. `getSize(out?)` returns the current drawn size and optionally writes into a passed object.
+
+### Visual vs source bounds
+
+```ts
+const drawn = sprite.visualBounds; // minX, maxX, minY, maxY of the drawn region (anchor-aware)
+```
+
+`sprite.visualBounds` is the rectangle the sprite actually draws in local space, accounting for anchor and texture trim. It differs from `getLocalBounds()` when the texture has padding/trim or a non-zero anchor.
+
+### Anchor
+
+```ts
+sprite.anchor.set(0.5); // center both axes
+sprite.anchor.set(0, 0); // top-left (default)
+sprite.anchor.set(1, 0); // top-right
+sprite.anchor = { x: 0.5, y: 1 }; // bottom-center
+```
+
+`anchor` is normalized `[0, 1]` relative to the texture dimensions. It shifts where the texture draws relative to the sprite's `(x, y)` without offsetting the sprite's position. If omitted, falls back to `texture.defaultAnchor`. Anchor is Sprite-only; it differs from `pivot` (inherited from `Container`, in pixel space); pivot shifts both transform origin and visual position.
+
+### Tint and alpha
+
+```ts
+sprite.tint = 0xff0000; // multiply against the texture colors
+sprite.alpha = 0.5; // parent-combined transparency
+```
+
+`tint` multiplies pixel values; white (`0xffffff`) is a no-op. `alpha` is combined with ancestor alpha up the tree.
+
+### Round pixels
+
+```ts
+const sprite = new Sprite({ texture, roundPixels: true });
+```
+
+Snaps rendering coordinates to integers for crisp pixel-art. Apply per-sprite, or globally via `TextureStyle.defaultOptions.scaleMode = 'nearest'` + `roundPixels: true` on the renderer.
+
+### Dynamic textures
+
+```ts
+texture.dynamic = true;
+texture.frame.width /= 2;
+texture.update();
+```
+
+v8 removed event-based change notification. Set `texture.dynamic = true` once, then normal `texture.update()` calls propagate to all sprites that reference it. Without `dynamic`, you must call `sprite['onViewUpdate']()` manually after mutating the texture.
+
+## Common Mistakes
+
+### [HIGH] Using `Texture.from(url)` to load
+
+Wrong:
+
+```ts
+const texture = Texture.from("https://example.com/image.png");
+const sprite = new Sprite(texture);
+```
+
+Correct:
+
+```ts
+const texture = await Assets.load("https://example.com/image.png");
+const sprite = new Sprite(texture);
+```
+
+In v8, `Texture.from()` only retrieves from the cache. It does not fetch. Use `Assets.load()` first; its return value is the texture, so you don't need a separate `Texture.from()` call.
+
+
+### [HIGH] Confusing anchor with pivot
+
+Wrong:
+
+```ts
+sprite.pivot.set(sprite.width / 2, sprite.height / 2);
+```
+
+Correct:
+
+```ts
+sprite.anchor.set(0.5);
+```
+
+`anchor` is normalized `[0, 1]` and shifts where the texture draws without offsetting position. `pivot` is in pixel space and offsets both the transform origin and the rendered position. For centering a sprite, always use `anchor`.
+
+
+### [MEDIUM] Adding children to a Sprite
+
+Wrong:
+
+```ts
+sprite.addChild(childSprite);
+```
+
+Correct:
+
+```ts
+const group = new Container();
+group.addChild(sprite, childSprite);
+```
+
+`Sprite` sets `allowChildren = false`. Adding children logs a deprecation warning and will become a hard error. Group leaves inside a `Container`.
+
+
+## API Reference
+
+- [Sprite](https://pixijs.download/release/docs/scene.Sprite.html.md)
+- [SpriteOptions](https://pixijs.download/release/docs/scene.SpriteOptions.html.md)
+- [Texture](https://pixijs.download/release/docs/rendering.Texture.html.md)

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

@@ -0,0 +1,216 @@
+# TilingSprite
+
+A sprite variant that repeats a texture across a given area. The texture can be scrolled, scaled, and rotated independently of the sprite itself. Use for scrolling backgrounds, parallax layers, repeating ground patterns, and any surface that tiles a single texture.
+
+## Quick Start
+
+```ts
+const texture = await Assets.load("grass.png");
+
+const bg = new TilingSprite({
+  texture,
+  width: app.screen.width,
+  height: app.screen.height,
+});
+
+app.stage.addChild(bg);
+
+app.ticker.add((ticker) => {
+  bg.tilePosition.x -= 1 * ticker.deltaTime;
+});
+```
+
+`width` / `height` define the visible tiling region. `tilePosition` scrolls the pattern within that region.
+
+## Construction
+
+```ts
+const bg = new TilingSprite({
+  texture,
+  width: 800,
+  height: 600,
+  tilePosition: { x: 0, y: 0 },
+  tileScale: { x: 1.5, y: 1.5 },
+  anchor: 0.5,
+  roundPixels: true,
+});
+
+const fromTexture = TilingSprite.from(texture, { width: 800, height: 600 });
+const fromCache = TilingSprite.from("pattern.png", { width: 800, height: 600 });
+```
+
+`TilingSprite.from(source, options?)` accepts a `Texture` or a cached alias string. The alias form reads from the Assets cache only; `await Assets.load('pattern.png')` first or the returned sprite draws `Texture.EMPTY`.
+
+### TilingSpriteOptions
+
+| Option                 | Type                  | Default          | Description                                                                        |
+| ---------------------- | --------------------- | ---------------- | ---------------------------------------------------------------------------------- |
+| `texture`              | `Texture`             | `Texture.EMPTY`  | Texture repeated across the tiling region.                                         |
+| `width`                | `number`              | `256`            | Width of the visible tiling region.                                                |
+| `height`               | `number`              | `256`            | Height of the visible tiling region.                                               |
+| `anchor`               | `PointData \| number` | `{ x: 0, y: 0 }` | Normalized origin of the tiling sprite itself (not the pattern).                   |
+| `tilePosition`         | `PointData`           | `{ x: 0, y: 0 }` | Offset of the repeated pattern within the region; animate to scroll.               |
+| `tileScale`            | `PointData`           | `{ x: 1, y: 1 }` | Scale applied to the tile pattern only; sprite region stays the same size.         |
+| `tileRotation`         | `number`              | `0`              | Rotation in radians applied to the texture before tiling.                          |
+| `applyAnchorToTexture` | `boolean`             | `false`          | Shift the texture origin by the anchor instead of locking `(0,0)` to the top-left. |
+| `roundPixels`          | `boolean`             | `false`          | Snap the sprite's position (not the tile pattern) to integer coordinates.          |
+
+All `Container` options (`position`, `scale`, `tint`, `label`, `filters`, `zIndex`, etc.) are also valid here — see `skills/pixijs-scene-core-concepts/references/constructor-options.md`.
+
+## Core Patterns
+
+### Scrolling pattern
+
+```ts
+app.ticker.add((ticker) => {
+  bg.tilePosition.x -= 2 * ticker.deltaTime;
+  bg.tilePosition.y -= 0.5 * ticker.deltaTime;
+});
+```
+
+`tilePosition` is an `ObservablePoint`. Shifting it moves the pattern without moving the sprite. This is the cheapest way to scroll a background.
+
+### Tile scale and rotation
+
+```ts
+bg.tileScale.set(2, 2);
+bg.tileRotation = Math.PI / 4;
+```
+
+- `tileScale`: scales the pattern independently of the sprite. A value of `{ x: 2, y: 2 }` doubles each tile.
+- `tileRotation`: rotates the tile pattern in radians. The rotation is applied to the texture before tiling, so the underlying sprite stays axis-aligned.
+
+### Anchor on the tiling region
+
+```ts
+const bg = new TilingSprite({
+  texture,
+  width: 800,
+  height: 600,
+  anchor: 0.5,
+});
+
+bg.x = app.screen.width / 2;
+bg.y = app.screen.height / 2;
+```
+
+`anchor` is the normalized origin of the tiling sprite itself (same semantics as `Sprite`), not of the repeated tile. The visible region is anchored, the tiles fill it.
+
+### `applyAnchorToTexture`
+
+```ts
+const bg = new TilingSprite({
+  texture,
+  width: 800,
+  height: 600,
+  anchor: 0.5,
+  applyAnchorToTexture: true,
+});
+```
+
+By default, the top-left corner of the tiling region always maps to the `(0, 0)` texture coordinate. Set `applyAnchorToTexture: true` to shift the texture origin based on the anchor; useful when you want the pattern to stay centered on the sprite's anchor point as it scales.
+
+### Parallax layers
+
+```ts
+const far = new TilingSprite({ texture: farTex, width: 800, height: 600 });
+const near = new TilingSprite({ texture: nearTex, width: 800, height: 600 });
+
+app.stage.addChild(far, near);
+
+app.ticker.add((ticker) => {
+  far.tilePosition.x -= 0.5 * ticker.deltaTime;
+  near.tilePosition.x -= 2 * ticker.deltaTime;
+});
+```
+
+Give each layer a different `tilePosition` scroll rate for a parallax effect. Scroll speeds are independent per sprite.
+
+### Round pixels
+
+```ts
+const bg = new TilingSprite({
+  texture,
+  width: 800,
+  height: 600,
+  roundPixels: true,
+});
+```
+
+Snaps the sprite's position (not the tile pattern) to integer coordinates. Useful for pixel-art tilesets to avoid shimmer.
+
+### Hit testing
+
+```ts
+bg.eventMode = "static";
+bg.on("pointertap", (e) => {
+  console.log("tile clicked", bg.toLocal(e.global));
+});
+```
+
+`TilingSprite` overrides `containsPoint` so hit testing respects the anchor-offset bounds of the tiling region (not the texture). Use it as a regular event target for clickable backgrounds.
+
+### Global defaults
+
+```ts
+TilingSprite.defaultOptions.texture = Texture.from("defaultPattern.png");
+TilingSprite.defaultOptions.tileScale = { x: 2, y: 2 };
+```
+
+`TilingSprite.defaultOptions` is a mutable static object merged with any options passed to the constructor. Override fields once at startup for project-wide defaults.
+
+### Resizing the tiling region
+
+```ts
+bg.setSize(app.screen.width, app.screen.height);
+const size = bg.getSize();
+```
+
+`setSize(value, height?)` accepts a square value, two numbers, or `{ width, height }`. `getSize(out?)` returns the current region and optionally writes into an existing object. Both override the base `Sprite` behavior so a single call avoids recomputing bounds twice.
+
+## Common Mistakes
+
+### [HIGH] Forgetting to pass a texture
+
+Wrong:
+
+```ts
+const bg = new TilingSprite({ width: 800, height: 600 });
+```
+
+Correct:
+
+```ts
+const texture = await Assets.load("pattern.png");
+const bg = new TilingSprite({ texture, width: 800, height: 600 });
+```
+
+The runtime default is `Texture.EMPTY` (set in `TilingSprite.defaultOptions`), so omitting the texture produces an invisible sprite with nothing to tile. Always pass a real texture.
+
+
+### [HIGH] Scaling the sprite instead of the tile
+
+Wrong:
+
+```ts
+bg.scale.set(2);
+```
+
+Correct:
+
+```ts
+bg.tileScale.set(2);
+```
+
+Scaling the sprite stretches everything; including the visible area. Use `tileScale` to make each tile larger while keeping the sprite's region the same size.
+
+
+### [MEDIUM] Non-power-of-two textures with `tileScale`
+
+Some WebGL implementations cannot repeat non-power-of-two textures in hardware. If you see the pattern clamp to the edge instead of wrapping, resize the source texture to power-of-two dimensions (128, 256, 512, etc.) or pre-bake the tile pattern into a larger texture.
+
+
+## API Reference
+
+- [TilingSprite](https://pixijs.download/release/docs/scene.TilingSprite.html.md)
+- [TilingSpriteOptions](https://pixijs.download/release/docs/scene.TilingSpriteOptions.html.md)

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

@@ -0,0 +1,136 @@
+---
+name: pixijs-scene-text
+description: "Use this skill when rendering text in PixiJS v8. Covers Text for canvas-quality styled labels, BitmapText for cheap per-frame updates via glyph atlas, HTMLText for HTML/CSS markup via SVG, SplitText and SplitBitmapText for per-character animation, TextStyle, tagStyles, constructor options, TextOptions, HTMLTextOptions, BitmapText, SplitTextOptions, SplitBitmapTextOptions. Triggers on: Text, BitmapText, HTMLText, SplitText, SplitBitmapText, TextStyle, HTMLTextStyle, BitmapFont.install, tagStyles, fontFamily, wordWrap."
+license: MIT
+---
+
+PixiJS has five text-rendering classes that cover different trade-offs between styling, performance, and animation. `Text` renders to a canvas for full CSS-style fidelity. `BitmapText` reads from a pre-generated atlas for cheap updates. `HTMLText` renders an HTML fragment via SVG `<foreignObject>` for rich markup. `SplitText` and `SplitBitmapText` wrap the first two classes and expose per-character, per-word, and per-line containers for animation.
+
+Assumes familiarity with `pixijs-scene-core-concepts`. All text classes are leaf nodes; they cannot have children. Wrap multiple text instances in a `Container` to group them.
+
+## Quick Start
+
+```ts
+const text = new Text({
+  text: "Hello PixiJS",
+  style: {
+    fontFamily: "Arial",
+    fontSize: 36,
+    fill: 0xffffff,
+    stroke: { color: 0x4a1850, width: 5 },
+    dropShadow: { color: 0x000000, blur: 4, distance: 6 },
+  },
+});
+
+text.anchor.set(0.5);
+text.x = app.screen.width / 2;
+text.y = 40;
+
+app.stage.addChild(text);
+```
+
+All text classes use options-object constructors; positional `(string, style)` from v7 is not supported.
+
+**Related skills:** `pixijs-scene-core-concepts` (leaves, transforms), `pixijs-assets` (font loading), `pixijs-performance` (BitmapText tradeoffs), `pixijs-color` (`FillInput` for fill/stroke), `pixijs-scene-graphics` (gradients and patterns reused via `FillInput`).
+
+## Variants
+
+| Variant           | Use when                                                           | Trade-offs                                                            | Reference                                                          |
+| ----------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `Text`            | High-quality static or infrequent-update labels                    | Expensive to update (canvas re-draw + GPU upload)                     | [references/text.md](references/text.md)                           |
+| `BitmapText`      | Scores, timers, gameplay labels, anything that changes every frame | Limited styling; fixed glyph atlas; requires MSDF for crisp scaling   | [references/bitmap-text.md](references/bitmap-text.md)             |
+| `HTMLText`        | Rich formatted text, mixed styles, real HTML tags                  | Async rendering (one frame delay); similar update cost to `Text`      | [references/html-text.md](references/html-text.md)                 |
+| `SplitText`       | Per-character animation with rich styling                          | Each char is a full `Text`; expensive for long strings                | [references/split-text.md](references/split-text.md)               |
+| `SplitBitmapText` | Per-character animation on long strings or dynamic content         | Inherits BitmapText limitations (glyph atlas, no MSDF-free crispness) | [references/split-bitmap-text.md](references/split-bitmap-text.md) |
+
+## When to use what
+
+- **"I need a styled static label"** → `Text`. Use for titles, menus, dialog, error messages. See `references/text.md`.
+- **"I need a score or timer that updates every frame"** → `BitmapText`. Updates only reposition quads; no canvas re-draw. See `references/bitmap-text.md`.
+- **"I need mixed formatting with `<b>`, `<i>`, `<br>`"** → `HTMLText`. Real HTML/CSS rendering via SVG. See `references/html-text.md`.
+- **"I need inline colored tags like `<red>Warning:</red>`"** → `Text` or `HTMLText` with `tagStyles`. Both support it.
+- **"I need to animate each character individually"** → `SplitText` for short strings, `SplitBitmapText` for long strings or many instances. See `references/split-text.md` / `references/split-bitmap-text.md`.
+- **"I need CJK / Arabic / emoji-heavy text"** → `Text` or `HTMLText`. `BitmapText` fails because the glyph set is too large for a single atlas.
+- **"I need a custom font"** → Load via `Assets.load({ src: 'font.woff2', data: { family: 'MyFont' } })` first, then set `style.fontFamily: 'MyFont'`. Works for `Text` and `HTMLText`.
+
+## Update cost comparison
+
+| Update trigger      | Text | BitmapText | HTMLText | SplitText                     | SplitBitmapText          |
+| ------------------- | ---- | ---------- | -------- | ----------------------------- | ------------------------ |
+| Changing `.text`    | High | Very low   | High     | Very high (N text re-renders) | Low (N quad repositions) |
+| Changing `.style`   | High | Medium     | High     | Very high                     | Medium                   |
+| Moving (`.x`, `.y`) | Free | Free       | Free     | Free                          | Free                     |
+| Rotating / scaling  | Free | Free       | Free     | Free                          | Free                     |
+
+"Free" = normal Container transform cost. "High" = new canvas draw + GPU upload. "Very low" = quad reposition only. Update strings that change per-frame only on `BitmapText` or `SplitBitmapText`.
+
+## Quick concepts
+
+- **Options-object constructors.** Every v8 text class uses `new Text({ text, style, ... })`. The v7 `(string, style)` form is removed.
+- **`tagStyles`.** `Text` and `HTMLText` support per-tag styling via `style.tagStyles`. Tags are only parsed when `tagStyles` has entries; otherwise `<` is treated literally.
+- **`BitmapFont.install`.** Pre-generates an atlas before you create any `BitmapText`. Without install, the first `BitmapText` with a new `fontFamily` generates the atlas lazily.
+- **MSDF fonts.** Multi-channel Signed Distance Field fonts stay sharp at any size. Generate with external tools (e.g., msdf-bmfont), load via `Assets.load('font.fnt')`. Requires `import 'pixi.js/text-bitmap'` in custom builds.
+
+## Common Mistakes
+
+### [HIGH] Updating `Text.text` every frame
+
+Wrong:
+
+```ts
+app.ticker.add(() => {
+  scoreText.text = `Score: ${score}`;
+});
+```
+
+Correct:
+
+```ts
+const scoreText = new BitmapText({ text: "Score: 0", style });
+app.ticker.add(() => {
+  scoreText.text = `Score: ${score}`;
+});
+```
+
+Every `Text` update re-rasterizes the whole string. Use `BitmapText` for any value that changes per-frame.
+
+
+### [HIGH] Positional constructor args
+
+Wrong:
+
+```ts
+const text = new Text("Hello", { fontSize: 24 });
+```
+
+Correct:
+
+```ts
+const text = new Text({ text: "Hello", style: { fontSize: 24 } });
+```
+
+v8 removed the `(string, style)` form. All text classes use options objects.
+
+
+### [HIGH] Not importing `pixi.js/text-bitmap` in custom builds
+
+Under `skipExtensionImports: true` or aggressive tree-shaking, `Assets.load('font.fnt')` silently returns raw data unless you add `import 'pixi.js/text-bitmap'`. The standard `import { ... } from 'pixi.js'` bundle includes the extension.
+
+
+### [MEDIUM] Adding children to a text instance
+
+Every text class sets `allowChildren = false`. Wrap in a `Container` to group text with other content.
+
+
+## API Reference
+
+- [Text](https://pixijs.download/release/docs/scene.Text.html.md)
+- [TextStyle](https://pixijs.download/release/docs/text.TextStyle.html.md)
+- [BitmapText](https://pixijs.download/release/docs/scene.BitmapText.html.md)
+- [BitmapFont](https://pixijs.download/release/docs/text.BitmapFont.html.md)
+- [HTMLText](https://pixijs.download/release/docs/scene.HTMLText.html.md)
+- [HTMLTextStyle](https://pixijs.download/release/docs/text.HTMLTextStyle.html.md)
+- [SplitText](https://pixijs.download/release/docs/text.SplitText.html.md)
+- [SplitBitmapText](https://pixijs.download/release/docs/text.SplitBitmapText.html.md)
+- [AbstractSplitText](https://pixijs.download/release/docs/text.AbstractSplitText.html.md)
+- [AbstractText](https://pixijs.download/release/docs/scene.AbstractText.html.md)