@web-engine-dev/text-rendering

High-quality text rendering using Signed Distance Fields (SDF) with support for rich text, RTL, and multiple fonts.

Note: Advanced shaping (contextual alternates, complex scripts) is currently limited.

Features

• Font File Loading: Load TTF/OTF/WOFF/WOFF2 fonts directly
• SDF Rendering: Resolution-independent text
• Rich Text: Bold, italic, color, size changes
• RTL Support: Right-to-left text rendering
• Font Atlases: Efficient multi-font rendering
• Text Effects: Outline, shadow, glow
• Layout: Word wrap, alignment, line spacing

Installation

npm install @web-engine-dev/text-rendering
# or
pnpm add @web-engine-dev/text-rendering

Quick Start

import { TextRenderer, Font, TextStyle } from '@web-engine-dev/text-rendering';

// Create renderer
const text = new TextRenderer(device);

// Load font
const font = await Font.load('fonts/roboto.fnt');

// Create style
const style = new TextStyle({
  font: font,
  size: 24,
  color: '#ffffff',
  align: 'center',
});

// Render text
text.draw('Hello, World!', 100, 100, style);

API Overview

TextStyle

const style = new TextStyle({
  font: font,
  size: 24,
  color: '#ffffff',
  align: 'left', // 'left', 'center', 'right'
  verticalAlign: 'top', // 'top', 'middle', 'bottom'
  lineHeight: 1.2,
  letterSpacing: 0,
  wordWrap: true,
  maxWidth: 400,
});

Text Effects

const style = new TextStyle({
  font: font,
  size: 32,
  color: '#ffffff',

  // Outline
  outline: {
    width: 2,
    color: '#000000',
  },

  // Shadow
  shadow: {
    offsetX: 2,
    offsetY: 2,
    blur: 4,
    color: '#00000080',
  },

  // Glow
  glow: {
    size: 4,
    color: '#ff880080',
  },
});

Rich Text

// Use BBCode-style tags
text.drawRich('This is [b]bold[/b] and [color=#ff0000]red[/color] text', x, y, style);

// Supported tags:
// [b] - Bold
// [i] - Italic
// [size=24] - Font size
// [color=#ffffff] - Text color
// [font=arial] - Font family

Font Loading

import {
  FontLoader,
  createFontLoader,
  loadFontWithAtlas,
  CharacterSets,
} from '@web-engine-dev/text-rendering';

// Option 1: Load font file directly with FontLoader
const loader = createFontLoader();
const font = await loader.load('fonts/roboto.ttf');

// Register with atlas for glyph generation
const atlas = createFontAtlas();
loader.registerWithAtlas(font, atlas);

// Preload common characters
loader.preloadCharacters(font.id, CharacterSets.ASCII_PRINTABLE, atlas);

// Option 2: One-step loading with atlas
const { font, atlas, loader } = await loadFontWithAtlas('fonts/roboto.ttf', {
  preloadCharacters: CharacterSets.ALPHANUMERIC,
});

// Generate glyphs on-demand as needed
const glyph = loader.generateGlyph(font.id, 'A'.charCodeAt(0), atlas);

Supported Formats

• .ttf - TrueType fonts
• .otf - OpenType fonts
• .woff - Web Open Font Format
• .woff2 - Web Open Font Format 2

Pre-defined Character Sets

CharacterSets.ASCII_PRINTABLE    // Space through tilde (95 chars)
CharacterSets.ALPHANUMERIC       // A-Z, a-z, 0-9 (62 chars)
CharacterSets.DIGITS             // 0-9
CharacterSets.UPPERCASE          // A-Z
CharacterSets.LOWERCASE          // a-z
CharacterSets.PUNCTUATION        // .,;:!?'"-()[]{}
CharacterSets.LATIN_EXTENDED     // Common accented characters
CharacterSets.SYMBOLS            // Common symbols (copyright, euro, etc.)

Text Measurement

const metrics = text.measure('Hello', style);
console.log(metrics.width);
console.log(metrics.height);
console.log(metrics.lines);