Font¶
The Font class enables loading fonts and drawing text with them.
Synopsis¶
Constructors¶
Static Methods¶
Instance Methods¶
Instance Members¶
Constructors¶
Font(paths[, size, emoji_font])¶
Loads a font from given path and size.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
paths |
string or string[] |
Yes | The path of the font to load. If multiple paths are provided, first is used as primary font and next are used as fallback fonts. |
size |
int |
No | A specific size to load for the font. Default: 16. |
emoji_font |
string |
No | A specific emoji font to use. Default: current default emoji font name, if set. |
Font(options)¶
Loads a font from given options.
Font Options Table¶
| Field | Type | Default | Description |
|---|---|---|---|
paths |
string or string[] |
N/A | The path of the font to load. If multiple paths are provided, first is used as primary font and next are used as fallback fonts when a glyph is not found. |
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 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.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 |
table |
{r=255, g=255, b=255, a=255} |
Color to render the text. |
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. |
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 = [
"/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
"/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
"/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 = {r=0, g=255, b=0, a=255} })
sampleFont.draw(10, 68, "こんにちは!🇯🇵", { vertical = true })
sampleFont.draw(100, 100, "Do you like :sushi:?")