Font

Fonts: bundles, TTF baking, pixel fonts and measuring.

import { Font, FontTtfConfig, FontBakeOptions, FontMeasureStyle, FontMeasureResult } from "willow";

Font

class Font

Font handle backed by a willow::FontFamily. Constructed via the static factories (Font.load, Font.system, Font.fromBuffer). Direct new Font(...) raises a TypeError.

Font: properties

Member	Description
readonly name: string	Family name reported by the bundle.

Font: methods

Member	Description
dispose(): void	Releases this font handle. Destroying the handle returned by Font.system() does NOT free willow's bundled default family. Only this wrapper retires. Idempotent and silent, like every other dispose(). The one method this class carries, renderCount(), raises "InvalidStateError: Font.renderCount: font has been disposed" afterwards. The name field also raises InvalidStateError once disposed.
renderCount(): float	Returns the cumulative number of glyph renders this font has performed. float, not int: the underlying counter never resets and would silently wrap an int32 after roughly 2.1 billion glyphs. Counts glyphs actually emitted by the render pipeline (once per frame a Text node using this font is on-screen and not served from a CacheAsTree replay) — not distinct glyphs, and not frames where the node was cached.
measure(text: string, size: float, style?: FontMeasureStyle): FontMeasureResult	Measures text directly without creating a scene node.
lineHeight(size: float, style?: FontMeasureStyle): float	Returns willow's native line height for a display size and face style.

Font: static methods

Member	Description
static load(path: string): Font	Loads a font bundle from path (resolved via the engine asset roots).
static fromBuffer(buffer: Buffer): Font	Loads a font bundle from an in-memory byte buffer.
static fromPixelFont(texture: Texture | string, cellWidth: int, cellHeight: int, chars: string): Font	Wraps a pixel font spritesheet into a Font. cellWidth and cellHeight specify the fixed cell size in the texture. chars maps cells in row-major order to characters.
static fromTTF(buffer: Buffer, config?: FontTtfConfig): Font	Bakes a TTF/OTF buffer at load time. No baking occurs per frame.
static loadTTF(path: string, config?: FontTtfConfig): Font	Loads and bakes a project-root-confined TTF/OTF file at load time.
static loadTTFCached(ttf: string | Buffer, cacheDir: string, options?: FontBakeOptions): Font	Synchronously loads a TTF/OTF (a project-root-confined path or a Buffer) through an on-disk bake cache. The first call bakes and writes <cacheDir>/<key>.fontbundle (atomically); later calls with the same font bytes and options load that file without baking. An empty or unwritable cacheDir bakes in memory.
static cachedBakeCount(): float	Number of bakes Font.loadTTFCached has performed in this process; cache hits do not count.
static system(name?: string): Font	Returns a handle to willow's bundled default font. The optional name argument is accepted for signature compatibility and ignored.

FontTtfConfig

class FontTtfConfig

Runtime TTF/OTF baking options. Baking happens once while loading.

FontTtfConfig: properties

Member	Description
sizes?: Array<float>	Point sizes to bake ahead of time. Unset uses the font family's default size set.
sdfSpread?: float	SDF spread in pixels for the baked distance field. Unset uses the baker's default.
atlasWidth?: int	Baked atlas page width in pixels. Unset uses the baker's default.
atlasHeight?: int	Baked atlas page height in pixels. Unset uses the baker's default.
chars?: string	Character set to bake glyphs for. Unset bakes the baker's default set.

FontBakeOptions

class FontBakeOptions

Options for Font.loadTTFCached; they map one to one onto the font baker's options and are part of the cache key.

FontBakeOptions: properties

Member	Description
sizes?: Array<float>	Em sizes in pixels to bake. Unset bakes 64 and 256.
distanceRange?: float	SDF distance range in pixels for every size. Unset or 0 uses size / 8.
atlasWidth?: int	Atlas page width in pixels. Unset bakes 1024.
charset?: string	Characters to bake: ascii, latin, full, U+hhhh-hhhh ranges joined by commas, or literal characters. Unset bakes ASCII.
effectSize?: float	Em size of the extra effects entry for outline, glow and shadow. Unset or 0 bakes none.
effectRange?: float	Distance range of the effects entry. Unset or 0 uses effectSize / 2.

FontMeasureStyle

class FontMeasureStyle

Optional face selection for direct font measurement.

FontMeasureStyle: properties

Member	Description
bold?: boolean	Measure using the bold face, when available.
italic?: boolean	Measure using the italic face, when available.

FontMeasureResult

class FontMeasureResult

Dimensions returned by direct font measurement.

FontMeasureResult: properties

Member	Description
readonly width: float	Measured width in pixels.
readonly height: float	Measured height in pixels.