@docyrus/animaguru 0.6.0

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

@@ -0,0 +1,137 @@
+# Background Loading
+
+Background loading lets PixiJS fetch and prepare assets passively while other work happens. Use it to prime the next level while the current one is playing, preload assets during a splash screen, or prepare UI assets during initial load. `backgroundLoad` and `backgroundLoadBundle` are non-blocking and return immediately.
+
+## Quick Start
+
+```ts
+await Assets.loadBundle("menu");
+showMenu();
+
+Assets.backgroundLoadBundle("level1");
+
+playerClicksStart(() => {
+  Assets.loadBundle("level1").then(() => startLevel());
+});
+```
+
+The `backgroundLoadBundle` call starts loading `level1` immediately without blocking. The later `loadBundle` call resolves quickly if background loading finished in the meantime.
+
+## Core Patterns
+
+### Background-loading a single asset
+
+```ts
+Assets.backgroundLoad("images/level2-assets.png");
+
+// later, when we need it:
+const texture = await Assets.load("images/level2-assets.png");
+```
+
+Fire-and-forget. Background loading happens one asset at a time to avoid blocking the main thread. When your code later calls `Assets.load(url)` for the same asset, it either resolves immediately (if background work finished) or waits for the already-in-progress load.
+
+### Background-loading an array
+
+```ts
+Assets.backgroundLoad([
+  "images/sprite1.png",
+  "images/sprite2.png",
+  "images/background.png",
+]);
+```
+
+Queues multiple assets for background loading. They're processed sequentially.
+
+### Background-loading a bundle
+
+```ts
+await Assets.init({
+  manifest: {
+    bundles: [
+      { name: "home", assets: [{ alias: "bg", src: "home-bg.png" }] },
+      { name: "level-1", assets: [{ alias: "map", src: "level1-map.json" }] },
+    ],
+  },
+});
+
+await Assets.loadBundle("home");
+showHome();
+
+Assets.backgroundLoadBundle("level-1");
+
+onPlayClicked(async () => {
+  await Assets.loadBundle("level-1");
+  startLevel();
+});
+```
+
+Same idea for bundles. Bundle assets are queued one at a time. Requires the bundle to exist via the manifest or `addBundle`.
+
+### Interrupting background loading
+
+```ts
+Assets.backgroundLoadBundle("level-2");
+
+onPlayerDecidedLevel3(async () => {
+  await Assets.loadBundle("level-3");
+});
+```
+
+Calling `Assets.load()` or `Assets.loadBundle()` interrupts background loading safely. The current background asset finishes, then the explicit load takes priority. Your explicit load resolves normally.
+
+### Combining with a progress bar
+
+Background loading has no progress callback; it runs silently. To show a loading bar, use `Assets.loadBundle(name, onProgress)` in the foreground instead. Typical pattern: use background loading for nice-to-have preloads and foreground loading for the bundles you're actually waiting on.
+
+## Common Mistakes
+
+### [HIGH] Expecting progress from background loading
+
+Wrong:
+
+```ts
+Assets.backgroundLoadBundle("level2", (p) => updateBar(p));
+```
+
+Correct:
+
+```ts
+Assets.backgroundLoadBundle("level2");
+// show a spinner or no UI while it runs
+```
+
+`backgroundLoad` and `backgroundLoadBundle` don't accept progress callbacks. They're silent. For visible progress, use the foreground `Assets.load` / `Assets.loadBundle` with an `onProgress` argument.
+
+
+### [MEDIUM] Assuming background load completes before next foreground load
+
+Wrong:
+
+```ts
+Assets.backgroundLoadBundle("level-2");
+setTimeout(() => startLevel2(), 0);
+```
+
+Correct:
+
+```ts
+Assets.backgroundLoadBundle("level-2");
+
+onStart(async () => {
+  await Assets.loadBundle("level-2");
+  startLevel2();
+});
+```
+
+Background loading is best-effort. If the player hits Start before it finishes, the foreground `loadBundle` still needs to await the remaining work. Always `await` the real load before using the assets.
+
+
+### [MEDIUM] Background-loading assets that are never used
+
+Each queued background load consumes bandwidth and GPU memory. If the player never visits level 2, you've wasted that bandwidth. Background-load only what you're confident will be needed soon.
+
+
+## API Reference
+
+- [Assets](https://pixijs.download/release/docs/assets.Assets.html.md)
+- [BackgroundLoader](https://pixijs.download/release/docs/assets.BackgroundLoader.html.md)

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

@@ -0,0 +1,122 @@
+# Bundles
+
+A bundle is a named group of assets you can load or unload as a unit. Use bundles to batch assets per game level, UI screen, or feature so that a single `loadBundle(name)` call resolves everything needed for that context. Bundles play well with background loading and manifest-based workflows.
+
+## Quick Start
+
+```ts
+Assets.addBundle("level1", [
+  { alias: "bg", src: "level1/background.png" },
+  { alias: "tileset", src: "level1/tiles.json" },
+  { alias: "theme", src: "level1/music.mp3" },
+]);
+
+const resources = await Assets.loadBundle("level1");
+const bg = Sprite.from("bg");
+```
+
+`loadBundle(name)` returns a `Record<alias, asset>`. Each alias is also available via `Assets.get(alias)` after the bundle resolves.
+
+## Core Patterns
+
+### Programmatic bundles
+
+```ts
+Assets.addBundle("ui", [
+  { alias: "button", src: "ui/button.png" },
+  { alias: "panel", src: "ui/panel.png" },
+  { alias: "cursor", src: "ui/cursor.png" },
+]);
+
+await Assets.loadBundle("ui");
+```
+
+`addBundle(name, assets)` registers a bundle at runtime. The assets array uses the same `{ alias, src, data? }` shape as `Assets.add()`.
+
+### Loading multiple bundles at once
+
+```ts
+await Assets.loadBundle(["ui", "level1", "sounds"]);
+```
+
+Pass an array of bundle names to load them in parallel. The returned object is keyed by bundle name: `{ ui: {...}, level1: {...}, sounds: {...} }`.
+
+### Progress across a bundle
+
+```ts
+await Assets.loadBundle("level1", (progress) => {
+  loadingBar.width = progress * maxBarWidth;
+});
+```
+
+The second argument is a `ProgressCallback` that fires as each asset in the bundle completes. Progress is normalized `[0, 1]` across the entire bundle.
+
+### Unloading a bundle
+
+```ts
+await Assets.unloadBundle("level1");
+```
+
+Tears down every asset in the bundle, releases GPU memory, and removes cached entries. Remove any Sprites or Text that reference the bundle's textures before unloading.
+
+### Sharing assets between bundles
+
+```ts
+Assets.addBundle("main", [{ alias: "hero", src: "hero.png" }]);
+Assets.addBundle("bossArea", [{ alias: "hero", src: "hero.png" }]);
+```
+
+If two bundles declare the same alias with the same `src`, the underlying texture is loaded once and shared. There is no reference counting: unloading either bundle destroys the shared texture, and the other bundle's alias stays broken until you reload it.
+
+### Bundle IDs
+
+```ts
+const resources = await Assets.loadBundle("level1");
+const bg = resources["bg"];
+
+const fromCache = Assets.get("bg");
+
+const fromNamespaced = Assets.get("level1-bg");
+```
+
+Inside the resolver, bundle assets are stored under a combined key like `'level1-bg'` by default. The plain `'bg'` alias still resolves thanks to resolver shortcuts. If you need to override the format, pass `bundleIdentifier` to `Assets.init()`.
+
+## Common Mistakes
+
+### [HIGH] Unloading while assets are still in use
+
+Wrong:
+
+```ts
+await Assets.unloadBundle("level1");
+// level1 sprites still on the stage; they now reference destroyed textures
+```
+
+Correct:
+
+```ts
+level1Container.destroy({ children: true });
+await Assets.unloadBundle("level1");
+```
+
+Always destroy (or detach from the scene) any display objects that reference the bundle's textures before unloading. Otherwise the renderer hits freed GPU memory and errors.
+
+
+### [MEDIUM] Confusing `addBundle` and `init` manifests
+
+Wrong:
+
+```ts
+await Assets.init();
+Assets.addBundle('ui', [...]);
+await Assets.loadBundle('ui');
+```
+
+Both work; this is not actually wrong; but a manifest passed to `Assets.init({ manifest: {...} })` registers all bundles at init time in one place. Prefer manifests when you know all bundles upfront; prefer `addBundle` when bundles are discovered dynamically at runtime.
+
+
+## API Reference
+
+- [Assets](https://pixijs.download/release/docs/assets.Assets.html.md)
+- [AssetsBundle](https://pixijs.download/release/docs/assets.AssetsBundle.html.md)
+- [Resolver](https://pixijs.download/release/docs/assets.Resolver.html.md)

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

@@ -0,0 +1,143 @@
+# Caching
+
+Every asset loaded through `Assets` is cached until you explicitly unload it. The cache is a global singleton keyed by the resolved URL, alias, and any bundle identifier. Use the cache to avoid double-loading, retrieve loaded assets synchronously, and reclaim GPU memory when an asset is no longer needed.
+
+## Quick Start
+
+```ts
+await Assets.load("hero.png");
+
+const cached = Assets.get("hero.png");
+const sprite = new Sprite(cached);
+
+await Assets.unload("hero.png");
+```
+
+`Assets.load` adds the asset to the cache; `Assets.get` retrieves it synchronously; `Assets.unload` removes it and releases the underlying GPU resource.
+
+## Core Patterns
+
+### Synchronous access to already-loaded assets
+
+```ts
+await Assets.load(["hero.png", "enemy.png"]);
+
+const hero = Assets.get("hero");
+const enemy = Assets.get("enemy");
+
+if (hero) {
+  app.stage.addChild(new Sprite(hero));
+}
+```
+
+`Assets.get(alias)` returns `undefined` if the asset has not been loaded yet. It is synchronous; use it in tight loops or anywhere `await` would be awkward.
+
+### Multiple keys at once
+
+```ts
+await Assets.load(["hero", "enemy", "boss"]);
+
+const all = Assets.get(["hero", "enemy", "boss"]);
+const heroTex = all["hero"];
+```
+
+Passing an array returns an object keyed by alias. Useful for retrieving all the assets a scene needs in one call.
+
+### Deduping load calls
+
+```ts
+const tex1 = await Assets.load("hero.png");
+const tex2 = await Assets.load("hero.png");
+console.log(tex1 === tex2); // true
+```
+
+Calling `Assets.load` with the same key multiple times returns the same cached result immediately on subsequent calls. Safe to call from multiple async functions concurrently.
+
+### Unloading
+
+```ts
+sprite.destroy();
+await Assets.unload("hero.png");
+```
+
+`Assets.unload(id)` removes the asset from the cache, calls `destroy()` on the texture (releasing GPU memory), and removes any loader-specific wrappers. Always destroy or detach display objects that reference the asset before unloading, or you'll hit freed GPU memory.
+
+### Unloading a bundle
+
+```ts
+level1Container.destroy({ children: true });
+await Assets.unloadBundle("level1");
+```
+
+Prefer `unloadBundle` over manually iterating. It has no reference counting: every asset in the bundle is removed from the cache and destroyed, even if another bundle declares the same `src`, and that bundle's alias stays broken until you reload it. Detach anything on the scene that still uses those assets first.
+
+### Inspecting the cache
+
+```ts
+import { Cache } from "pixi.js";
+
+const key = "hero.png";
+if (Cache.has(key)) {
+  const texture = Cache.get(key);
+}
+```
+
+The low-level `Cache` class backs `Assets.get`. It exposes `has(key)`, `get(key)`, `set(key, value)`, and `remove(key)`. Most code should go through `Assets.get/unload` instead, but direct `Cache` access is useful for diagnostics or custom loader plugins.
+
+## Common Mistakes
+
+### [CRITICAL] Using `Assets.get` before `Assets.load`
+
+Wrong:
+
+```ts
+const texture = Assets.get("hero.png");
+const sprite = new Sprite(texture); // texture is undefined
+```
+
+Correct:
+
+```ts
+await Assets.load("hero.png");
+const texture = Assets.get("hero.png");
+const sprite = new Sprite(texture);
+```
+
+`Assets.get` is synchronous and returns `undefined` if the asset hasn't been loaded yet. Always await `Assets.load` first, or use the return value of `Assets.load` directly.
+
+
+### [HIGH] Not unloading between levels
+
+Textures stay in the cache indefinitely. A game that loads level after level without calling `Assets.unload` or `Assets.unloadBundle` slowly accumulates GPU memory until it hits browser limits.
+
+```ts
+await Assets.unloadBundle("level1");
+await Assets.loadBundle("level2");
+```
+
+
+### [MEDIUM] Using sprites after unload
+
+Wrong:
+
+```ts
+const sprite = new Sprite(texture);
+await Assets.unload("hero.png");
+// sprite still references the destroyed texture
+```
+
+Correct:
+
+```ts
+sprite.destroy();
+await Assets.unload("hero.png");
+```
+
+`Assets.unload` destroys the underlying texture. Any sprite still referencing it will render Texture.EMPTY or crash depending on the backend. Destroy the leaf (or reassign its texture) before unloading.
+
+
+## API Reference
+
+- [Assets](https://pixijs.download/release/docs/assets.Assets.html.md)
+- [Cache](https://pixijs.download/release/docs/assets.Cache.html.md)
+- [Texture](https://pixijs.download/release/docs/rendering.Texture.html.md)

package/vendor/pixijs-skills/skills/pixijs-assets/references/compressed-textures.md

@@ -0,0 +1,120 @@
+# Compressed Textures
+
+GPU-compressed texture formats (DDS, KTX, KTX2, Basis) use 4–8x less GPU memory than PNG/JPEG and skip runtime decoding. Use them for large textures, high-asset-count games, and anywhere memory budget matters. Each format requires a side-effect import to register its loader.
+
+## Quick Start
+
+```ts
+import "pixi.js/ktx2";
+import { Assets, Sprite } from "pixi.js";
+
+const texture = await Assets.load("background.ktx2");
+
+const bg = new Sprite(texture);
+app.stage.addChild(bg);
+```
+
+Without the side-effect import, the loader won't know how to parse the file and will skip it silently.
+
+## Core Patterns
+
+### Format imports
+
+```ts
+import "pixi.js/dds"; // DirectDraw Surface (.dds)
+import "pixi.js/ktx"; // KTX (Khronos Texture) v1
+import "pixi.js/ktx2"; // KTX v2 (with Basis Universal support)
+import "pixi.js/basis"; // Basis Universal (.basis)
+```
+
+Each import registers a `LoaderParser` that can decode the matching file extension. Import only the formats you use; the loaders include decoder runtime that adds to your bundle size.
+
+### Format selection matrix
+
+| Format | Platforms | Notes                                                                                                           |
+| ------ | --------- | --------------------------------------------------------------------------------------------------------------- |
+| DDS    | All       | Legacy desktop formats (DXT, BC). Fast decoder; wide support.                                                   |
+| KTX    | All       | Older Khronos container. Prefer KTX2 for new projects.                                                          |
+| KTX2   | All       | Newer container; typically used with Basis Universal. GPU-native when available.                                |
+| Basis  | All       | Supercompressed; transcodes to the GPU-native format at load time. Best for "one file, any platform" workflows. |
+
+Use KTX2 + Basis for new projects unless you have a specific need for one of the others.
+
+### With the resolver
+
+```ts
+import "pixi.js/ktx2";
+import { Assets } from "pixi.js";
+
+Assets.add({
+  alias: "background",
+  src: "background.{ktx2,webp,png}",
+});
+
+const texture = await Assets.load("background");
+```
+
+List compressed textures as first-preference format in the resolver. On browsers or hardware that can't sample the compressed format, the resolver falls back to WebP or PNG automatically.
+
+### Async decoding
+
+```ts
+import "pixi.js/basis";
+import { Assets } from "pixi.js";
+
+const texture = await Assets.load("hero.basis");
+```
+
+Basis Universal decodes asynchronously on a worker thread (where supported). You don't need to await anything beyond the normal `Assets.load`; the loader handles decoding.
+
+### Multiple compressed formats at once
+
+```ts
+import "pixi.js/ktx2";
+import "pixi.js/basis";
+import "pixi.js/dds";
+```
+
+Multiple format imports can coexist. Each registers an extension for its own file type. If you only use one format, import only that one to keep the bundle smaller.
+
+## Common Mistakes
+
+### [CRITICAL] Missing the format import
+
+Wrong:
+
+```ts
+import { Assets } from "pixi.js";
+await Assets.load("background.ktx2");
+```
+
+Correct:
+
+```ts
+import "pixi.js/ktx2";
+import { Assets } from "pixi.js";
+await Assets.load("background.ktx2");
+```
+
+Without the side-effect import, no loader parser is registered for `.ktx2` files. The load silently does nothing (or errors) and you get `undefined` back.
+
+
+### [HIGH] Relying on mipmaps from compressed textures in Canvas2D
+
+Compressed textures require WebGL or WebGPU. The Canvas2D backend can't sample them. If you need Canvas support, include a PNG/WebP fallback via the resolver format list:
+
+```ts
+Assets.add({ alias: "bg", src: "bg.{ktx2,png}" });
+```
+
+
+### [MEDIUM] Large Basis files in WebGL1
+
+Basis Universal transcodes to different GPU formats based on what the device supports. On WebGL1 without extensions, some devices fall back to an uncompressed format, defeating the memory savings. Check `renderer.context.supports` for supported compressed formats if you're targeting older hardware.
+
+
+## API Reference
+
+- [Assets](https://pixijs.download/release/docs/assets.Assets.html.md)
+- [loadKTX2](https://pixijs.download/release/docs/assets.loadKTX2.html.md)
+- [TextureSource](https://pixijs.download/release/docs/rendering.TextureSource.html.md)