API Reference

Complete API documentation for the funky-pixi-text library.

Installation

Terminal

npm install funky-pixi-text pixi.js

PIXI.js v7 (^7.2.4) is a peer dependency.

Quick Start

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);

Generating MSDF Fonts

This library consumes BMFont JSON atlases generated by msdf-bmfont-xml or compatible tools.

Terminal

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

This produces two files: Roboto-Black.json (glyph metrics, kerning, atlas layout) and Roboto-Black.png (the MSDF atlas texture). Place them side-by-side and load the .json through PIXI Assets.

Loading Fonts

The package exports a PIXI Asset load parser, registered automatically as a PIXI extension when you import the library.

Loading by URL

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

await Assets.load({
  src: "fonts/Roboto-Black.json",
  loadParser: FontLoader.name, // "MSDFFontLoaderExtension"
});

// Reference in Text() by the file base name
new Text("Hi", { fontName: "Roboto-Black" });

Loading multiple fonts

Multiple fonts

await Assets.load([
  { src: "fonts/Roboto-Black.json", loadParser: FontLoader.name },
  { src: "fonts/Tourney.json",      loadParser: FontLoader.name },
  { src: "fonts/Meddon-Regular.json", loadParser: FontLoader.name },
]);

Overriding the texture URL or font name

Overriding defaults

await Assets.load({
  src: "fonts/MyFont.json",
  loadParser: FontLoader.name,
  data: {
    fontName: "MyCustomKey",         // key used by Text({ fontName })
    textureUrl: "fonts/[email protected]", // override atlas path
  },
});

The Text Class

Text extends PIXI.Container and emits a single batched PIXI.Mesh containing all glyphs.

Constructor

new Text(text: string, style: TextStyle)

Both arguments are required. The font referenced by style.fontName must already be loaded via Assets.

Instance Methods

Method	Description
setText(text: string): void	Replace the displayed string and rebuild the layout.
setStyle(partial: Partial<TextStyle>): void	Update one or more style properties. Uses a uniform-only fast-path when possible.
setColor(color: number \| TextStyleGradient): void	Shortcut to change fill color or gradient (uniform-only update when shape unchanged).
setSmoothing(value: number): void	Adjust edge AA smoothing (0.05 – 5.0).
setKerning(enabled: boolean, scale?: number): void	Toggle kerning and optionally scale the kerning amount.
getTextBounds(): PIXI.Rectangle	Returns the laid-out bounding box including padding for shadow / extrude / smoothing.
debugKerning(): void	Logs all kerning pairs present in the font.
destroy(options?): void	Frees geometry, material, shader, and removes the instance from internal tracking.

Static Methods

Method	Description
Text.enableAutoConfigUpdate(ticker?: PIXI.Ticker): () => void	Begin watching the global performance config and rebuild all live Text instances when it changes. Returns a cleanup function.
Text.disableAutoConfigUpdate(): void	Stop the global watcher.

TextStyle Reference

TextStyle

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
  maxWidth?: number;         // pixels, used with wordWrap and/or autoScale
  maxHeight?: number;        // pixels, used with autoScale
  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;
};

Gradient

TextStyleGradient

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
};

Stroke

TextStyleStroke

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

Drop Shadow

TextStyleDropShadow

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
};

Extrude (3D)

TextStyleExtrude

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
};

Texture Fill

TextStyleTextureFill

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"
};

Available Blend Modes

normalmultiplyscreenoverlaysoftLighthardLightcolorDodgecolorBurnvividLightlinearLightluminosityhue