Skip to content

Font

The Font class enables loading fonts and drawing text with them.

Synopsis

Constructors

Static Methods

Instance Methods

Instance Members

Constructors

Font()

Loads the embedded default font (Bitstream Vera Sans) at a size of 16.0.

Font(size[, emoji_font])

Shorthand constructor to load the embedded default font at a custom scale.

Parameters:

Parameter Type Required Description
size float Yes A specific size to load for the default font.
emoji_font string No A specific emoji font atlas to use. Default: current default emoji font name, if set.

Font(paths[, size[, emoji_font]])

Loads custom external font files or operating system font aliases.

Strict Path Requirements

Every path or alias listed in the paths variable must physically exist on the host operating system. If a file is missing or misspelled, a script exception is thrown.

Multiple paths are used strictly for missing character/glyph-level fallbacks, not file-missing fallbacks.

Parameters:

Parameter Type Required Description
paths string or string[] Yes The path or alias of the font to load. If multiple paths are provided, the first is used as the primary font, and subsequent elements act as fallback layers for missing glyphs.
size float No A specific size to load for the font. Default: 16.0.
emoji_font string No A specific emoji font atlas to use. Default: current default emoji font name, if set.

Font(options)

Loads a font configuration using a named properties table.

Font Options Table

Field Type Default Description
paths string or string[] "" The path or alias of the font to load. Handles glyph-level fallbacks when provided as an array. Leaving this empty or omitted loads the default font.
size float 16.0 A specific size to load for the font.
emoji_font string Current default emoji font name, if set. A specific emoji font atlas to use.

Static Methods

Font.load_emoji_font(name, path[, size])

Loads an emoji font from a directory.

Parameters:

Parameter Type Required Description
name string Yes The emoji font name.
path string Yes Path to the emoji font directory.
size int No A specific size to load for the emoji font. Default: Load all emoji font sizes available in its directory.

Font.set_default_emoji_font(name)

Sets the default emoji font to use.

Parameters:

Parameter Type Required Description
name string Yes The name of the emoji font to use as default.

Font.flush_caches()

Destroys cached text textures and compiled layouts for the calling VM's active window only.

Call this on scene transitions to immediately reclaim GPU memory.

Instance Methods

font.derive([size[, modifier]])

Creates and returns a new Font instance derived from an existing one, allowing you to modify its size, style modifier, or both, while retaining the original font's paths and emoji configuration.

Parameters:

Parameter Type Required Description
size float No A specific size to load for the derived font.
modifier string No A style modifier (e.g., "Bold", "Italic", "BoldItalic"...).
  • Returns: instance: The new derived Font instance.

font.draw(x, y, text[, options])

Draw given text at specified coordinates on the screen.

Draw Options Table

Field Type Default Description
angle float 0.0 Angle to render the text, in degrees.
color Color | string | int | array | table "white" Text color. See Color Formats.
scale float 1.0 Scale factor to render the text.
replace_emojis_shortcodes bool true Whether emoji shortcodes like :sushi: should be replaced while rendering the text.
rtl bool false Whether text should be rendered from right to left.
vertical bool false Whether text should be rendered as a vertical column.

font.metrics()

Get font metrics as a table.

  • Returns: table

Metrics Table

Field Type Description
ascent int The font ascent (Offset from the baseline to the top).
descent int The font descent (Offset from the baseline to the bottom).
line_skip int The spacing between lines of text for this font.

font.measure(text[, scale])

Compute the dimensions of a rendered string of text at a given scale.

Parameters:

Parameter Type Required Description
text string Yes The text to compute dimensions for.
scale float No Scale factor for computed dimensions. Default: 1.0.
  • Returns: table

Measure Table

Field Type Description
width float The rendered text width.
height float The rendered text height.

font.truncate(text, width[, ellipsis])

Truncates a string of text so that its rendered width fits within a specified length. If the text is truncated, the specified ellipsis string is appended to the end.

Parameters:

Parameter Type Required Description
text string Yes The original text string to evaluate and truncate if necessary.
width float Yes The maximum allowed width in pixels.
ellipsis string No The suffix string to append if truncation occurs. Default: ....
  • Returns: string: The truncated string with the ellipsis appended (if it exceeded width), or the original text unmodified if it already fit.

Instance Members

font.emoji_font

  • Type: string

The current emoji font to use to render this font.

Examples

// Load an emoji font
Font.load_emoji_font("Noto Color Emoji", "assets/Fonts/Noto Color Emoji")

// Set the default emoji font to use
Font.set_default_emoji_font("Noto Color Emoji")

// Prepare font
local fontPaths = [
    "DejaVu Sans",           // /usr/share/fonts/truetype/dejavu/DejaVuSans.ttf
    "Noto Sans Mono CJK JP", // /usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc
    "Noto Sans Arabic",      // /usr/share/fonts/truetype/noto/NotoSansArabic-Regular.ttf
]
local sampleFont = Font({paths = fontPaths, size = 24})

// In draw():
sampleFont.draw(10, 10, "Hello world!")
sampleFont.draw(200, 34, "مرحبا بالعالم!", { rtl = true, color = Color.Lime })
sampleFont.draw(10, 68, "こんにちは!🇯🇵", { vertical = true })
sampleFont.draw(100, 100, "Do you like :sushi:?")

Additional example code available here.