Text2D

Текст внутри 2D-сцены — вывеска в мире, подпись на карте, табличка с именем над персонажем, число урона: Node2D, который двигается и сортируется вместе со спрайтами. Font2D — шрифт, которым он рисуется; загружается один раз. Текст поверх игры, который стоит на месте, когда камера движется (счёт, меню паузы), — это UI: UIText среди виджетов сцены.

  • написать текст в 2D-мире игры: вывеску, подпись, число урона
  • подписать место на 2D-карте текстом, который сохраняет размер на экране
  • показать над персонажем имя, которое следует за ним
  • загрузить шрифт для 2D-текста и его жирное начертание
  • переносить 2D-текст по ширине и ограничить его несколькими строками
  • обвести текст, чтобы он читался на любом фоне
  • измерить блок текста, чтобы подложить под него панель
  • выровнять строки текста по центру или по правому краю

Платформы: везде, где работает Scene2D; headless-тесты раскладывают текст (bounds), но ничего не рисуют.

Обзор

TypeScript
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

TypeScript
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() освобождает его для всех, кто его держит (тексты, которые им ещё пользуются, перестают рисоваться); следующая загрузка разберёт его заново.

TypeScript
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()
Note

у каждого шрифта свой SDF-атлас глифов 2048 × 2048 (16 МБ на CPU и столько же на GPU), который создаётся на первом глифе: это около 1400 глифов Inter — латиница, кириллица и греческий шрифта с запасом. Когда атлас заполнен, движок пишет в лог glyph atlas full, и следующие глифы не рисуются; для набора размером с CJK нужен второй файл шрифта.

Создание текста: new Text2D

TypeScript
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 — максимум.

TypeScript
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 (порядок отрисовки): у двух перекрывающихся подписей ореол одной никогда не ложится поверх букв другой.

Имя над персонажем: текст как дочерний узел

Табличка с именем — дочерний узел персонажа: она следует за ним и попадает в сцену вместе с ним.

TypeScript
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

TypeScript
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

TypeScript
text.bounds: Vec2   // [ширина, высота] разложенного блока, после переноса и ограничения строк

В единицах узла (мировые или логические px при units: 'px'), без scale узла. Читай его, чтобы задать размер панели или кнопки под текстом:

TypeScript
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 при fontSize 20 = 1 единица).
  • anchor — точка блока, которая стоит в позиции узла, в пространстве якоря спрайта (Y вниз): [0.5, 1] = низ-центр, [0, 0] = верх-лево.

Текст в файле сцены: блок text

TypeScript
// 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 узла. См. файлы сцен.

Подводные камни

TypeScript
// ✗ 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}`)))

Смотрите также

  • Scene2D — порядок отрисовки, HUD поверх сцены
  • Node2D — трансформ, иерархия (унаследованы)
  • Шрифты — макрос font(): семейства, веса, свой файл шрифта
  • Path2D — линии и фигуры рядом с текстом
  • Camera2D — зум