@docyrus/animaguru 0.6.0

package/vendor/pixijs-skills/skills/pixijs-scene-text/references/bitmap-text.md

@@ -0,0 +1,232 @@
+# BitmapText
+
+Text rendered from a pre-generated texture atlas of glyphs. Updating the text string only repositions quads; no canvas re-render, no GPU upload per change. Use `BitmapText` for scores, timers, gameplay labels, and any text whose content changes frequently. Trade-off: limited styling, fixed glyph set, pixel-perfect only at the font's native size (unless you use MSDF).
+
+## Quick Start
+
+```ts
+const score = new BitmapText({
+  text: "Score: 0",
+  style: {
+    fontFamily: "Arial",
+    fontSize: 32,
+    fill: 0xffffff,
+  },
+});
+
+app.stage.addChild(score);
+
+app.ticker.add(() => {
+  score.text = `Score: ${Math.floor(performance.now() / 100)}`;
+});
+```
+
+When you pass a system font family without calling `BitmapFont.install`, the text-bitmap system generates a dynamic bitmap font on first use.
+
+## Construction
+
+```ts
+const minimal = new BitmapText({ text: "Score: 0" });
+
+const styled = new BitmapText({
+  text: "Hello",
+  style: { fontFamily: "GameFont", fontSize: 48, fill: 0xff0000 },
+  anchor: 0.5,
+  roundPixels: true,
+});
+```
+
+### BitmapTextOptions
+
+`BitmapText`'s constructor accepts the base `TextOptions` directly (no additional bitmap-specific fields). Fields match `references/text.md` with two caveats: `style` is still `TextStyle \| TextStyleOptions` (the same class `Text` uses, but many style fields are ignored by the bitmap pipeline), and `resolution` is managed by the underlying `BitmapFont` at install time rather than per-instance.
+
+| Option        | Type                            | Default                                  | Description                                                                                                                                                                                                                                      |
+| ------------- | ------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `text`        | `TextString`                    | `''`                                     | Text content. Same as `Text`.                                                                                                                                                                                                                    |
+| `style`       | `TextStyle \| TextStyleOptions` | `new TextStyle()` with `fill = 0xffffff` | Shared TextStyle type; fields like `fontFamily`, `fontSize`, `fill`, `stroke`, `align`, `wordWrap`, `wordWrapWidth`, and `lineHeight` are respected. Gradients as fill and filters are not. See the TextStyle reference in `references/text.md`. |
+| `anchor`      | `PointData \| number`           | `0`                                      | Same as `Text`.                                                                                                                                                                                                                                  |
+| `resolution`  | `number \| null`                | `null`                                   | Accepted but ignored at runtime — set resolution on the `BitmapFont` via `BitmapFont.install({ resolution })` instead. Passing a non-null value logs a warning.                                                                                  |
+| `roundPixels` | `boolean`                       | `false`                                  | Same as `Text`.                                                                                                                                                                                                                                  |
+
+All `Container` options (`position`, `scale`, `tint`, `label`, `filters`, `zIndex`, etc.) are also valid here — see `skills/pixijs-scene-core-concepts/references/constructor-options.md`.
+
+> `BitmapText` does NOT accept `textureStyle` or `autoGenerateMipmaps`; those are specific to canvas `Text` and `HTMLText`. The atlas texture style is controlled when installing the font via `BitmapFont.install({ textureStyle })`.
+
+## Core Patterns
+
+### Dynamic fonts (system font -> runtime atlas)
+
+```ts
+const dynamic = new BitmapText({
+  text: "Hello",
+  style: { fontFamily: "Arial", fontSize: 32, fill: 0xff1010 },
+});
+```
+
+The first `BitmapText` with a given `fontFamily` + `fontSize` generates an atlas lazily. Subsequent `BitmapText` instances reuse it. The system also scales an existing close-match size rather than re-generating.
+
+### Pre-installed fonts
+
+```ts
+import { BitmapFont } from "pixi.js";
+
+BitmapFont.install({
+  name: "GameFont",
+  style: {
+    fontFamily: "Arial",
+    fontSize: 48,
+    fill: 0xffffff,
+    stroke: { color: "#000000", width: 2 },
+  },
+});
+
+const title = new BitmapText({
+  text: "Level 1",
+  style: { fontFamily: "GameFont", fontSize: 48, fill: 0x00ff00 },
+});
+```
+
+`BitmapFont.install` pre-generates an atlas so the first `BitmapText` render has no setup cost. Useful for known fixed styles in a game.
+
+#### Install options
+
+| Option         | Purpose                                                                                                                                                                                                                                               |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `chars`        | Character set to pre-render. Accepts a string, nested ranges, or a preset: `BitmapFontManager.ALPHA`, `BitmapFontManager.NUMERIC`, `BitmapFontManager.ALPHANUMERIC`, `BitmapFontManager.ASCII`. Essential for non-ASCII, CJK, or restricted charsets. |
+| `resolution`   | Texture atlas resolution. Default `1`. Use `window.devicePixelRatio` for HiDPI displays.                                                                                                                                                              |
+| `padding`      | Glyph padding inside the atlas. Default `4`. Raise to avoid bleeding at large scales.                                                                                                                                                                 |
+| `skipKerning`  | Skip kerning metadata to save memory and install time. Default `false`.                                                                                                                                                                               |
+| `textureStyle` | `TextureStyle`/`TextureStyleOptions` override for the generated atlas (for example `{ scaleMode: 'nearest' }` for pixel fonts).                                                                                                                       |
+| `dynamicFill`  | Allow runtime tinting via `BitmapText.tint`. Requires the font `style.fill` to be white, no stroke, no drop shadow, or a drop shadow with color `0x000000` (black). The idiomatic way to color bitmap text without generating a new atlas per color.  |
+
+```ts
+import { BitmapFont, BitmapFontManager } from "pixi.js";
+
+BitmapFont.install({
+  name: "UIFont",
+  chars: BitmapFontManager.ALPHANUMERIC,
+  resolution: window.devicePixelRatio,
+  padding: 8,
+  skipKerning: true,
+  textureStyle: { scaleMode: "nearest" },
+  dynamicFill: true,
+  style: { fontFamily: "Arial", fontSize: 32, fill: 0xffffff },
+});
+
+const hp = new BitmapText({
+  text: "100",
+  style: { fontFamily: "UIFont", fill: "red" },
+});
+const mp = new BitmapText({
+  text: "50",
+  style: { fontFamily: "UIFont", fill: "blue" },
+});
+```
+
+### Loaded bitmap fonts (FNT / XML)
+
+```ts
+import "pixi.js/text-bitmap";
+import { Assets, BitmapText } from "pixi.js";
+
+await Assets.load("fonts/arcade.fnt");
+
+const arcade = new BitmapText({
+  text: "HIGH SCORE",
+  style: { fontFamily: "arcade", fontSize: 36 },
+});
+```
+
+Load `.fnt` or `.xml` files (AngelCode BMFont format) via Assets. Generate them from a `.ttf` / `.otf` with [AssetPack](https://pixijs.io/assetpack/). The side-effect import `'pixi.js/text-bitmap'` registers the loader; required for custom builds that set `skipExtensionImports: true`.
+
+### MSDF / SDF fonts for crisp scaling
+
+Multi-channel Signed Distance Field (MSDF) fonts stay sharp at any size. Generate them with [AssetPack](https://pixijs.io/assetpack/) (Pixi's own asset pipeline, which takes a `.ttf` or `.otf` and emits the `.fnt` + atlas) or [msdf-bmfont](https://msdf-bmfont.donmccurdy.com/). Load them via Assets; they're detected automatically when the FNT file declares a distanceField section.
+
+```ts
+await Assets.load("fonts/msdf-hero.fnt");
+
+const heading = new BitmapText({
+  text: "Title",
+  style: { fontFamily: "msdf-hero", fontSize: 120 },
+});
+
+heading.scale.set(2);
+```
+
+MSDF fonts trade CPU rendering time for a custom fragment shader, but remain crisp when scaled up or down.
+
+### Word wrap
+
+```ts
+const paragraph = new BitmapText({
+  text: "A long wrapped paragraph of bitmap text",
+  style: {
+    fontFamily: "Arial",
+    fontSize: 24,
+    wordWrap: true,
+    wordWrapWidth: 300,
+    lineHeight: 30,
+  },
+});
+```
+
+Standard TextStyle wrapping properties work. Line-height and alignment (`align: 'center' | 'left' | 'right'`) apply to wrapped output.
+
+### Updating content
+
+```ts
+score.text = `Score: ${value}`;
+```
+
+Updates reposition glyph quads only. No canvas re-draw, no GPU upload. This is why `BitmapText` is the right choice for every-frame text updates.
+
+## Common Mistakes
+
+### [HIGH] Not importing `pixi.js/text-bitmap` in custom builds
+
+Wrong (custom build with `skipExtensionImports: true`):
+
+```ts
+import { Assets } from "pixi.js";
+await Assets.load("font.fnt");
+```
+
+Correct:
+
+```ts
+import "pixi.js/text-bitmap";
+import { Assets } from "pixi.js";
+await Assets.load("font.fnt");
+```
+
+Without the side-effect import, `.fnt` and `.xml` files aren't recognized by the asset loader; the call silently succeeds but returns raw data instead of a `BitmapFont`.
+
+
+### [MEDIUM] Setting `resolution` on BitmapText
+
+Wrong:
+
+```ts
+text.resolution = 2;
+```
+
+`BitmapText` ignores `resolution` and logs a warning. The effective resolution is baked into the `BitmapFont` at install time. To get higher resolution, install the font with a larger `fontSize` and scale the text down.
+
+
+### [MEDIUM] Missing characters silently dropped
+
+If the font atlas doesn't contain a glyph (e.g., a rare Unicode character), the glyph is silently skipped with no visible error. Text may appear incomplete. For unknown or user-generated content, fall back to canvas `Text` or `HTMLText`.
+
+
+### [HIGH] Using BitmapText for CJK or emoji-heavy content
+
+CJK (Chinese/Japanese/Korean), Arabic, and emoji-heavy strings need thousands of glyphs. A bitmap atlas containing all of them exceeds GPU texture-size limits. Use `Text` or `HTMLText` for text with unpredictable or very large character sets.
+
+
+## API Reference
+
+- [BitmapText](https://pixijs.download/release/docs/scene.BitmapText.html.md)
+- [BitmapFont](https://pixijs.download/release/docs/text.BitmapFont.html.md)
+- [BitmapFontManager](https://pixijs.download/release/docs/text.BitmapFontManager.html.md)
+- [AbstractBitmapFont](https://pixijs.download/release/docs/text.AbstractBitmapFont.html.md)

package/vendor/pixijs-skills/skills/pixijs-scene-text/references/html-text.md

@@ -0,0 +1,192 @@
+# HTMLText
+
+Text rendered via an SVG `<foreignObject>` wrapping an HTML fragment. This gives you the full HTML/CSS box model for typography; real `<b>`, `<i>`, `<br>`, `<div>`, line-breaks, nested styles, emoji; rasterized to a texture. Use `HTMLText` for rich formatting, mixed content, inline custom tags, or markup that the canvas `Text` class can't express.
+
+## Quick Start
+
+```ts
+const rich = new HTMLText({
+  text: "<b>Bold</b> and <i>italic</i> text",
+  style: {
+    fontFamily: "Arial",
+    fontSize: 24,
+    fill: 0x333333,
+    wordWrap: true,
+    wordWrapWidth: 400,
+  },
+});
+
+app.stage.addChild(rich);
+```
+
+`HTMLText` is a leaf. It uses `HTMLTextStyle`, which is `TextStyle` minus `leading`, `textBaseline`, `trim`, and `filters` (those four are unsupported by the SVG rendering path). Rendering is asynchronous; the text may not appear on the same frame it's created.
+
+## Construction
+
+```ts
+const minimal = new HTMLText({ text: "<b>Hello</b>" });
+
+const styled = new HTMLText({
+  text: "<i>Styled</i>",
+  style: { fontSize: 24, fill: 0xffffff },
+  anchor: 0.5,
+  resolution: 2,
+  autoGenerateMipmaps: true,
+  textureStyle: { scaleMode: "linear" },
+});
+```
+
+### HTMLTextOptions
+
+`HTMLText` extends the base `TextOptions` (typed with `HTMLTextStyle` / `HTMLTextStyleOptions` as its style) and adds HTML-specific fields. Inherited `text`, `style`, `anchor`, `resolution`, and `roundPixels` behave as documented in `references/text.md` — only the HTMLText-specific additions are listed here.
+
+| Option                | Type                                    | Default                                            | Description                                                                                                                                               |
+| --------------------- | --------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `style`               | `HTMLTextStyle \| HTMLTextStyleOptions` | `new HTMLTextStyle()`                              | HTML text style object or options. Matches `TextStyle` minus `leading`, `textBaseline`, `trim`, and `filters`. Adds `cssOverrides` for raw CSS injection. |
+| `textureStyle`        | `TextureStyle \| TextureStyleOptions`   | `undefined`                                        | Scale mode for the generated texture (`nearest` or `linear`); every other `TextureStyle` field is ignored. (@advanced)                                    |
+| `autoGenerateMipmaps` | `boolean`                               | `TextureSource.defaultOptions.autoGenerateMipmaps` | Generate mipmaps for the text texture; improves quality when scaled down.                                                                                 |
+
+All base text options (`text`, `anchor`, `resolution`, `roundPixels`) are inherited from `TextOptions` — see `references/text.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`.
+
+> Both `textureStyle` and `autoGenerateMipmaps` are also exposed as runtime instance properties, but they are only read when a new texture is generated for the text (a text, style or resolution change); `onViewUpdate()` alone does not regenerate it.
+
+## Core Patterns
+
+### Custom tags via `tagStyles`
+
+```ts
+const message = new HTMLText({
+  text: "<warning>Low power</warning> <custom>Press any key</custom>",
+  style: {
+    fontFamily: "Arial",
+    fontSize: 28,
+    fill: 0xffffff,
+    tagStyles: {
+      warning: { fill: 0xff3333, fontWeight: "bold" },
+      custom: { fill: 0x66ccff, fontStyle: "italic" },
+    },
+  },
+});
+```
+
+`tagStyles` maps custom (or standard) HTML tag names to style overrides. Inherit is automatic; a nested `<warning>` inside `<custom>` inherits the outer style. Standard tags like `<b>`, `<i>`, `<u>`, `<br>` work as expected.
+
+### Raw CSS overrides
+
+```ts
+const styled = new HTMLText({
+  text: "Underlined shadowed text",
+  style: { fontSize: 24, fill: 0xffffff },
+});
+
+styled.style.addOverride("text-decoration: underline");
+styled.style.addOverride("text-shadow: 2px 2px 4px rgba(0,0,0,0.5)");
+```
+
+For CSS properties without a `TextStyle` equivalent, use `addOverride` to inject raw CSS. Useful for `text-decoration`, `text-transform`, `letter-spacing` beyond what TextStyle exposes, and any other CSS property supported inside SVG `<foreignObject>`.
+
+### Word wrap
+
+```ts
+const wrapped = new HTMLText({
+  text: "A long paragraph of HTML text that should wrap automatically",
+  style: {
+    fontFamily: "Arial",
+    fontSize: 20,
+    fill: 0xffffff,
+    wordWrap: true,
+    wordWrapWidth: 300,
+    align: "center",
+  },
+});
+```
+
+Word wrap is handled by the browser's SVG layout, so it supports everything CSS wrapping supports; including hyphenation, justification, and RTL scripts when the font and the rendered CSS support them.
+
+### Resolution and mipmaps
+
+```ts
+const crisp = new HTMLText({
+  text: "Retina crisp",
+  style: { fontSize: 32, fill: 0xffffff },
+  resolution: 2,
+  autoGenerateMipmaps: true,
+});
+```
+
+Same pattern as canvas `Text`: `resolution` controls the rasterized texture density; `autoGenerateMipmaps` improves quality when drawn smaller than native.
+
+### Async rendering
+
+```ts
+const htmlText = new HTMLText({
+  text: "Initial content",
+  style: { fontSize: 24, fill: 0xffffff },
+});
+htmlText.visible = false;
+app.stage.addChild(htmlText);
+
+app.ticker.addOnce(() => {
+  htmlText.visible = true;
+});
+```
+
+HTMLText renders to an SVG blob, then a texture. The texture is available one frame after creation. If you need the text ready before showing it, add it while hidden and reveal it on the next tick.
+
+## Common Mistakes
+
+### [HIGH] Updating HTMLText content every frame
+
+Wrong:
+
+```ts
+app.ticker.add(() => {
+  htmlText.text = `Score: ${score}`;
+});
+```
+
+Correct:
+
+```ts
+const bitmap = new BitmapText({ text: "Score: 0", style });
+app.ticker.add(() => {
+  bitmap.text = `Score: ${score}`;
+});
+```
+
+Each `HTMLText.text` assignment re-renders the SVG, rasterizes it, and uploads to the GPU. At 60fps this is far too expensive. Use `BitmapText` for any text that changes per-frame.
+
+
+### [HIGH] Missing CORS headers on fonts
+
+If the HTML references a web font loaded from a different origin without CORS headers, the SVG `<foreignObject>` is tainted and the rasterization fails (or falls back to a default font). Host fonts on the same origin or include `Access-Control-Allow-Origin`.
+
+
+### [MEDIUM] Expecting HTMLText frame on creation
+
+Wrong:
+
+```ts
+const text = new HTMLText({ text: "Hello", style });
+text.x = (app.screen.width - text.width) / 2; // text.width is 0 here
+```
+
+Correct:
+
+```ts
+const text = new HTMLText({ text: "Hello", style });
+app.ticker.addOnce(() => {
+  text.x = (app.screen.width - text.width) / 2;
+});
+```
+
+HTMLText measurement happens asynchronously. Defer layout calculations to the next frame, or use canvas `Text` when you need immediate metrics.
+
+
+## API Reference
+
+- [HTMLText](https://pixijs.download/release/docs/scene.HTMLText.html.md)
+- [HTMLTextStyle](https://pixijs.download/release/docs/text.HTMLTextStyle.html.md)
+- [HTMLTextSystem](https://pixijs.download/release/docs/rendering.HTMLTextSystem.html.md)

package/vendor/pixijs-skills/skills/pixijs-scene-text/references/split-bitmap-text.md

@@ -0,0 +1,187 @@
+# SplitBitmapText (experimental)
+
+The bitmap counterpart to `SplitText`. Wraps a `BitmapText` and exposes `lines`, `words`, and `chars` as independently-animatable containers. Use `SplitBitmapText` when you want per-character animation on long strings, many simultaneous instances, or text that changes frequently; scenarios where `SplitText`'s per-char canvas rasterization would be too expensive.
+
+## Quick Start
+
+```ts
+import { BitmapFont, SplitBitmapText } from "pixi.js";
+
+BitmapFont.install({
+  name: "GameFont",
+  style: { fontFamily: "Arial", fontSize: 48 },
+});
+
+const split = new SplitBitmapText({
+  text: "Fast Animate",
+  style: { fontFamily: "GameFont", fontSize: 48 },
+  charAnchor: { x: 0.5, y: 1 },
+});
+
+app.stage.addChild(split);
+
+split.chars.forEach((char, i) => {
+  char.onRender = () => {
+    const t = performance.now() / 200 + i;
+    char.y = Math.sin(t) * 5;
+  };
+});
+```
+
+The API mirrors `SplitText` exactly; the only difference is the underlying text engine. Install a bitmap font (or load one from a `.fnt` file) before creating the instance.
+
+## Construction
+
+```ts
+const minimal = new SplitBitmapText({
+  text: "Hello World",
+  style: { fontFamily: "GameFont", fontSize: 32 },
+});
+
+const full = new SplitBitmapText({
+  text: "Fast\nPer-char",
+  style: { fontFamily: "GameFont", fontSize: 48, fill: 0xffffff },
+  autoSplit: true,
+  lineAnchor: 0.5,
+  wordAnchor: { x: 0, y: 0.5 },
+  charAnchor: { x: 0.5, y: 1 },
+  x: 100,
+  y: 200,
+});
+```
+
+### SplitBitmapTextOptions
+
+`SplitBitmapText` uses the same option shape as `SplitText`: all splitting fields are inherited from `AbstractSplitOptions`, and the only concrete difference is that `style` drives a `BitmapText` render instead of a `Text` render. Like `SplitText`, it is a `Container`, not a `ViewContainer`; the top-level options do NOT include `anchor`, `resolution`, `roundPixels`, `textureStyle`, or `autoGenerateMipmaps`.
+
+| Option       | Type                                     | Default | Description                                                                                                                                                                                    |
+| ------------ | ---------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `text`       | `string`                                 | —       | Text content to render and segment. Required.                                                                                                                                                  |
+| `style`      | `TextStyle \| Partial<TextStyleOptions>` | —       | TextStyle instance or style options; `fill` defaults to `0xffffff` when unset, matching `BitmapText`. See `references/bitmap-text.md` for which fields the bitmap pipeline respects. Required. |
+| `autoSplit`  | `boolean`                                | `true`  | Automatically re-split when `text` or `style` changes; set `false` to batch updates and call `split.split()` manually.                                                                         |
+| `lineAnchor` | `number \| PointData`                    | `0`     | Normalized transform origin (0–1) for each line container.                                                                                                                                     |
+| `wordAnchor` | `number \| PointData`                    | `0`     | Normalized transform origin for each word container.                                                                                                                                           |
+| `charAnchor` | `number \| PointData`                    | `0`     | Normalized transform origin for each character container.                                                                                                                                      |
+
+All `Container` options (`position`, `scale`, `tint`, `label`, `filters`, `zIndex`, etc.) are also valid here — see `skills/pixijs-scene-core-concepts/references/constructor-options.md`.
+
+> `SplitBitmapText.defaultOptions` overrides the defaults globally for every new `SplitBitmapText` instance. `SplitBitmapText.from(existingBitmapText, options?)` builds an instance by cloning the source's text and style — `tagStyles` on the source are discarded (bitmap text does not support them) and a warning is logged.
+
+## Core Patterns
+
+### Segment access
+
+```ts
+split.lines.forEach((line) => {
+  line.alpha = 0.9;
+});
+split.words.forEach((word) => {
+  word.scale.set(1.1);
+});
+split.chars.forEach((char) => {
+  char.rotation = 0.05;
+});
+```
+
+Each `lines[i]`, `words[i]`, `chars[i]` is a Container wrapping a `BitmapText` instance for that segment. BitmapText glyph quads are cheap, so iterating and transforming hundreds of characters stays performant.
+
+### Transform origins
+
+```ts
+const split = new SplitBitmapText({
+  text: "Wave motion",
+  style: { fontFamily: "GameFont", fontSize: 48 },
+  lineAnchor: 0.5,
+  wordAnchor: { x: 0, y: 0.5 },
+  charAnchor: { x: 0.5, y: 1 },
+});
+```
+
+Same normalized 0–1 anchors as `SplitText`: line, word, and char containers each get a separate transform origin. Set once at construction; the anchors apply to every future re-split.
+
+### Stagger animation
+
+```ts
+split.chars.forEach((char, i) => {
+  char.alpha = 0;
+});
+
+let elapsed = 0;
+app.ticker.add((ticker) => {
+  elapsed += ticker.deltaMS;
+  split.chars.forEach((char, i) => {
+    if (elapsed > i * 50) char.alpha = Math.min(char.alpha + 0.05, 1);
+  });
+});
+```
+
+Reveal characters one at a time. Because each char is a cheap BitmapText, this scales to long strings without dropping frames.
+
+### Constructing from an existing BitmapText
+
+```ts
+const label = new BitmapText({
+  text: "Press start",
+  style: { fontFamily: "GameFont", fontSize: 32 },
+});
+
+const animatable = SplitBitmapText.from(label);
+```
+
+`SplitBitmapText.from(existingBitmapText)` copies content and style, then splits. Useful for attaching per-character animation to a text that was already laid out elsewhere.
+
+### Updating content
+
+```ts
+split.text = "New string";
+```
+
+`autoSplit` (default `true`) rebuilds the segment arrays on every text/style change. Per-segment animations attached via `onRender` persist across re-splits as long as you re-apply them in the update step.
+
+## Common Mistakes
+
+### [HIGH] Using SplitBitmapText without a BitmapFont
+
+Wrong:
+
+```ts
+const split = new SplitBitmapText({
+  text: "Hello",
+  style: { fontFamily: "Arial", fontSize: 48 },
+});
+```
+
+The above works; dynamic bitmap fonts auto-generate; but for known game fonts prefer pre-installing:
+
+Correct:
+
+```ts
+BitmapFont.install({
+  name: "GameFont",
+  style: { fontFamily: "Arial", fontSize: 48 },
+});
+const split = new SplitBitmapText({
+  text: "Hello",
+  style: { fontFamily: "GameFont", fontSize: 48 },
+});
+```
+
+Pre-installation avoids first-render latency and gives you control over the atlas.
+
+
+### [MEDIUM] Expecting CJK or emoji support
+
+`SplitBitmapText` inherits BitmapText's limitations: the glyph atlas must contain every character, and very large character sets exceed GPU texture size. For per-character animation on CJK or emoji-heavy text, use `SplitText` (which accepts the performance cost) or pre-generate a targeted atlas covering only the characters you'll use.
+
+
+### [MEDIUM] Missing glyphs silently dropped
+
+If a character isn't in the font atlas, its segment is skipped and no error is thrown. Array indices may not line up one-to-one with source character positions if glyphs are missing. Always test your font against the full string content.
+
+
+## API Reference
+
+- [SplitBitmapText](https://pixijs.download/release/docs/text.SplitBitmapText.html.md)
+- [AbstractSplitText](https://pixijs.download/release/docs/text.AbstractSplitText.html.md)
+- [BitmapText](https://pixijs.download/release/docs/scene.BitmapText.html.md)
+- [BitmapFont](https://pixijs.download/release/docs/text.BitmapFont.html.md)