API Reference

npm install funky-pixi-text pixi.js

import { Application, Assets } from "pixi.js";
import { Text, FontLoader } from "funky-pixi-text";

const app = new Application({ backgroundColor: 0x222222, resizeTo: window });
document.body.appendChild(app.view as HTMLCanvasElement);

// Load an MSDF font (atlas .png + bmfont .json)
await Assets.load({
  src: "fonts/Roboto-Black.json",
  loadParser: FontLoader.name,
});

const label = new Text("Hello MSDF!", {
  fontName: "Roboto-Black",
  fontSize: 96,
  color: 0xffffff,
  align: "center",
  anchorX: 0.5,
  anchorY: 0.5,
});

label.position.set(app.screen.width / 2, app.screen.height / 2);
app.stage.addChild(label);

npm i -g msdf-bmfont-xml
msdf-bmfont -f json -o Roboto-Black --font-size 64 ./Roboto-Black.ttf

type TextStyle = {
  fontName: string;          // REQUIRED — key used when font was loaded
  fontSize?: number;         // default 16 (logical pixels)
  color?: number | TextStyleGradient; // 0xRRGGBB or gradient object; default 0xffffff

  // Layout
  align?: "left" | "center" | "right" | "justify"; // default "left"
  anchorX?: number;          // 0..1 (0 = left, 0.5 = center, 1 = right); default 0
  anchorY?: number;          // 0..1 (0 = top,  0.5 = middle, 1 = bottom); default 0
  wordWrap?: boolean;        // default false
  breakWords?: boolean;      // with wordWrap, split words wider than maxWidth
                             // mid-word instead of overflowing; default false
  maxWidth?: number;         // pixels, used with wordWrap and/or autoScale; default Infinity
  maxHeight?: number;        // pixels, used with autoScale; default Infinity
  autoScale?: boolean;       // shrink fontSize to fit maxWidth/maxHeight; default false
  leading?: number;          // extra px added to line height
  lineHeight?: number;       // override line height in pixels (0 = use font default)
  letterSpacing?: number;    // px added between characters
  kerning?: boolean;         // default true
  kerningScale?: number;     // multiplier for kerning amount; default 1.0

  // Effects
  stroke?: TextStyleStroke | null;
  dropShadow?: TextStyleDropShadow | null;
  extrude?: TextStyleExtrude | null;
  fillTexture?: TextStyleTextureFill | null;

  // Rendering
  smoothing?: number;        // edge AA half-width (0.05..5.0); default 0.02
  scale?: number;            // visual multiplier; default 1.0
  msdfSign?: number;         // 1 or -1; flip signed distance (rare)

  // Performance
  performanceMode?: "auto" | "high-quality" | "balanced" | "mobile-optimized";
  performanceConfig?: PerformanceConfig;
};

type TextStyleGradient = {
  type: "linear" | "circular";
  colors: number[];                       // 0xRRGGBB array (up to maxGradientStops)
  alphas?: number[];                      // matching per-stop alphas (0..1)
  stops?: number[];                       // matching positions (0..1)
  angle?: number;                         // degrees, linear only
  center?: { x: number; y: number };      // circular only, 0..1 in glyph space
  radius?: number;                        // circular only, 0..1; <=0 = auto
};

type TextStyleStroke = {
  color: number;       // 0xRRGGBB
  width: number;       // 0..10 (px in MSDF distance units)
  smoothing?: number;  // 0..10, default 1.0
};

type TextStyleDropShadow = {
  color: number;     // 0xRRGGBB
  angle: number;     // degrees
  distance: number;  // px
  blur: number;      // 0..30 (clamped by performance config)
  alpha?: number;    // 0..1, default 1
};

type TextStyleExtrude = {
  depth?: number;     // px, default 16
  steps?: number;     // raymarch steps (clamped by performance config), default 24
  angle?: number;     // degrees, direction of extrusion, default 45
  sideColor?: number; // 0xRRGGBB; defaults to a darker face color
};

type TextStyleTextureFill = {
  url?: string;                         // image URL (loaded via Assets if not cached)
  assetId?: string;                     // OR an existing Assets alias
  uvScale?: [number, number];           // default [1,1]
  uvOffset?: [number, number];          // default [0,0]
  rotation?: number;                    // radians, default 0
  mix?: number;                         // 0..1, default 1
  colorAlpha?: number;                  // 0..1, default 1
  textureAlpha?: number;                // 0..1, default 1
  blendMode?: TextureBlendMode;         // "normal" | "multiply" | "screen" |
                                        // "overlay" | "softLight" | "hardLight" |
                                        // "colorDodge" | "colorBurn" |
                                        // "vividLight" | "linearLight" |
                                        // "luminosity" | "hue"
};