Docsv3.31.0
Back to API Reference
Class

UniTextFont

Inherits:ScriptableObject

Serialized font definition that owns face and rendering metadata and resolves its immutable source lazily. Embedded sources stay in the asset in the Editor and WebGL; other players resolve build-generated disk-backed sources. The Core materializes only when glyph or shaping work first needs this face.

Derived Types(3)

Types that inherit from UniTextFont.

C
UniTextColorFont
A color-font asset — embedded color-font bytes (CBDT/sbix bitmap or COLRv0/COLRv1 vector) rendered through the shared color-glyph pipeline. The color analog of UniTextFont: add it to a Font Stack like any other font and it serves the codepoints it covers via the normal resolution chain. The always-on system emoji font (EmojiFont) stays the privileged provider for emoji-presentation codepoints.
C
UniTextFontVariant
A UniTextFont that takes only the raw font bytes from a Source font and defines everything else itself — face metrics, units-per-em, render settings and glyph overrides are fully independent and overridable. Use to render the same TTF/OTF with a different look or metrics without duplicating the bytes. Each variant has its own atlas and shaper cache (the base mixes the asset instance id into UniTextFont.FontDataHash), so variants and their source coexist without overwriting each other's glyphs. On first assignment the face metrics are seeded from the source font; after that they are owned by the variant.
C
UniTextSystemFont
UniTextFont that resolves its font bytes from the host OS at runtime from a per-platform pick (Common / Windows / macOS / Linux / iOS / Android). WebGL is unsupported.

Nested Types

S
AxisDefault
One variable-font axis pinned to a custom default value, keyed by its OpenType tag (4-char tag packed big-endian, same bits as the HarfBuzz uint tag).
C
Core
Plain runtime for a font: owns face access, glyph tables, lookup dictionaries, curve cache and atlas pipeline. Constructable on worker threads (no Unity object lifecycle). Dispose instances constructed directly; a UniTextFont owns and disposes the runtime exposed by its asset.
S
GlyphOverride
Per-glyph overrides for one glyph index: SDF tile size plus advance, position and size adjustments applied wherever this glyph renders in the font.
public UniTextFont.Core Runtime{ get }

Lazy-built runtime that owns the FT face, glyph tables and atlas pipeline. First access after creation or source invalidation must occur on the main thread unless a provider has already captured the worker-safe slot.

protected bool HasRuntime{ get }

True if Runtime is already materialized. Avoids triggering lazy build.

public bool HasFontData{ get }

True when font bytes are available (either serialized or supplied by a subclass).

public int FontDataHash{ get }

Process-unique runtime identity used by atlas and shaping registries.

public FaceInfo FaceInfo{ get; set }

Font face metrics (ascender, descender, line height, etc.); their units per em is always UnitsPerEm.

public int UnitsPerEm{ get; set }

Font design units per em (typically 1000 or 2048). Fundamental scaling unit: scale = fontSize / unitsPerEm.

public float FontScale{ get; set }

Visual scale multiplier. Compensates for fonts that render visually smaller/larger than peers at the same size (e.g. Dongle).

public bool ParticipatesInNormalization{ get; set }

Whether font-size normalization may scale this font to match the primary font. Disable to keep a decorative font's intrinsic proportions.

public float ItalicStyle{ get; set }

Synthetic italic slant in percent of height (30 leans the top right by 0.30 of the height, ≈16.7°, not 30°), applied as a horizontal skew when an italic tag is set. 0 falls back to DefaultItalicStyle.

public int SpacingOffset{ get; set }

Baseline spacing added to every glyph's advance during shaping, in font design units. Layered additively with style-level letter-spacing.

public int SpaceAdvance{ get; set }

Space (U+0020) advance for this font, in design units; replaces the width HarfBuzz reports. SpaceAdvanceUninitialized = use the font's own / HarfBuzz fallback.

public float FakeBoldWeight{ get; set }

Baseline synthetic bold in CSS weight steps from the font's own weight (1 ≈ Regular → Bold). Renders thicker via SDF dilate and compensates advance to keep layout stable. No effect on color emoji fonts.

public int PixelsPerEm{ get; set }

Native pixel grid of a pixel-art font in pixels per em; 0 for a distance-field font. Glyphs of a pixel font rasterize once, one atlas texel per font pixel, and render with nearest sampling and hard edges; text sizes that are integer multiples of this value render pixel-exact.

public bool SnapToPixelGrid{ get; set }

Whether a pixel font's glyph origins, and every translation an effect or animation applies to its quads, round to whole font pixels. No effect when PixelsPerEm is 0.

public int AtlasPadding{ get }

Atlas gutter in pixels around each glyph tile, prevents bilinear bleeding.

public bool IsVariable{ get }

True if this font defines OpenType variable axes.

public bool IsColor{ get }

True for color (emoji/COLR) fonts — they bypass the SDF pipeline.

public Dictionary<long,Glyph> GlyphLookupTable{ get }

(varHash48, glyphIndex) → atlas-resident Glyph. Null until the font's lookup tables are built.

protected void InvalidateRuntime()

Tears down the current runtime; next Runtime access rebuilds.

protected void NotifyConfigurationChanged()
protected void SetRawFontDataHash(int value)
protected void SetResolvedMetadata(FaceInfo valueFaceInfo, int valueUnitsPerEm, Nullable<int> valueSpaceAdvance = null)

Updates coupled face metadata without exposing an observable half-updated runtime.

public virtual byte[] CopyFontData()

Creates a managed snapshot of the complete raw font file.

public virtual int GetCachedInstanceId()

Cached Unity instance id, suitable for use as a dictionary key.

public virtual UniTextFontError LoadFontFace()

Loads the underlying FreeType face. Returns the resulting error code, or UniTextFontError.Success if already loaded.

public void ReadFontAssetDefinition()

Creates the runtime glyph lookup table when it does not exist yet; existing entries stay.

public uint GetGlyphIndexForUnicode(uint unicode)

Resolves a codepoint to a glyph index via HarfBuzz, with controlled fallbacks for NBSP/soft-hyphen.

public bool HasGlyphInAtlas(uint glyphIndex, UniTextRenderMode mode)

Returns whether the glyph has a committed or pending entry in the selected distance-field atlas for this font's default variation.

public virtual void ClearDynamicData()

Drops the FT face, glyph caches and atlas entries owned by this font. Next access rebuilds on demand.

protected virtual void OnEnable()
protected virtual void OnDisable()
protected virtual void OnDestroy()
public static void ClearRuntimeData()

Releases native and atlas data for all live runtimes while preserving their managed font definitions, then invalidates shared resolution caches.

public static int ComputeFontDataHash(byte[] data)

Cheap content hash of font bytes (FNV-1a variant, sampling step on large files). Stable across runs.

protected void ResetInstanceFontDataHash()
public static UniTextFont CreateFontAsset(byte[] fontBytes)

Builds a runtime UniTextFont from font file bytes, taking FaceInfo, units-per-em and the pixel grid from face 0.

public static T CreateFontAsset(byte[] fontBytes)

Builds a font asset of the given UniTextFont subtype from font file bytes, populating its source, hash, units-per-em and face metrics identically to CreateFontAsset.

protected int fontDataHash
public static const float DefaultItalicStyle

Synthetic-italic slant used when a font stores none (value 0), notably OS system-font fallbacks built at runtime. The italic modifier reads it as a horizontal shear in percent of height.

Back to API Reference