Text2D
Текст внутри 2D-сцены — вывеска в мире, подпись на карте, табличка с именем над персонажем, число
урона: Node2D, который двигается и сортируется вместе со спрайтами. Font2D —
шрифт, которым он рисуется; загружается один раз. Текст поверх игры, который стоит на месте, когда
камера движется (счёт, меню паузы), — это UI: UIText среди виджетов сцены.
- написать текст в 2D-мире игры: вывеску, подпись, число урона
- подписать место на 2D-карте текстом, который сохраняет размер на экране
- показать над персонажем имя, которое следует за ним
- загрузить шрифт для 2D-текста и его жирное начертание
- переносить 2D-текст по ширине и ограничить его несколькими строками
- обвести текст, чтобы он читался на любом фоне
- измерить блок текста, чтобы подложить под него панель
- выровнять строки текста по центру или по правому краю
Платформы: везде, где работает Scene2D; headless-тесты раскладывают текст
(bounds), но ничего не рисуют.
Обзор
const inter = font("inter") // при компиляции: устанавливает Inter (400 / 500 / 700), возвращает "Inter"
const main = async () => {
const scene = new Scene2D({ background: "#10131a" })
const regular = await Font2D.load(inter)
const bold = await Font2D.load(inter, { weight: 700 })
const title = new Text2D({ font: bold, text: "Level 1", fontSize: 32, position: [0, 120] })
const sign = new Text2D({
font: regular, text: "Old mill", fontSize: 14, units: "px", // всегда 14 логических px на экране
anchor: [0.5, 1], position: [-80, 0], outline: { width: 0.12, color: "#000" },
})
scene.add(title, sign)
scene.open()
}
main()Шрифт для Text2D, один на все размеры: Font2D.load
Font2D.load(source: string | FetchResponse | File, options?: {
weight?: number // зарегистрированное семейство: вес начертания; по умолчанию 400, иначе ближайший зарегистрированный
italic?: boolean // зарегистрированное семейство: курсивное начертание; по умолчанию false
}): Promise<Font2D>
font.destroy(): void // освободить шрифт и его атлас — для всех, кто его держитsource — семейство, которое установил макрос font() (font("inter")
компилируется в "Inter"), или файл TTF / OTF: asset('./fonts/Brand.ttf'), URL, полученный
fetch-ответ, File, который выбрал пользователь. Семейство разрешается в TTF своего начертания (те
же начертания, что у UI-текста): точный вес или ближайший установленный; семейство, которое никто
не установил, отклоняется со списком установленных. Источник с /, . или : — это файл, и он
загружается как есть.
Загрузи шрифт один раз и используй его в любом размере: загрузка по семейству или по URL
кэшируется, поэтому все Font2D.load("Inter") проекта делят один нативный шрифт. destroy()
освобождает его для всех, кто его держит (тексты, которые им ещё пользуются, перестают
рисоваться); следующая загрузка разберёт его заново.
const main = async () => {
const brand = await Font2D.load(asset("./fonts/Brand.ttf")) // файл шрифта из проекта
const scene = new Scene2D()
scene.add(new Text2D({ font: brand, text: "Brand", fontSize: 40 }))
scene.open()
}
main()у каждого шрифта свой SDF-атлас глифов 2048 × 2048 (16 МБ на CPU и столько же на GPU), который
создаётся на первом глифе: это около 1400 глифов Inter — латиница, кириллица и греческий шрифта с
запасом. Когда атлас заполнен, движок пишет в лог glyph atlas full, и следующие глифы не
рисуются; для набора размером с CJK нужен второй файл шрифта.
Создание текста: new Text2D
new Text2D(options: {
font: Font2D
text: string // '\n' переносит строку
fontSize?: number // em, в `units`; по умолчанию 16
units?: 'world' | 'px' // по умолчанию 'world'; 'px' = логические px экрана при любом зуме
color?: ColorInput // по умолчанию белый; альфа учитывается
align?: 'left' | 'center' | 'right' // строки внутри блока; по умолчанию 'left'
maxWidth?: number // ширина переноса, в единицах узла; не указано — без переноса
maxLines?: number // не больше N строк; 0 / не указано — без ограничения
overflow?: 'ellipsis' | 'clip' // как заканчивается последняя строка обрезанного блока; по умолчанию 'ellipsis'
lineHeight?: number // множитель собственной высоты строки шрифта; по умолчанию как у шрифта
letterSpacing?: number // дополнительный отступ после каждой буквы, в em; по умолчанию 0
outline?: { width: number, color?: ColorInput } // ореол, ширина в em; цвет по умолчанию чёрный
anchor?: Vec2Like // пивот блока: [0,0] верх-лево … [1,1] низ-право; по умолчанию [0.5, 0.5]
position?: Vec2Like
rotation?: number // градусы, против часовой
scale?: number | Vec2Like
z?: number // порядок отрисовки, см. Scene2D
renderPriority?: number // 0..7, по умолчанию 4
material?: Material2D // для текста важно только смешивание
})Каждая опция — живое свойство с тем же именем (label.text = 'Score 3', label.outline = null).
Запись в text, font, fontSize, units или опцию раскладки заново раскладывает блок в нативном
коде, один раз — никогда не каждый кадр: если текст только двигается, анимируй трансформ узла, а не
текст. Что поддерживается: латиница, кириллица, письменности вроде греческой, с кернингом; без
сложного шейпинга (арабский, индийские письменности) и без эмодзи — они есть у UIText.
Размер 2D-текста: fontSize и units
fontSize — это em, как размер в UIText и Canvas: Text2D в 16 px такого же размера, как
UIText в 16 px. Высота одной строки — собственный шаг строк шрифта (1.21 × fontSize у Inter).
units: 'world'(по умолчанию) — мировые единицы: текст — часть мира и масштабируется вместе с ним на экране. Глифы — поля расстояний (SDF), поэтому края остаются чёткими при любом масштабе.units: 'px'— логические px экрана: один и тот же размер на экране при любом масштабе мира, как у подписи на карте или таблички с именем. Без поворота такой текст ложится на сетку пикселей устройства и читается как UI-текст.
scale узла масштабирует и тот и другой.
Подпись места на карте: units: 'px' и outline
Подпись на карте сохраняет размер на экране (units: 'px'), а обводка держит её читаемой на любом
фоне. outline.width задаётся в em: 0.05 — тонкая, 0.15 — максимум.
const main = async () => {
const scene = new Scene2D({ background: "#d8d2c4" })
const inter = await Font2D.load(font("inter"))
const label = new Text2D({
font: inter, text: "Moscow", fontSize: 13, units: "px",
anchor: [0.5, 1], position: [120, 40], // низ-центр стоит на месте
color: "#222", outline: { width: 0.12, color: "#fff" },
})
scene.add(label)
scene.open()
scene.camera.zoom = 4 // в 4× ближе: подпись остаётся 13 px
}
main()Обводка рисуется в проходе под основной частью всех узлов с теми же renderPriority и z
(порядок отрисовки): у двух перекрывающихся подписей ореол одной
никогда не ложится поверх букв другой.
Имя над персонажем: текст как дочерний узел
Табличка с именем — дочерний узел персонажа: она следует за ним и попадает в сцену вместе с ним.
const main = async () => {
const scene = new Scene2D()
const inter = await Font2D.load(font("inter"))
const hero = new Sprite({ size: [24, 40], color: "#4f7cff", anchor: [0.5, 1] })
const name = new Text2D({
font: inter, text: "Ada", fontSize: 12, units: "px",
anchor: [0.5, 1], position: [0, 46], outline: { width: 0.12 },
})
hero.add(name) // следует за героем, в сцене героя
scene.add(hero)
scene.open()
hero.animateTo({ x: 160, duration: 1500 }) // имя едет следом
}
main()Перенос по ширине и ограничение строк: maxWidth, maxLines, overflow
text.maxWidth = 220 // ширина переноса в единицах узла: мировых или логических px при units 'px'
text.maxLines = 2 // оставить первые 2 строки (lineClamp у UIText); 0 = без ограничения
text.overflow = 'ellipsis' // или 'clip' (textOverflow у UIText)maxWidth и bounds — в единицах узла (мировые единицы или логические px при units: 'px'), а не
в долях fontSize. Строки разрываются на \n и жадно переносятся по пробелам; слово длиннее
ширины остаётся целым и торчит. С maxLines последняя оставленная строка более длинного блока
заканчивается на «…» (U+2026; три точки, если в шрифте его нет) и укорачивается по целым символам,
пока не влезет в maxWidth, — без maxWidth многоточие просто удлиняет её; 'clip' отрезает блок
после последней оставленной строки как есть.
Размер текста: bounds
text.bounds: Vec2 // [ширина, высота] разложенного блока, после переноса и ограничения строкВ единицах узла (мировые или логические px при units: 'px'), без scale узла. Читай его, чтобы
задать размер панели или кнопки под текстом:
const main = async () => {
const scene = new Scene2D({ background: "#10131a" })
const inter = await Font2D.load(font("inter"))
const quest = new Text2D({
font: inter, fontSize: 16, maxWidth: 220, maxLines: 2, align: "center",
text: "Find the old mill north of the river and bring back the miller's key",
})
const size = quest.bounds // две строки, не шире 220
const panel = new Sprite({ size: [size.x + 24, size.y + 16], color: "#223" })
panel.z = -1 // под текстом
scene.add(panel, quest) // оба с центром в начале координат
scene.open()
}
main()Строки, буквы и пивот блока: align, lineHeight, letterSpacing, anchor
alignставит каждую строку внутри блока ('left','center','right').lineHeightумножает собственный шаг строк шрифта (1.5= в полтора раза больше); это не длина.letterSpacing— дополнительный отступ после каждой буквы в em, поэтому он масштабируется сfontSize(0.05приfontSize20 = 1 единица).anchor— точка блока, которая стоит в позиции узла, в пространстве якоря спрайта (Y вниз):[0.5, 1]= низ-центр,[0, 0]= верх-лево.
Текст в файле сцены: блок text
// title.scene2d.ts
export default defineScene2d({
nodes: {
sign: { text: { font: font("inter"), text: "Forest", fontSize: 14, units: "px" }, position: [0, 64] },
},
})font здесь — строка: семейство, которое установил font(), или файл шрифта
(asset('./fonts/Brand.ttf')); загружается через Font2D.load в обычном начертании. Остальные
ключи — опции выше, а цвет можно задать и пропом color узла. См.
файлы сцен.
Подводные камни
// ✗ maxWidth в символах или em
new Text2D({ font, text, fontSize: 20, maxWidth: 12 }) // 12 мировых единиц: по слову на строку
// ✓ ширина в единицах узла
new Text2D({ font, text, fontSize: 20, maxWidth: 240 })
// ✗ счёт в HUD как Text2D: он двигается и масштабируется вместе с миром
// ✓ UIText в виджетах сцены: scene.widgets(UIWidget(UIText(() => `Score: ${score.value}`)))