@docyrus/animaguru 0.6.0

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

@@ -0,0 +1,205 @@
+# Fonts
+
+PixiJS loads two kinds of fonts through `Assets`: web fonts (TTF/OTF/WOFF/WOFF2) via `loadWebFont`, and bitmap fonts (FNT/XML) via `loadBitmapFont`. Use web fonts for `Text` and `HTMLText`; use bitmap fonts for `BitmapText` when you need GPU-friendly rendering without runtime text layout.
+
+## Web fonts
+
+### Quick Start
+
+```ts
+await Assets.load("fonts/titan-one.woff2");
+
+const text = new Text({
+  text: "Hello world",
+  style: { fontFamily: "Titan One", fontSize: 48 },
+});
+```
+
+Once the font is loaded, reference it by its derived family name in any `TextStyle`. PixiJS registers the font with the browser's `FontFaceSet`, so DOM elements and Canvas can use it too.
+
+### Family name derivation
+
+```ts
+// Loaded URL               → Derived family name
+// fonts/titan-one.woff     → 'Titan One'
+// fonts/open_sans.ttf      → 'Open Sans'
+// fonts/my-custom-font.otf → 'My Custom Font'
+```
+
+By default, the family name is the filename without extension, with dashes and underscores replaced by spaces and title-cased. Override it with `data.family`.
+
+### Load options via `data`
+
+```ts
+await Assets.load({
+  alias: "hero-font",
+  src: "fonts/hero.woff2",
+  data: {
+    family: "HeroFont",
+    weights: ["normal", "bold"],
+    style: "italic",
+    display: "swap",
+    unicodeRange: "U+0000-00FF",
+    stretch: "expanded",
+    featureSettings: '"liga" 1',
+  },
+});
+```
+
+Fields on `data` map directly to FontFace descriptors:
+
+| Option            | Purpose                                                                                                                                |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `family`          | Override the derived font family name                                                                                                  |
+| `weights`         | Array of weights to register. One `FontFace` per weight, all sharing the same URL. Valid values: `'normal'`, `'bold'`, `'100'`–`'900'` |
+| `style`           | `'normal'`, `'italic'`, `'oblique'`                                                                                                    |
+| `display`         | CSS `font-display` (`'auto'`, `'block'`, `'swap'`, `'fallback'`, `'optional'`)                                                         |
+| `unicodeRange`    | Restrict which codepoints the font covers                                                                                              |
+| `stretch`         | `'normal'`, `'condensed'`, `'expanded'`, etc.                                                                                          |
+| `variant`         | CSS font-variant value                                                                                                                 |
+| `featureSettings` | OpenType feature settings like `'"liga" 1, "dlig" 1'`                                                                                  |
+
+### Loading multiple weights
+
+```ts
+await Assets.load({
+  src: "fonts/inter.woff2",
+  data: {
+    family: "Inter",
+    weights: ["400", "700"],
+  },
+});
+```
+
+A single URL registers as multiple weights. Use when your font file contains a variable font or when your platform lets one file satisfy multiple weights.
+
+### Supported extensions
+
+`.ttf`, `.otf`, `.woff`, `.woff2`. WOFF2 is the smallest and universally supported in current browsers. Prefer it unless you're targeting very old environments.
+
+## Bitmap fonts
+
+### Quick Start
+
+```ts
+import "pixi.js/text-bitmap";
+
+await Assets.load("fonts/arial.fnt");
+
+const text = new BitmapText({
+  text: "Score: 9999",
+  style: { fontFamily: "Arial", fontSize: 32 },
+});
+```
+
+The side-effect import registers the `CanvasBitmapTextPipe` and `BitmapTextPipe` rendering pipes. `Assets.load('font.fnt')` works without it and returns a `BitmapFont`, but rendering a `BitmapText` fails at render time without the import.
+
+### Supported formats
+
+| Extension | Format             |
+| --------- | ------------------ |
+| `.fnt`    | BMFont text or XML |
+| `.xml`    | BMFont XML         |
+
+The parser sniffs the content to pick between text and XML automatically.
+
+### Texture page loading
+
+```ts
+// my-font.fnt references my-font_0.png, my-font_1.png
+await Assets.load("fonts/my-font.fnt");
+```
+
+Bitmap fonts reference page images by filename in the `.fnt` data. The parser resolves these relative to the `.fnt` URL and loads them automatically. Any search params on the `.fnt` URL (e.g. cache busting) propagate to the page texture URLs.
+
+### Signed Distance Field (SDF) fonts
+
+The parser detects distance field metadata in the `.fnt` file and enables `linear` scale mode plus disables mipmaps automatically. No extra configuration needed from the caller. SDF fonts stay crisp at any size, so you can render a single bitmap font at many different sizes.
+
+### Accessing the BitmapFont instance
+
+```ts
+await Assets.load({ alias: "arial", src: "fonts/arial.fnt" });
+
+const font = Assets.get("arial");
+console.log(font.chars);
+console.log(font.fontFamily);
+```
+
+The cached asset is a `BitmapFont` instance. `Assets.get('arial')` and `Assets.get('arial-bitmap')` both return it, and `Assets.get('Arial-bitmap')` works if `fontFamily` matches.
+
+## Forcing the font parser
+
+If your font URL lacks an extension, force the loader:
+
+```ts
+await Assets.load({
+  src: "https://cdn.example.com/fonts/abc123",
+  parser: "web-font",
+  data: { family: "Hero", weights: ["400", "700"] },
+});
+
+await Assets.load({
+  src: "https://cdn.example.com/fonts/hero-bmfont",
+  parser: "bitmap-font",
+});
+```
+
+See the main `SKILL.md` section on "Forcing a parser with `parser`" for the full list of parser IDs.
+
+## Common Mistakes
+
+### [HIGH] Forgetting the bitmap-font import
+
+Wrong:
+
+```ts
+import { Assets, BitmapText } from "pixi.js";
+await Assets.load("arial.fnt");
+const text = new BitmapText({ text: "Hi", style: { fontFamily: "Arial" } });
+app.stage.addChild(text);
+```
+
+Correct:
+
+```ts
+import "pixi.js/text-bitmap";
+import { Assets, BitmapText } from "pixi.js";
+await Assets.load("arial.fnt");
+const text = new BitmapText({ text: "Hi", style: { fontFamily: "Arial" } });
+app.stage.addChild(text);
+```
+
+`Assets.load('arial.fnt')` succeeds in the default bundle and returns a `BitmapFont`, but `'pixi.js/text-bitmap'` registers the `CanvasBitmapTextPipe` and `BitmapTextPipe`. Without it, `BitmapText` renders nothing or errors at render time.
+
+
+### [HIGH] Using Text before the font is loaded
+
+Wrong:
+
+```ts
+const text = new Text({ text: "Hi", style: { fontFamily: "Hero" } });
+Assets.load("fonts/hero.woff2");
+```
+
+Correct:
+
+```ts
+await Assets.load("fonts/hero.woff2");
+const text = new Text({ text: "Hi", style: { fontFamily: "Hero" } });
+```
+
+The browser falls back to a system font if the named family isn't registered yet, then the `Text` is cached at that fallback style. Reloading the font doesn't repaint existing Text objects.
+
+
+### [MEDIUM] Family name mismatch
+
+If you don't pass `data.family`, the family name is derived from the filename. `my_hero_font.woff` becomes `'My Hero Font'`; use exactly that string in your `TextStyle.fontFamily`, or set `data.family` to an explicit value.
+
+
+## API Reference
+
+- [loadWebFont](https://pixijs.download/release/docs/assets.loadWebFont.html.md)
+- [loadBitmapFont](https://pixijs.download/release/docs/assets.loadBitmapFont.html.md)
+- [LoadFontData](https://pixijs.download/release/docs/assets.LoadFontData.html.md)
+- [BitmapFont](https://pixijs.download/release/docs/scene.BitmapFont.html.md)

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

@@ -0,0 +1,171 @@
+# Animated GIFs
+
+PixiJS loads animated GIFs through `Assets.load()` and returns a `GifSource` containing all decoded frames. Pass the source to `GifSprite` for playback, looping, and frame control. GIF support is opt-in via the `'pixi.js/gif'` side-effect import.
+
+## Quick Start
+
+```ts
+import "pixi.js/gif";
+import { Assets, GifSprite } from "pixi.js";
+
+const source = await Assets.load("explosion.gif");
+const gif = new GifSprite(source);
+app.stage.addChild(gif);
+```
+
+Without `'pixi.js/gif'`, the `.gif` loader parser isn't registered and `Assets.load()` won't know what to do with the file.
+
+## Core Patterns
+
+### Load options via `data`
+
+```ts
+const source = await Assets.load({
+  src: "pixel-art.gif",
+  data: {
+    fps: 12,
+    scaleMode: "nearest",
+    resolution: 2,
+    autoGenerateMipmaps: false,
+  },
+});
+```
+
+`data` accepts `GifBufferOptions`, which extends `CanvasSourceOptions`:
+
+| Option                | Default    | Purpose                                                          |
+| --------------------- | ---------- | ---------------------------------------------------------------- |
+| `fps`                 | `30`       | Fallback frame rate when the GIF has no per-frame delay metadata |
+| `scaleMode`           | `'linear'` | `'nearest'` for pixel art, `'linear'` for smooth scaling         |
+| `resolution`          | `1`        | Render resolution of the decoded frames                          |
+| `autoGenerateMipmaps` | `false`    | Generate mipmaps for downscaling                                 |
+
+Any other `CanvasSourceOptions` field works here too.
+
+### GifSprite options
+
+```ts
+const gif = new GifSprite({
+  source,
+  autoPlay: true,
+  loop: true,
+  animationSpeed: 0.5,
+  autoUpdate: true,
+  fps: 30,
+  onComplete: () => console.log("done"),
+  onLoop: () => console.log("looped"),
+  onFrameChange: (frame) => console.log(frame),
+});
+```
+
+Construction options control playback behavior; they're independent of the load-time `data` options.
+
+### Loading from a data URI
+
+```ts
+const source = await Assets.load(
+  "data:image/gif;base64,R0lGODlhAQABAAAAACw...",
+);
+```
+
+The parser matches both `.gif` file extensions and `data:image/gif` URIs. No extra configuration needed.
+
+### Playback control
+
+```ts
+gif.play();
+gif.stop();
+gif.currentFrame = 5;
+gif.animationSpeed = 0.5;
+gif.loop = false;
+
+console.log(gif.totalFrames);
+console.log(gif.playing);
+console.log(gif.progress);
+console.log(gif.duration);
+```
+
+### Sharing a source across sprites
+
+```ts
+const source = await Assets.load("spin.gif");
+
+const a = new GifSprite(source);
+const b = new GifSprite(source);
+
+a.animationSpeed = 1;
+b.animationSpeed = 0.25;
+```
+
+Multiple `GifSprite` instances can share the same `GifSource`; each gets independent playback state. The underlying textures are shared, so this is cheap.
+
+### Cleanup
+
+```ts
+gif.destroy(); // destroys the sprite, not the source
+gif.destroy(true); // destroys the sprite AND the source (breaks other sprites using it)
+await Assets.unload("explosion.gif"); // unload through the Assets system
+```
+
+Prefer `Assets.unload` unless you know no other sprite shares the same `GifSource`.
+
+## Forcing the GIF parser
+
+If your GIF URL lacks an extension, force the parser:
+
+```ts
+const source = await Assets.load({
+  src: "https://cdn.example.com/gif/abc123",
+  parser: "gif",
+  data: { fps: 24 },
+});
+```
+
+See the main `SKILL.md` section on "Forcing a parser with `parser`" for the full list of parser IDs.
+
+## Common Mistakes
+
+### [CRITICAL] Missing the GIF import
+
+Wrong:
+
+```ts
+import { Assets } from "pixi.js";
+await Assets.load("explosion.gif");
+```
+
+Correct:
+
+```ts
+import "pixi.js/gif";
+import { Assets } from "pixi.js";
+await Assets.load("explosion.gif");
+```
+
+Without `'pixi.js/gif'`, the loader parser isn't registered. The call fails or returns undefined.
+
+
+### [MEDIUM] Using GIF when a spritesheet would be cheaper
+
+GIF decoding creates one texture per frame. For a 30-frame animation that's 30 separate uploads. A spritesheet packs all frames into a single atlas texture, which batches better and uses less GPU memory. Prefer spritesheets for performance-critical game animations; use GIFs for convenience and one-off effects.
+
+
+### [MEDIUM] destroy(true) when other sprites share the source
+
+```ts
+const source = await Assets.load("spin.gif");
+const a = new GifSprite(source);
+const b = new GifSprite(source);
+
+a.destroy(true); // WRONG: also destroys source, breaking sprite b
+```
+
+Pass `true` to `destroy` only if you know nothing else references the `GifSource`. Otherwise call plain `destroy()` and `Assets.unload()` when the source is no longer needed.
+
+
+## API Reference
+
+- [GifSource](https://pixijs.download/release/docs/gif.GifSource.html.md)
+- [GifSprite](https://pixijs.download/release/docs/gif.GifSprite.html.md)
+- [GifBufferOptions](https://pixijs.download/release/docs/gif.GifBufferOptions.html.md)
+- [GifAsset](https://pixijs.download/release/docs/gif.GifAsset.html.md)

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

@@ -0,0 +1,175 @@
+# Manifests
+
+A manifest is a JSON-shaped description of every bundle in your application. Pass it to `Assets.init({ manifest })` and the resolver registers every bundle at startup, so later code can reference them by name. Use manifests when you know your asset graph upfront and want one source of truth.
+
+## Quick Start
+
+```ts
+await Assets.init({
+  manifest: {
+    bundles: [
+      {
+        name: "load-screen",
+        assets: [{ alias: "logo", src: "logo.png" }],
+      },
+      {
+        name: "game",
+        assets: [
+          { alias: "hero", src: "hero.{webp,png}" },
+          { alias: "enemies", src: "enemies.json" },
+        ],
+      },
+    ],
+  },
+});
+
+await Assets.loadBundle("load-screen");
+await Assets.loadBundle("game");
+```
+
+Each bundle has a `name` and an `assets` array of `UnresolvedAsset` entries. Format expansions (`{webp,png}`) and resolution patterns (`@{1,2}x`) work inside `src`.
+
+## Core Patterns
+
+### Inline manifest object
+
+```ts
+const manifest = {
+  bundles: [
+    {
+      name: "ui",
+      assets: [
+        { alias: "button", src: "ui/button.png" },
+        { alias: "panel", src: "ui/panel.png" },
+      ],
+    },
+  ],
+};
+
+await Assets.init({ manifest });
+```
+
+The manifest can be any plain object matching the `AssetsManifest` shape. Pass it directly to `init`.
+
+### Manifest from a URL
+
+```ts
+await Assets.init({ manifest: "assets/manifest.json" });
+```
+
+When `manifest` is a string, PixiJS loads it as JSON first, then registers the bundles. Useful when your build tooling generates a manifest at deploy time (e.g., with `@assetpack/core`).
+
+### Format and resolution patterns in manifests
+
+```ts
+const manifest = {
+  bundles: [
+    {
+      name: "hero",
+      assets: [{ alias: "hero", src: "hero@{0.5,1,2}x.{webp,avif,png}" }],
+    },
+  ],
+};
+```
+
+The resolver expands the pattern to six candidates and picks the best match based on `window.devicePixelRatio` and browser format support. Configure preferences in `Assets.init({ texturePreference: {...} })`.
+
+### Multiple aliases per entry
+
+```ts
+const manifest = {
+  bundles: [
+    {
+      name: "characters",
+      assets: [
+        { alias: ["hero", "player"], src: "hero.png" },
+        { alias: "npc1", src: "villager.png" },
+      ],
+    },
+  ],
+};
+```
+
+An asset can expose multiple aliases. `Assets.load('hero')` and `Assets.load('player')` return the same texture.
+
+### Data options in manifest entries
+
+```ts
+const manifest = {
+  bundles: [
+    {
+      name: "pixel-art",
+      assets: [
+        {
+          alias: "tile",
+          src: "tile.png",
+          data: { scaleMode: "nearest" },
+        },
+      ],
+    },
+  ],
+};
+```
+
+Each asset entry can include a `data` field forwarded to the loader. Use it for `scaleMode`, `autoGenerateMipmaps`, `parseAsGraphicsContext`, FontFace descriptors, etc.
+
+### Background-loading from a manifest
+
+```ts
+await Assets.init({ manifest });
+await Assets.loadBundle("load-screen");
+
+Assets.backgroundLoadBundle("game");
+await Assets.loadBundle("game");
+```
+
+After init, you can start background loading of other bundles immediately. The call is non-blocking; the `await Assets.loadBundle('game')` later resolves quickly if the background work finished.
+
+## Common Mistakes
+
+### [HIGH] Calling `Assets.init` twice
+
+Wrong:
+
+```ts
+await Assets.init({ manifest });
+await Assets.init({ basePath: "https://cdn.example.com/" });
+```
+
+Correct:
+
+```ts
+await Assets.init({ manifest, basePath: "https://cdn.example.com/" });
+```
+
+`Assets.init()` can only be called once. The second call is ignored with a warning. Combine all configuration into a single call.
+
+
+### [MEDIUM] Missing format expansion on manifest entries
+
+Wrong:
+
+```ts
+{ alias: 'hero', src: 'hero.webp' }
+```
+
+Correct:
+
+```ts
+{ alias: 'hero', src: 'hero.{webp,png}' }
+```
+
+Listing only one format blocks the resolver from falling back on browsers without WebP/AVIF support. Always list at least one fallback.
+
+
+### [MEDIUM] Loading manifest after `Assets.add`
+
+If you call `Assets.add(...)` or `Assets.addBundle(...)` before `Assets.init({ manifest })`, the manifest bundles will append to the existing state but preference-detection (format, resolution) hasn't run yet. Prefer calling `init` first, then adding ad-hoc assets.
+
+
+## API Reference
+
+- [AssetsManifest](https://pixijs.download/release/docs/assets.AssetsManifest.html.md)
+- [Assets](https://pixijs.download/release/docs/assets.Assets.html.md)
+- [Resolver](https://pixijs.download/release/docs/assets.Resolver.html.md)
+- [UnresolvedAsset](https://pixijs.download/release/docs/assets.UnresolvedAsset.html.md)

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

@@ -0,0 +1,142 @@
+# Progress Tracking
+
+`Assets.load` and `Assets.loadBundle` accept a progress callback that fires as each asset completes. Use it to drive loading bars, percentage readouts, or spinner state updates during long loads. The progress value is normalized `[0, 1]` across the entire call.
+
+## Quick Start
+
+```ts
+const loadingBar = new Graphics();
+app.stage.addChild(loadingBar);
+
+await Assets.load(["hero.png", "enemy.png", "map.json"], (progress) => {
+  loadingBar.clear();
+  loadingBar.rect(0, 0, progress * 400, 20).fill(0x66ccff);
+});
+```
+
+The callback is invoked after each asset resolves. Final invocation reaches `1.0` just before the promise resolves.
+
+## Core Patterns
+
+### Progress on a single asset
+
+```ts
+await Assets.load("large-atlas.json", (progress) => {
+  console.log(`${Math.round(progress * 100)}%`);
+});
+```
+
+Even for a single asset, the callback fires (typically once, reaching `1.0`). For most cases, progress for a single call is not useful; prefer progress on bundles or arrays.
+
+### Progress on an array
+
+```ts
+const assets = await Assets.load(
+  ["hero.png", "enemy.png", "map.json", "music.mp3"],
+  (progress) => updateBar(progress),
+);
+```
+
+Progress is distributed evenly across the N assets. When the third asset in a four-asset array finishes, progress is `0.75`.
+
+### Progress on a bundle
+
+```ts
+await Assets.loadBundle("level1", (progress) => {
+  loadingText.text = `Loading… ${Math.round(progress * 100)}%`;
+});
+```
+
+Each asset in the bundle contributes equally. If the bundle has 10 entries, each contributes `0.1` to the total.
+
+### Progress via `LoadOptions.onProgress`
+
+```ts
+await Assets.load("game.json", {
+  onProgress: (progress) => updateBar(progress),
+  onError: (err, asset) => {
+    const src = typeof asset === "string" ? asset : asset.src;
+    console.warn("failed:", src, err);
+  },
+});
+```
+
+Instead of a callback as the second argument, pass a `LoadOptions` object. This is the preferred form when you also need error handling or retry strategies. Note that `onError` receives `string | ResolvedAsset`; guard before accessing `.src`.
+
+### Global progress across multiple loads
+
+```ts
+async function loadAllWithTotal(tasks: Array<() => Promise<any>>) {
+  let done = 0;
+  for (const task of tasks) {
+    await task();
+    done++;
+    updateBar(done / tasks.length);
+  }
+}
+
+await loadAllWithTotal([
+  () => Assets.load("menu.json"),
+  () => Assets.loadBundle("level1"),
+  () => Assets.loadBundle("sounds"),
+]);
+```
+
+Progress callbacks are scoped per call. If you need a single bar across several sequential loads, wrap the calls manually and count completions yourself.
+
+## Common Mistakes
+
+### [HIGH] Treating progress callback as completion
+
+Wrong:
+
+```ts
+Assets.load("hero.png", (progress) => {
+  if (progress === 1) {
+    showHero();
+  }
+});
+```
+
+Correct:
+
+```ts
+await Assets.load("hero.png", (progress) => updateBar(progress));
+showHero();
+```
+
+`progress === 1` may fire slightly before the returned promise resolves. Always use the `await` or `.then()` to know when loading is truly complete. The progress callback is for UI updates only.
+
+
+### [MEDIUM] Progress not updating smoothly
+
+Each asset contributes a discrete step. If your bundle has three assets, progress jumps `0 -> 0.33 -> 0.66 -> 1.0`. For a smoother bar, split large bundles into smaller ones, or animate the bar width toward the target value:
+
+```ts
+let target = 0;
+await Assets.loadBundle("game", (p) => {
+  target = p;
+});
+
+app.ticker.add(() => {
+  loadingBar.width += (target * maxWidth - loadingBar.width) * 0.1;
+});
+```
+
+
+### [MEDIUM] Progress via background loading
+
+Wrong:
+
+```ts
+Assets.backgroundLoadBundle("game", (p) => updateBar(p));
+```
+
+Background loading has no progress callback. For visible progress, use `Assets.loadBundle` (foreground). See `references/background.md`.
+
+
+## API Reference
+
+- [Assets](https://pixijs.download/release/docs/assets.Assets.html.md)
+- [LoadOptions](https://pixijs.download/release/docs/assets.LoadOptions.html.md)
+- [ProgressCallback](https://pixijs.download/release/docs/assets.ProgressCallback.html.md)