Skip to content

t1k:cocos:playable:font-service

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
Tools—

Keywords: font, font filename, FontService, label, ttf, UI

/t1k:cocos:playable:font-service

FontService — Global & Per-Label Font Management

Section titled “FontService — Global & Per-Label Font Management”

Static singleton at PLAGameFoundation/ui/utils/FontService.ts. Manages system fonts and custom TTF fonts loaded from resources/font/. See also: t1k-cocos-playable-parameter (LabelParameter uses applyFont), t1k-cocos-playable-gameflow (LoadingView, WinView).

Import: db://assets/packages/@playablelabs/game-foundation/ui/utils/FontService

FontService (static class)
├── _globalFont: string — current global font value
├── _isCustomFont: boolean — true when name is in CUSTOM_FONTS list
└── _customFontAsset: Font — cached loaded Font asset
Custom font detection: CUSTOM_FONTS = ['Baloo Regular', 'Lilita One']
Font files live at: resources/font/{FontNameNoSpaces}.ttf (or .fnt)

Two modes:

  • System font — label.useSystemFont = true; label.fontFamily = name (e.g., “Arial”)
  • Custom font — loads from resources/font/, sets label.font = asset with useSystemFont = false
// Set globally — triggers applyToAllLabels() on completion
FontService.setGlobalFont("Arial, sans-serif"); // system font
FontService.setGlobalFont("Baloo Regular"); // custom — async loads from resources
// Read current value
const font = FontService.globalFont;
// Re-apply to all labels (if new labels spawned after setGlobalFont)
FontService.applyToAllLabels();
// Sync — uses already-loaded global font state
FontService.applyFontToLabel(label: Label): void
// Async — loads custom font if needed; handles both system and custom
await FontService.applyFont(label: Label, fontValue: string): Promise<void>

With LabelParameter onUpdate:

// In ParameterController.SetUpOnUpdate()
labelParam.onUpdate = async (value) => {
await FontService.applyFont(this.myLabel, value);
};

Global font from parameter (e.g., font family selector):

fontFamilyParam.onUpdate = (value) => {
FontService.setGlobalFont(value);
};

Apply global font to a newly spawned label:

// After instantiating a prefab with labels
FontService.applyToAllLabels(); // or per-label for performance
FontService.applyFontToLabel(newLabel);

Adding a new custom font:

  1. Place font file at resources/font/BaloRegular.ttf (name without spaces)
  2. Add the display name to the CUSTOM_FONTS array in FontService.ts:
    const CUSTOM_FONTS = ['Baloo Regular', 'Lilita One', 'My New Font'];
  3. Call FontService.setGlobalFont("My New Font") — it strips spaces when loading path
  • Calling applyFontToLabel after the label’s node is destroyed — applyFont guards with label.isValid check, applyFontToLabel does not. Check label.isValid before calling.
  • Expecting setGlobalFont for a custom font to be synchronous — it’s async (loads from resources). Labels created after the call but before load completes will not have the font applied. Call applyToAllLabels() after await completes if needed.
  • Font file name must have no spaces: "Baloo Regular" → loads font/BalooBRegular (strips spaces). Match exactly.
  • System font fontFamily accepts CSS font stack strings ("Arial, sans-serif") — only the first token is used for custom-font detection.
  • applyFontToLabel uses the cached _customFontAsset; if no global font has been set yet, it returns early silently.
  • Web fonts via @font-face don’t apply inside Cocos Label until manually registered with cc.assetManager.
  • A face is only as wide as its cmap. Parse it before adding a language; a named-but-missing TTF only warns and draws boxes. A pooled or popup-born label keeps its authored face until something localizes it at birth, and a stand-in weight (Black for a Regular SDF) is 20-30% heavier and reads as a layout bug. Coverage union, pending-list guard and birth-time stamp: t1k-cocos-playable-localize (SKILL Phase 2, references/wiring-guide.md). Cross-link: t1k-art-base-fonts (coverage, subset) in the art kit.
  • Bitmap fonts have a fixed glyph set — non-Latin characters render as boxes; check glyph coverage before localizing.
  • A space in a .ttf FILENAME breaks font loading outright — preview and builds alike. This is not the same constraint as the resource-path rule in Common Mistakes above: it is an engine-level bug that fires even for a font referenced directly as a Font asset (no FontService involvement). The engine’s getFontFamily() already quotes the family name and loadFont() quotes it a second time → invalid @font-face → a 3 s timeout and Download Font [ "Name_LABEL" ] failed; the editor preview server independently 404s the %20 path. Fix by renaming through the editor so the .meta UUID survives; see the full recipe in t1k:cocos:playable:tooling-gotchas → font-filename-space-breaks-ttf-load.
  • Build a CJK subset from the union of the FINAL runtime string table, never per-language source tables. The union is the supplement strings, the decoded strings and the endonyms, including the language selector’s own rows (e.g. 繁體中文). A character absent from the shipped subset does not fail: the browser silently falls back per glyph to a lighter system face, so one word renders in mixed weight (the bold subset glyph beside a regular fallback glyph). Seen once: a traditional-Chinese subset of ~1.7k codepoints lacked 繁, and 28 reachable strings across zh-cn, zh-tw, ko and ja missed a glyph, while the project’s localization check stayed green because it only compared key presence. A coverage check must read the font’s cmap (e.g. fontTools TTFont(path).getBestCmap()) and diff it against every codepoint of every reachable string per language; a key-presence check proves nothing about glyphs.