@docyrus/animaguru 0.6.0

package/vendor/pixijs-skills/skills/pixijs-assets/references/resolution.md

@@ -0,0 +1,142 @@
+# Resolution and Format Detection
+
+PixiJS's asset resolver can pick the best asset variant for the current device based on pixel density (`@0.5x`, `@1x`, `@2x`) and supported image formats (`avif`, `webp`, `png`). Use resolution and format patterns to serve one asset spec that adapts to retina displays, format support, and bandwidth budgets.
+
+## Quick Start
+
+```ts
+await Assets.init({
+  texturePreference: {
+    resolution: window.devicePixelRatio,
+    format: ["avif", "webp", "png"],
+  },
+});
+
+Assets.add({ alias: "hero", src: "hero@{0.5,1,2}x.{webp,png}" });
+
+const texture = await Assets.load("hero");
+```
+
+The resolver expands the pattern to six candidates (`hero@0.5x.webp`, `hero@0.5x.png`, `hero@1x.webp`, ...) and picks the best match based on device pixel ratio and format support.
+
+## Core Patterns
+
+### Configuring preferences at init
+
+```ts
+await Assets.init({
+  texturePreference: {
+    resolution: window.devicePixelRatio, // e.g., 2 on retina
+    format: ["avif", "webp", "png"], // preferred-first order
+  },
+});
+```
+
+- `resolution` is a single number (best-match threshold) or array of acceptable resolutions.
+- `format` is ordered by preference. The resolver tries each in turn and uses the first one the browser supports.
+
+### Resolution patterns in src
+
+```ts
+Assets.add({ alias: "bg", src: "bg@{0.5,1,2}x.png" });
+```
+
+The resolver expands this to `bg@0.5x.png`, `bg@1x.png`, `bg@2x.png` and picks based on `texturePreference.resolution`. Encoded resolution sets the texture's source resolution automatically, so the sprite's `width` / `height` appear as logical size regardless of the file chosen.
+
+### Format patterns in src
+
+```ts
+Assets.add({ alias: "icon", src: "icon.{avif,webp,png}" });
+```
+
+Format detection runs once during `Assets.init()`. The resolver learns which formats the browser supports, then picks the highest-preference supported format per load.
+
+### Combined resolution + format
+
+```ts
+Assets.add({ alias: "hero", src: "hero@{0.5,1,2}x.{avif,webp,png}" });
+```
+
+Both patterns can appear in the same `src`. The resolver does a Cartesian product: 3 resolutions × 3 formats = 9 candidates. It picks the best combination based on both preferences.
+
+### Manual resolution override
+
+```ts
+Assets.add({
+  alias: "sharp",
+  src: "sharp.png",
+  data: { resolution: 2 },
+});
+```
+
+If a file is already at a known resolution but lacks the `@2x` filename suffix, pass `resolution` in `data` to tell the loader. Useful when your tooling doesn't produce suffixed filenames.
+
+### Custom retina prefix
+
+```ts
+import { Resolver } from "pixi.js";
+
+Resolver.RETINA_PREFIX = /@([0-9\.]+)density/;
+
+Assets.add({ alias: "hero", src: "hero@{1,2}density.png" });
+```
+
+Change the resolution filename pattern if your build pipeline uses a different convention. Default is `/@([0-9\.]+)x/`.
+
+### Skipping format detection
+
+```ts
+await Assets.init({
+  skipDetections: true,
+  texturePreference: { format: ["webp"] },
+});
+```
+
+If you know your target browser supports a specific format, `skipDetections: true` skips the runtime detection (a small init-time saving). Useful for embedded or kiosk deployments where format support is fixed.
+
+## Common Mistakes
+
+### [HIGH] Wrong pattern syntax
+
+Wrong:
+
+```ts
+Assets.add({ alias: "hero", src: "hero@[1,2]x.png" });
+```
+
+Correct:
+
+```ts
+Assets.add({ alias: "hero", src: "hero@{1,2}x.png" });
+```
+
+The expansion syntax uses `{}` (like shell brace expansion), not `[]`. Square brackets aren't recognized and the resolver tries to load the literal filename.
+
+
+### [MEDIUM] Missing fallback format
+
+Wrong:
+
+```ts
+Assets.add({ alias: "hero", src: "hero.avif" });
+```
+
+Correct:
+
+```ts
+Assets.add({ alias: "hero", src: "hero.{avif,png}" });
+```
+
+If a browser doesn't support AVIF, the loader fails. Always list at least one fallback format that all target browsers support.
+
+
+### [MEDIUM] Mismatch between spritesheet.json `meta.scale` and actual image
+
+In v8, a spritesheet's `meta.scale` field directly sets the resolution of the atlas texture. If the JSON says `"1"` but the image was exported at 2x, frames render at double the intended size. Verify `meta.scale` matches the actual image resolution; atlas tools like TexturePacker set this automatically.
+
+
+## API Reference
+
+- [Assets](https://pixijs.download/release/docs/assets.Assets.html.md)
+- [Resolver](https://pixijs.download/release/docs/assets.Resolver.html.md)
+- [AssetInitOptions](https://pixijs.download/release/docs/assets.AssetInitOptions.html.md)

package/vendor/pixijs-skills/skills/pixijs-assets/references/spritesheet.md

@@ -0,0 +1,119 @@
+# Spritesheet: Texture Atlases and Animations
+
+Load and use texture atlases and animation sheets with PixiJS's `Spritesheet` class. Atlases reduce draw calls by packing many textures into a single image.
+
+## Quick Start
+
+```ts
+const sheet = await Assets.load("spritesheet.json");
+
+const hero = new Sprite(sheet.textures["hero.png"]);
+app.stage.addChild(hero);
+
+const walk = new AnimatedSprite(sheet.animations["walk"]);
+walk.animationSpeed = 0.15;
+walk.play();
+app.stage.addChild(walk);
+```
+
+When loaded through `Assets.load()`, the JSON file is fetched, the atlas image is loaded, and `sheet.parse()` is called automatically. The returned object is a `Spritesheet` instance.
+
+## Core Patterns
+
+### SpritesheetData JSON format
+
+```json
+{
+  "frames": {
+    "hero.png": {
+      "frame": { "x": 0, "y": 0, "w": 64, "h": 64 },
+      "sourceSize": { "w": 64, "h": 64 },
+      "spriteSourceSize": { "x": 0, "y": 0, "w": 64, "h": 64 },
+      "anchor": { "x": 0.5, "y": 0.5 },
+      "borders": { "left": 10, "top": 10, "right": 10, "bottom": 10 }
+    },
+    "walk_01.png": {
+      "frame": { "x": 64, "y": 0, "w": 64, "h": 64 },
+      "rotated": true,
+      "trimmed": true,
+      "sourceSize": { "w": 80, "h": 80 },
+      "spriteSourceSize": { "x": 8, "y": 8, "w": 64, "h": 64 }
+    }
+  },
+  "animations": {
+    "walk": ["walk_01.png", "walk_02.png", "walk_03.png"]
+  },
+  "meta": {
+    "image": "spritesheet.png",
+    "size": { "w": 512, "h": 256 },
+    "scale": "1"
+  }
+}
+```
+
+Key fields:
+
+- `frames` maps frame names to rectangle data, trim info, anchors, and 9-slice borders.
+- `rotated` indicates the frame is stored rotated 90 degrees in the atlas. The parser swaps width/height automatically.
+- `trimmed` indicates transparent padding was removed. `sourceSize` is the original dimensions; `spriteSourceSize` is the trimmed region within it.
+- `animations` maps animation names to ordered arrays of frame names.
+- `meta.scale` sets the resolution of the texture source. `"2"` means the atlas is @2x.
+- `meta.image` is the atlas image filename, resolved relative to the JSON file.
+
+### Manual Spritesheet creation
+
+```ts
+const texture = await Assets.load("atlas.png");
+const sheet = new Spritesheet({
+  texture,
+  data: spritesheetJsonData,
+  cachePrefix: "myAtlas_",
+});
+await sheet.parse();
+
+const frame = new Sprite(sheet.textures["hero.png"]);
+```
+
+`parse()` is async for large spritesheets (over 1000 frames); it batches texture creation across multiple frames. For smaller sheets, `parseSync()` is also available.
+
+`cachePrefix` prepends a string to all cached texture names, preventing collisions when multiple atlases share frame names (e.g., `"hero.png"` in two different sheets).
+
+### Preloaded texture with Assets
+
+```ts
+const atlasTexture = await Assets.load("images/spritesheet.png");
+
+Assets.add({
+  alias: "atlas",
+  src: "images/spritesheet.json",
+  data: { texture: atlasTexture },
+});
+const sheet = await Assets.load("atlas");
+```
+
+### Multi-pack spritesheets
+
+When `meta.related_multi_packs` is present, the loader automatically loads and links related spritesheets. All linked sheets are accessible via `sheet.linkedSheets`.
+
+### Cleanup
+
+```ts
+sheet.destroy();
+sheet.destroy(true); // also destroys the base atlas texture
+```
+
+## Common Mistakes
+
+### [HIGH] Spritesheet meta.scale behavior change
+
+In v8, `meta.scale` directly sets the texture source resolution. If your atlas was exported at @2x but `meta.scale` says `"1"`, frames render at double the intended size. Ensure `meta.scale` matches the actual resolution of the atlas image. Tools like TexturePacker set this automatically.
+
+### [MEDIUM] Not awaiting spritesheet parse
+
+`parse()` is async. Accessing `sheet.textures` before it resolves returns undefined entries. When loading via `Assets.load()`, parsing is handled automatically.
+
+## API Reference
+
+- [Spritesheet](https://pixijs.download/release/docs/assets.Spritesheet.html.md)
+- [spritesheetAsset](https://pixijs.download/release/docs/assets.spritesheetAsset.html.md)
+- [AnimatedSprite](https://pixijs.download/release/docs/scene.AnimatedSprite.html.md)

package/vendor/pixijs-skills/skills/pixijs-assets/references/svg.md

@@ -0,0 +1,132 @@
+# SVG Loading
+
+PixiJS loads `.svg` files in one of two modes: rasterized to a texture (fast, fixed resolution) or parsed into a `GraphicsContext` (scalable vector, reusable across `Graphics` instances). Choose texture mode for backgrounds and decorative elements at a fixed size; choose Graphics mode for icons, UI elements, or anything that needs to scale or be modified at runtime.
+
+## Quick Start
+
+```ts
+const svgTexture = await Assets.load("icon.svg");
+const sprite = new Sprite(svgTexture);
+
+const svgContext = await Assets.load({
+  src: "icon.svg",
+  data: { parseAsGraphicsContext: true },
+});
+const graphic = new Graphics(svgContext);
+```
+
+By default, SVG files rasterize to a texture at their native size. Pass `parseAsGraphicsContext: true` in the `data` field to parse as vector geometry instead.
+
+## Core Patterns
+
+### Texture mode (default)
+
+```ts
+const icon = await Assets.load("close.svg");
+const button = new Sprite(icon);
+```
+
+The SVG is rasterized to a bitmap via the browser's native SVG-to-image pipeline, then uploaded as a `Texture`. Rendering is batched just like a regular sprite. Scaling up beyond the rasterized resolution pixelates; the rasterization happens once.
+
+### Graphics mode
+
+```ts
+const context = await Assets.load({
+  src: "logo.svg",
+  data: { parseAsGraphicsContext: true },
+});
+
+const small = new Graphics(context);
+small.scale.set(0.5);
+
+const large = new Graphics(context);
+large.scale.set(3);
+```
+
+The SVG is parsed into a `GraphicsContext` (a compiled list of fill/stroke instructions). Both `Graphics` instances share the same context; cheap, and both stay crisp at any scale.
+
+### Resolution for sharper texture mode
+
+```ts
+const icon = await Assets.load({
+  src: "icon.svg",
+  data: { resolution: 2 },
+});
+```
+
+For texture mode, you can pass `resolution` in `data` to rasterize at a higher density. Pairs with `autoGenerateMipmaps` for smooth downscaling. Doesn't apply in Graphics mode.
+
+### Global default
+
+```ts
+import { loadSvg } from "pixi.js";
+
+loadSvg.config.parseAsGraphicsContext = true;
+```
+
+Flip the default mode globally. Any subsequent `Assets.load('*.svg')` call parses as Graphics unless overridden in the asset's `data` options.
+
+### What Graphics mode parses
+
+Graphics mode reads `<path>` (including `fill-rule="evenodd"` holes), `<rect>`, `<circle>`, `<ellipse>`, `<line>`, `<polygon>`, `<polyline>`, and `<g>`. Styling comes from the `fill`, `stroke`, `stroke-width`, `fill-opacity`, `stroke-opacity`, and `opacity` attributes or inline `style="..."`. Fills and strokes can reference `<linearGradient>` and `<radialGradient>` definitions through `url(#id)`; `gradientUnits` and percentage coordinates are honored. Not supported: `transform` attributes, `<style>` blocks, `stroke-dasharray`/`stroke-linecap`/`stroke-linejoin`, `gradientTransform`, `spreadMethod`, `stop-opacity`, `<text>`, `<image>`, `<use>`, `<clipPath>`, `<mask>`, `<pattern>`, and filters. Unsupported elements are skipped with a console warning. Texture mode has none of these limits because the browser rasterizes the file.
+
+### When to use which mode
+
+| Mode                                      | Best for                                          | Cost                                                           |
+| ----------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------- |
+| Texture (default)                         | Icons at a known size, backgrounds, complex SVGs  | One-time rasterization; fast per-frame; pixelates when scaled  |
+| Graphics (`parseAsGraphicsContext: true`) | Scalable icons, UI elements, runtime modification | Higher initial parse cost; crisp at any scale; shared contexts |
+
+If you need the same SVG at multiple sizes, Graphics mode is usually faster because you parse once and scale cheaply. If you have one fixed-size SVG, texture mode is simpler and batches with other sprites.
+
+## Common Mistakes
+
+### [HIGH] Expecting scalability in texture mode
+
+Wrong:
+
+```ts
+const icon = await Assets.load("icon.svg");
+const sprite = new Sprite(icon);
+sprite.scale.set(5); // pixelates
+```
+
+Correct (if you need scaling):
+
+```ts
+const context = await Assets.load({
+  src: "icon.svg",
+  data: { parseAsGraphicsContext: true },
+});
+const graphic = new Graphics(context);
+graphic.scale.set(5); // crisp
+```
+
+Or rasterize at higher resolution:
+
+```ts
+const icon = await Assets.load({
+  src: "icon.svg",
+  data: { resolution: 5 },
+});
+```
+
+Texture mode is frozen at rasterization time. Use Graphics mode or high `resolution` when the final size isn't known upfront.
+
+
+### [MEDIUM] External references in SVG files
+
+SVGs that reference external images via `<image href="...">` may fail to load if the reference is cross-origin without CORS headers. Inline the image data as base64 or serve everything from the same origin.
+
+
+### [MEDIUM] CSS in `<style>` elements
+
+Graphics mode does not read `<style>` blocks or class selectors at all; only presentation attributes and inline `style="..."` are parsed, so class-styled shapes render with the default black fill. Move the styling inline, or use texture mode for full CSS fidelity.
+
+
+## API Reference
+
+- [Assets](https://pixijs.download/release/docs/assets.Assets.html.md)
+- [LoadSVGConfig](https://pixijs.download/release/docs/assets.LoadSVGConfig.html.md)
+- [Graphics](https://pixijs.download/release/docs/scene.Graphics.html.md)
+- [GraphicsContext](https://pixijs.download/release/docs/scene.GraphicsContext.html.md)

package/vendor/pixijs-skills/skills/pixijs-assets/references/video.md

@@ -0,0 +1,158 @@
+# Video Textures
+
+PixiJS loads videos through `Assets.load()` and returns a regular `Texture`. Pass the texture to a `Sprite` and it paints the current video frame each render. Use video textures for backgrounds, cutscenes, or any animated surface driven by a video source.
+
+Supported extensions: `.mp4`, `.m4v`, `.webm`, `.ogg`, `.ogv`, `.h264`, `.avi`, `.mov`. Browser support varies; always provide a fallback format.
+
+## Quick Start
+
+```ts
+const videoTex = await Assets.load("intro.mp4");
+const sprite = new Sprite(videoTex);
+app.stage.addChild(sprite);
+```
+
+The returned texture wraps a `VideoSource`. The video starts playing automatically unless you set `autoPlay: false` in the `data` options.
+
+## Core Patterns
+
+### Load options via `data`
+
+```ts
+const texture = await Assets.load({
+  src: "city.mp4",
+  data: {
+    autoPlay: false,
+    loop: true,
+    muted: true,
+    preload: true,
+    playsinline: true,
+    updateFPS: 30,
+    alphaMode: "premultiply-alpha-on-upload",
+  },
+});
+```
+
+`data` accepts `VideoSourceOptions` fields. Defaults come from `VideoSource.defaultOptions`.
+
+| Option        | Default                | Purpose                                                    |
+| ------------- | ---------------------- | ---------------------------------------------------------- |
+| `autoLoad`    | `true`                 | Start downloading the video as soon as it's assigned       |
+| `autoPlay`    | `true`                 | Start playing once `canplay` fires                         |
+| `loop`        | `false`                | Restart at the end                                         |
+| `muted`       | `true`                 | Required for autoplay on most browsers                     |
+| `playsinline` | `true`                 | Prevents iOS fullscreen takeover                           |
+| `preload`     | `false`                | Await `canplaythrough` before resolving                    |
+| `updateFPS`   | `0`                    | Texture update rate. `0` updates every render frame        |
+| `crossorigin` | `true`                 | CORS mode for cross-origin URLs                            |
+| `alphaMode`   | auto-detected          | `'no-premultiply-alpha'` for straight alpha                |
+| `mime`        | derived from extension | Force a specific MIME type when the URL lacks an extension |
+
+### Format fallback
+
+```ts
+Assets.add({
+  alias: "clip",
+  src: "clip.{webm,mp4}",
+});
+
+const texture = await Assets.load("clip");
+```
+
+List multiple formats so the resolver picks the first one the browser supports. WebM and MP4 together cover all current browsers.
+
+### Mobile autoplay
+
+```ts
+const texture = await Assets.load({
+  src: "ad.mp4",
+  data: {
+    muted: true,
+    playsinline: true,
+    autoPlay: true,
+  },
+});
+```
+
+iOS and mobile Chrome only autoplay muted, inline video. Set both `muted: true` and `playsinline: true` or playback stalls on the first frame until the user taps.
+
+### Manual playback control
+
+```ts
+const texture = await Assets.load({
+  src: "boss-fight.mp4",
+  data: { autoPlay: false, preload: true },
+});
+
+const videoSource = texture.source as VideoSource;
+
+startButton.on("pointertap", () => {
+  videoSource.resource.play();
+});
+```
+
+With `autoPlay: false`, grab the underlying `VideoSource` from `texture.source` and call `.play()`, `.pause()`, or `.currentTime =` on its `resource` (the `HTMLVideoElement`). Pair with `preload: true` to guarantee the first frame is uploaded before you call `play()`.
+
+### Updating at a fixed rate
+
+```ts
+await Assets.load({
+  src: "background.mp4",
+  data: { updateFPS: 15 },
+});
+```
+
+`updateFPS` caps how often the GPU texture re-uploads from the video element. `0` re-uploads every render tick (smoothest; highest cost). `15` caps it to 15 uploads per second, which saves bandwidth on static-ish video backgrounds.
+
+## Forcing the video parser
+
+If your video URL lacks an extension (e.g., a CDN signed URL or a blob), the loader can't pick a parser by test. Force it with the top-level `parser` field:
+
+```ts
+const texture = await Assets.load({
+  src: "https://cdn.example.com/stream/abc123",
+  parser: "video",
+  data: { mime: "video/mp4" },
+});
+```
+
+See the main `SKILL.md` section on "Forcing a parser with `parser`" for the full list of parser IDs.
+
+## Common Mistakes
+
+### [HIGH] Autoplay without mute on mobile
+
+Wrong:
+
+```ts
+await Assets.load({ src: "ad.mp4", data: { autoPlay: true } });
+```
+
+Correct:
+
+```ts
+await Assets.load({
+  src: "ad.mp4",
+  data: { autoPlay: true, muted: true, playsinline: true },
+});
+```
+
+Mobile browsers block autoplay with sound. The promise resolves, but the video stays frozen on frame 0 until the user interacts.
+
+
+### [MEDIUM] Expecting sprite.texture to update itself
+
+The `Sprite` reflects the current video frame automatically because `VideoSource` re-uploads on every render. You don't need to call `update()` yourself. If playback looks frozen, check that the underlying video element is actually playing (`videoSource.resource.paused` should be `false`).
+
+
+### [MEDIUM] Missing CORS for cross-origin video
+
+Video served from another origin without `Access-Control-Allow-Origin` headers taints the canvas and most WebGL operations (`readPixels`, snapshots) fail silently. Either serve with CORS headers or pass `data: { crossorigin: false }` and accept that the texture can't be extracted.
+
+
+## API Reference
+
+- [VideoSource](https://pixijs.download/release/docs/rendering.VideoSource.html.md)
+- [VideoSourceOptions](https://pixijs.download/release/docs/rendering.VideoSourceOptions.html.md)
+- [loadVideoTextures](https://pixijs.download/release/docs/assets.loadVideoTextures.html.md)
+- [Assets](https://pixijs.download/release/docs/assets.Assets.html.md)