Text

Signed-distance-field (SDF) text: crisp at any scale, in world space or as a screen-space HUD, with a face color, outline, and softness — modeled on Unity’s TextMeshPro. Baked at runtime from the built-in Inter font, so it stays sharp when a camera moves close or on high-DPI mobile displays.

A Text label is script-owned and cached: build it once, set its style, then draw it each frame. Its layout is re-computed only when the text or a style property changes. The Text Wren API and its layout are a frozen contract, locked by engine golden tests.

Text

Text.new(content)

Returns: Text — A new label using the built-in Inter font.

Parameters:

• content (String) — The initial text (UTF-8; ASCII + Latin-1 render out of the box, other codepoints are baked on demand).

import "engine" for Text

var label = Text.new("PLUME3D")

Style properties

All are setters (assign to change); each re-lays-out the label on the next draw or measure.

• text = (String) — Replace the string.
• size = (Num) — Em height. World units for draw(), pixels for drawScreen().
• color = (List) — Face color [r, g, b, a], each 0..1.
• outlineColor = (List) — Outline color [r, g, b, a].
• outlineWidth = (Num) — Outline width in distance-field units, 0..1 (0 = no outline).
• softness = (Num) — Extra edge anti-aliasing.
• align = (Num) — Line alignment: 0 = left, 1 = center, 2 = right.
• wrapWidth = (Num) — Word-wrap width in the same units as size (0 = no wrapping).
• lineSpacing = (Num) — Line-height multiplier (1.0 = font default).
• richText = (Bool) — Enable inline markup (see Rich text).

label.size = 1.0
label.color = [0.98, 0.80, 0.25, 1.0]        // warm gold
label.outlineColor = [0.10, 0.05, 0.0, 1.0]
label.outlineWidth = 0.28
label.softness = 0.02

Measurement

• width — Laid-out width (read-only), in the same units as size.
• height — Laid-out height (read-only).
• lineCount — Number of laid-out lines.

label.draw(model)

Draw the label in world space with a column-major 4×4 model matrix (a 16-float List), transformed by the current view/projection. Depth-tested against 3D geometry (but does not write depth).

// A model that scales + positions the label in the scene.
label.draw([s, 0, 0, 0,  0, s, 0, 0,  0, 0, 1, 0,  x, y, z, 1])

label.drawScreen(x, y)

Draw the label in screen space at pixel position (x, y) = its top-left corner. size is interpreted in pixels here.

var hud = Text.new("Score: 1200")
hud.size = 24.0                 // 24 px tall
hud.drawScreen(24, 24)          // top-left corner of the window

Rich text

With richText = true, two inline tags style spans of the string:

• <color=#rrggbb>…</color> — tint the enclosed glyphs (6-digit hex).
• <size=N>…</size> — scale the enclosed glyphs by N (baseline-aligned).

Unrecognized or malformed tags render literally — bad markup never crashes.

var t = Text.new("<color=#ffd24a>rich</color> <size=1.5><color=#7ec8ff>text</color></size> markup")
t.richText = true
t.draw(model)

(<b> / <i> are planned — they need a bold/italic atlas; tracked separately.)

Example — in-world label

import "engine" for Engine, Graphics, Window, Text

class Game {
  construct new() { _label = null }
  identity { [1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1] }

  init() {
    _label = Text.new("LEXICON")
    _label.size = 1.0
    _label.color = [0.98, 0.80, 0.25, 1.0]
    _label.outlineWidth = 0.25
  }

  draw() {
    Graphics.setViewProjectionEnabled(true)
    Graphics.setViewMatrix(identity)
    Graphics.setProjectionMatrix(identity)
    // Center the label in NDC using its measured width.
    var s = 1.4 / _label.width
    _label.draw([s,0,0,0, 0,s,0,0, 0,0,1,0, -(_label.width*s)/2, -(_label.height*s)/2, 0, 1])
  }
  quit() {}
}

See SDF Text Demo (apps/sdf_text_demo) for a full world-space + HUD + rich-text example, and Graphics for the view/projection setup used by world-space text.