Text#

Shaped text as entities in the rendered world.

A Text names a font and string. Transform2D places its top-left corner, Tint colors every glyph, and Clip clips it like any other drawable.

tecs.gfx.text.install(world)
tecs.gfx.layers.configure(8, {sort = "z", screenSpace = true, unlit = true, overlay = true})
local font = assert(tecs.gfx.fonts.newTTF({
    source = tecs.files.assetPath("fonts/JetBrainsMono-ExtraBold.ttf"),
    name = "game.hud",
    size = 28,
    raster = "alpha",
}))
world:spawn(
    tecs.ecs.Transform2D(24, 24, 0, 8),
    tecs.gfx.Tint(0.92, 0.96, 1, 1),
    tecs.gfx.Text("tecs\n1200 entities", font, 28, "center")
)

Write text fields through world:getMut. A direct world:get write leaves the column clean and the displayed glyphs unchanged.

Fonts and layout#

newTTF reads a TrueType font. Tecs rasterizes glyphs lazily, packs them into the font atlas, and keeps one rendered instance per glyph. Reuse the same Font object for texts sharing a font name; independently created fonts must not overwrite one named image with different atlases.

For fixed-size UI, load an "alpha" raster at its displayed pixel size, as in the example. Put labels on an unlit, screen-space overlay layer so their antialiased edges blend. Use tecs.gfx.text.snap explicitly when the block's origin needs rounding to a whole pixel. The UI examples rebuild fonts for the window's scale factor and reuse each named atlas.

Text supports explicit newlines and left, center, or right alignment. The fifth Text argument sets a wrap width; zero disables wrapping. It does not anchor outside the top-left corner or style individual glyphs. Glyphs are sprite entities and inherit the text's layer. Missing glyphs are created in one batch per label, with direct native-column initialization. Existing glyph IDs are reused when text changes; shortening it releases only the surplus. Unchanged labels do no layout or glyph-creation work. Transform2D.scaleX and scaleY multiply the whole text block; glyph dimensions come from Text.size.

See Building interfaces for the complete screen UI and the text reference for measurement and glyph access.