t1k:cocos:playable:font-service
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: font, font filename, FontService, label, ttf, UI
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:font-serviceFontService — 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
Architecture
Section titled “Architecture”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/, setslabel.font = assetwithuseSystemFont = false
Key APIs
Section titled “Key APIs”Global font (applies to all scene labels)
Section titled “Global font (applies to all scene labels)”// Set globally — triggers applyToAllLabels() on completionFontService.setGlobalFont("Arial, sans-serif"); // system fontFontService.setGlobalFont("Baloo Regular"); // custom — async loads from resources
// Read current valueconst font = FontService.globalFont;
// Re-apply to all labels (if new labels spawned after setGlobalFont)FontService.applyToAllLabels();Per-label application
Section titled “Per-label application”// Sync — uses already-loaded global font stateFontService.applyFontToLabel(label: Label): void
// Async — loads custom font if needed; handles both system and customawait FontService.applyFont(label: Label, fontValue: string): Promise<void>Workflow: Integration Patterns
Section titled “Workflow: Integration Patterns”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 labelsFontService.applyToAllLabels(); // or per-label for performanceFontService.applyFontToLabel(newLabel);Adding a new custom font:
- Place font file at
resources/font/BaloRegular.ttf(name without spaces) - Add the display name to the
CUSTOM_FONTSarray inFontService.ts:const CUSTOM_FONTS = ['Baloo Regular', 'Lilita One', 'My New Font']; - Call
FontService.setGlobalFont("My New Font")— it strips spaces when loading path
Common Mistakes
Section titled “Common Mistakes”- Calling
applyFontToLabelafter the label’s node is destroyed —applyFontguards withlabel.isValidcheck,applyFontToLabeldoes not. Checklabel.isValidbefore calling. - Expecting
setGlobalFontfor 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. CallapplyToAllLabels()afterawaitcompletes if needed. - Font file name must have no spaces:
"Baloo Regular"→ loadsfont/BalooBRegular(strips spaces). Match exactly. - System font
fontFamilyaccepts CSS font stack strings ("Arial, sans-serif") — only the first token is used for custom-font detection. applyFontToLabeluses the cached_customFontAsset; if no global font has been set yet, it returns early silently.
Hard rules
Section titled “Hard rules”- Web fonts via
@font-facedon’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
.ttfFILENAME 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 aFontasset (noFontServiceinvolvement). The engine’sgetFontFamily()already quotes the family name andloadFont()quotes it a second time → invalid@font-face→ a 3 s timeout andDownload Font [ "Name_LABEL" ] failed; the editor preview server independently 404s the%20path. Fix by renaming through the editor so the.metaUUID survives; see the full recipe int1k: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.