fonts
Fonts for Decentraland SDK7 text: the three built-in faces and custom .ttf fonts shipped with the scene (fontSrc), for 3D and UI text. Use when the user wants a custom or branded typeface, wants to change a text's font, ships a .ttf, or asks why a custom font isn't showing. For text layout see build-ui; for placing 3D text see advanced-rendering.
How do I install this agent skill?
npx skills add https://github.com/decentraland/sdk-skills --skill fontsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides comprehensive documentation and coding guidelines for implementing built-in and custom fonts within Decentraland SDK7. It emphasizes best practices for mobile compatibility, SDK versioning, and asset licensing without introducing security risks.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Fonts in Decentraland
Every text component has two font fields:
| Field | What it takes | Components |
|---|---|---|
font | A built-in face. On TextShape / UiText: Font.F_SANS_SERIF (default), Font.F_SERIF, Font.F_MONOSPACE. On React-ECS props: 'sans-serif' (default), 'serif', 'monospace' | All |
fontSrc | Path to a .ttf file in the scene's content, relative to the scene root | TextShape, UiText, UiInput, UiDropdown, and the React-ECS Label, Button, Input, Dropdown and UiEntity uiText |
Those three built-in faces are the only ones. There is no font name list beyond them.
RULE: Check the SDK version before writing fontSrc
fontSrc needs @dcl/sdk 7.31.0 or later. On earlier versions the field does not exist: it is a TypeScript error, and even forced past the types the SDK never sends it to the explorer.
Read the installed version from node_modules/@dcl/sdk/package.json before writing it; on a Multiplayer Server scene (@dcl/sdk@auth-server) go by the typings, not the version string — the rule is sdk-scenes → A feature that needs a newer SDK. If the scene is older, upgrade @dcl/sdk as that rule says, or stay with a built-in font.
RULE: Always set font next to fontSrc
font is the fallback whenever the custom font cannot be used: on mobile always, on desktop until the font's asset bundle is ready (see Testing). Pick the closest built-in face, so the fallback still looks intended: 'serif' for a serif or display face, 'monospace' for a code or terminal face, 'sans-serif' otherwise.
Size every fixed box so the fallback fits, never from the custom font's width: desktop also renders the fallback until the font's bundle is ready (right after a deploy, and in a local preview whose converter did not serve the scene). Single-line text also needs textWrap="nowrap" and spare width: build-ui → Sizing and mobile.
RULE: The mobile app ignores fontSrc
The Decentraland mobile app does not support custom fonts: it always renders the font fallback, and its only faces are Noto Sans, Noto Serif and Noto Sans Mono, plus their bold variants (observed 2026-11). Every scene that uses fontSrc must still look right and fit with its fallback:
- Choose the fallback deliberately (previous rule), and before designing text-heavy UI for a mobile target, not after: one retrospective found three screens designed around a display font before this rule was read.
- Size every box so the fallback fits (previous rule).
- Never put meaning only in the custom font's look (an icon font, a symbol font, a "handwritten" clue). On mobile it becomes plain text.
When the user adds a custom font, tell them it won't show on mobile.
A display face that must survive on mobile needs image text: a per-glyph bitmap font, one UiEntity per character drawing its glyph as a uvs crop of an atlas (build-ui → references/ui-components.md → Texture UVs). It renders the same on every client, at two costs:
- One atlas per colour. Mobile apps below 1.16.0 ignore
uiBackground.colortint and alpha onuvscrops ({baseDir}/../sdk-scenes/references/mobile-parity.md), so pre-colour every variant and bake shadows and outlines into the glyph art. - Node count. Every glyph is a node, and stacked copies multiply it: an outline faked with 17 stacked
Labels dropped a screen to ~6 FPS, and baking shadows into the glyph art took a screen from ~23 to ~45 FPS. Keep image text to titles and short labels.
RULE: A custom font is a .ttf file in the scene
fontSrc is a file path, not a font name. Custom fonts are available, but a font the user names ("use Playfair Display") only works once its .ttf file sits in the scene's folder and fontSrc points at it. When the user wants a custom font and the scene has no .ttf for it yet, tell them custom fonts are supported and either ask for the .ttf, or offer to download it, confirming first like any asset download (sdk-scenes → Agent Behavioral Guidelines, item 2). Either way, the font's licence must allow redistributing it with the scene: most Google Fonts use the SIL Open Font License, which does.
The Unity explorer supports nothing else. Every other value silently falls back to font there:
fontSrc value | Unity explorer | Bevy explorer |
|---|---|---|
.ttf in the scene content | Yes, once its asset bundle exists (deployed, or the desktop preview, which converts fonts locally) | Yes |
OpenType with CFF outlines (usually .otf), collections (.ttc), web fonts (.woff, .woff2) | Falls back | Not documented — do not rely on it |
.ttf over 16 MB, or with extremely complex glyph outlines | Falls back (refused by the converter) | Not documented |
URL to a .ttf | Falls back | Yes |
Font family name ('Playfair Display') | Falls back | Yes |
| Missing file, invalid file, empty string | Falls back | Falls back |
The protocol's doc comment, which shows up in editor tooltips, says a font family name works. That is Bevy only: Unity dropped external fonts on purpose (security, code size, runtime glyph rasterising). Never write a family name or a URL in fontSrc.
When the desktop client rejects a fontSrc value it logs an SDK_FONTS line saying why: a warning for a URL (font_src "…" cannot be an external URL), a plain log line for anything that isn't a file of the scene, family names included (font_src "…" is not a content file of the scene …). Check the console, including non-warning lines, before anything else when a font falls back.
Adding a font to a scene
- Put the
.ttfunderassets/fonts/, for exampleassets/fonts/BungeeShade-Regular.ttf. Use a static.ttf. If a family ships only as a variable font, use its static instances. - Put the font's licence next to it (
assets/fonts/BungeeShade-OFL.txt). Deploying publishes the file on public content servers, so the licence must allow redistribution and embedding. OFL and Apache fonts allow it. Most commercial desktop licences do not. - Reference it by its path from the scene root, the same way as a texture
src:fontSrc: 'assets/fonts/BungeeShade-Regular.ttf'.
One file is one face. For a bold title and regular body text, ship both weights and point each text at its own file.
Cost: every text entity using the same fontSrc shares one loaded copy, so reusing a font across the scene costs no more than using it once. Each distinct font file becomes its own asset bundle of about 700 KB (two texture atlases), plus its own textures in memory. Keep a scene to one or two font files.
3D text (TextShape)
import { engine, Transform, TextShape, Font } from '@dcl/sdk/ecs'
import { Vector3, Color4, Color3 } from '@dcl/sdk/math'
const sign = engine.addEntity()
Transform.create(sign, { position: Vector3.create(8, 3, 8) })
TextShape.create(sign, {
text: 'OPEN',
fontSize: 6,
textColor: Color4.White(),
outlineColor: Color3.Black(),
outlineWidth: 0.1,
font: Font.F_SERIF,
fontSrc: 'assets/fonts/AbrilFatface-Regular.ttf'
})
// Switching font at runtime is a plain field write
TextShape.getMutable(sign).fontSrc = 'assets/fonts/BungeeShade-Regular.ttf'
UI text (React-ECS)
<Label
value="Score: 100"
fontSize={24}
textWrap="nowrap"
font="sans-serif"
fontSrc="assets/fonts/BungeeShade-Regular.ttf"
uiTransform={{ width: 240, height: 40 }}
/>
<Button value="Play" variant="primary" textWrap="nowrap" font="sans-serif" fontSrc="assets/fonts/BungeeShade-Regular.ttf" />
<Input placeholder="Your name" font="serif" fontSrc="assets/fonts/PTSerif-Regular.ttf" />
<Dropdown options={['Easy', 'Hard']} font="serif" fontSrc="assets/fonts/PTSerif-Regular.ttf" />
<UiEntity uiText={{ value: 'Coded-only text bag', font: 'monospace', fontSrc: 'assets/fonts/AzeretMono-Medium.ttf' }} />
Editable UI (build-ui): write fontSrc on the element by hand. The Creator Hub UI Designer neither shows nor edits it, but its saves splice only the props they change, so a hand-written fontSrc survives (Prettier may re-indent the line). Its canvas renders the font fallback. A custom font alone is not a reason to switch a UI to coded mode.
Testing a custom font
The desktop client (Unity explorer) loads scene fonts only from asset bundles, never from the raw font file. So the custom font shows only where bundles exist:
- Local preview (
npm run startor Creator Hub Play, no flag needed): the Desktop Explorer converts the scene's assets itself before the scene loads,.ttffonts included, so the font shows. Only.ttfconverts: any other font format keeps thefontfallback. If the font still shows its fallback, the converter did not run or could not serve this scene; the AB panel of the Explorer's debug menu says why (optimize-scene → Local Asset Bundle Preview). The converter is a separateabgenprocess on127.0.0.1:5147that can outlive a force-quit Explorer. The next launch adopts it when it is the same Explorer build serving the same scene and already ready; any other leftover blocks the port, the session degrades to raw GLTFs and the built-in font, and the AB panel names the pid — stop thatabgen(pgrep -fl abgen) and relaunch once (observed 2026-11). - Deployed scene: the font appears once the server's asset-bundle conversion finishes. Until then the fallback shows. Scenes deployed before font conversion existed get font bundles only when they are deployed again.
- Bevy explorer loads the
.ttfdirectly, so its preview shows the font without conversion. - Mobile app: always the fallback (see the mobile rule).
- Fallback fit check: before shipping text-heavy UI, look at it once on the fallback by removing
fontSrctemporarily so thefontface renders (restore it afterwards). Overlaps there are what players see until the font's bundle is ready, and always on mobile. It is the most demanding fit test: a fallback much wider than the custom face ran text over the key icons beside it and made two phrases overlap although nothing wrapped (in-world, 2026-11). - Tell the user which of these applies before they report "my font isn't working".
- The reference scene for expected behaviour is
scenes/84,-6-font-srcin decentraland/sdk7-test-scenes (realmsdk7testscenes.dcl.ethon zone). It covers each fallback case, fonts shared between components, recreating components and the scene boundary.
Glyphs and legibility
- A custom font only draws the characters it contains. Characters it lacks are drawn with the built-in sans-serif, mid-word, which looks broken. For accented letters, Cyrillic, CJK and so on, pick a font that includes those scripts.
- The font's bundle comes with ASCII, smart punctuation (quotes, dashes, ellipsis, bullet), € and the common Latin-1 letters already rendered. Any other character the font includes (Cyrillic, Greek, CJK…) is rendered the first time it appears, which causes a brief hitch. For text in those scripts, show it early (a loading or intro screen) rather than at a critical moment.
- No emoji in any text value, whatever the font. The Unity explorer has no emoji glyphs (see build-ui).
- Keep decorative and display faces for short titles and signs. Body text and anything read while moving needs a plain face at the sizes in build-ui (UI) and advanced-rendering (3D).
- A monospace face, built-in or custom, does not make spaces line up columns in a
TextShape. Use oneTextShapeper column (see advanced-rendering).
Cross-references
- build-ui: Label, Button, Input and Dropdown props, sizing and the no-emoji rule.
- advanced-rendering:
TextShapeplacement, orientation, outline and alignment. - migrate-sdk6-to-sdk7: SDK6
fontnames map to the built-inFontenum, and custom SDK6 fonts map tofontSrc. - deploy-worlds / deploy-scene: deploying so the server converts the font.
- optimize-scene: asset-bundle conversion and why it matters for load time.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/decentraland/sdk-skills/fonts">View fonts on skillZs</a>