SKILL.md
$28
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:
app.ticker.add(() => {
scoreText.text = Score: ${score};
});
Correct:
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:
const text = new Text("Hello", { fontSize: 24 });
Correct:
const text = new Text({ text: "Hello", style: { fontSize: 24 } });