SgText

Renders 3D text in the scene, with configurable font, size, color, and alignment. Can be used for labels, signs, UI elements, or debug output. Supports dynamic text updates and integration into world or screen space.

Inherits from

SceneObject

Usage

To use this class, add the following require at the top of your script:

local SgText = require 'engine/sceneobjects/sgtext'

Reference

create

static create(self, options, parent)

Create a new text object in the scenegraph.

Parameters

self
options (table): A table of options to fill the parameters
parent (SceneObject): The parent scene object to add this to

Returns

Promise: promise which will resolve to the created object

Example

-- Options can be omitted. This example shows the defaults,
-- only specify the ones you want different.
SgText.create({
    active = true,
    name = "",
    transform = Transform.new(),
    layers = {0},
    tags = {},
    receiveShadow = false,
    castShadow = false,
    material = nil,
    text = "Text",
    horizontalAlign = SgText.HorizontalAlign.Center,
    verticalAlign = SgText.VerticalAlign.Baseline,
    font = nil,
    size = 1,
    height = 1,
    curveSegments = 12,
    bevelEnabled = false,
    bevelThickness = 0.1,
    bevelSize = 0.03,
    bevelOffset = 0,
    bevelSegments = 3,
    uvScale = Vector2.new(1, 1)
})

Properties

You can access these properties directly on the object or through :get("propertyName") or :set("propertyName", value) methods.

Property	Type	Default	Description
active	Boolean	true	Indicates if the 3D object is currently active or inactive. When set to true, the object is active.
static	Boolean	false	Marks the object as immovable during play. Static objects ignore transform changes at runtime and use a fixed physics collider with zero mass.
transform	Transform	Transform.new()	Describes the object's transformation attributes including its position, rotation, and scale in the 3D space.
layers	Layers	[0]	Defines the layers that the 3D object is part of. Layers are used for managing object interactions and visibility in the scene.
tags	Tags	[]	Lists tags associated with the 3D object. Tags are useful for categorizing and searching objects in the scene.
receiveShadow	Boolean	false	Determines whether the object can receive shadows from other objects. Set to true if the object should display shadows cast upon it.
castShadow	Boolean	false	Controls whether the object casts shadows in the presence of light sources. Set to true to enable shadow casting from this object.
rendered	Boolean	true	When disabled, the object and its descendants are not drawn, but may still simulate physics or run scripts.
text	String	Text	String content displayed by this 3D text object.
horizontalAlignment	Enum	center	Anchors generated 3D text along the X axis (left, center, or right). \| Options: left, center, right
verticalAlignment	Enum	baseline	Anchors generated 3D text along the Y axis (top, middle, or bottom). \| Options: baseline, top, middle, bottom
size	Float	1	Font size in world units for generated 3D text.
height	Float	1	Extrusion depth of 3D text geometry. 0 produces flat glyph outlines only.
curveSegments	Integer	12	Curve subdivision when converting font outlines to polygons.
bevelEnabled	Boolean	false	Adds a beveled chamfer around glyph edges for a rounded 3D look.
bevelThickness	Float	0.1	How far the bevel extends into the extruded depth.
bevelSize	Float	0.03	Width of the bevel chamfer.
bevelOffset	Float	0	Distance the bevel starts from the glyph outline.
bevelSegments	Integer	3	Smoothness of the bevel curve (more segments = rounder bevel).
uVScale	Vector2d	Vector2.new(1, 1)	Scales UV coordinates on the generated text geometry.
physicsEnabled	Boolean	false	Turns physics simulation on or off for this object. When disabled, the object keeps its visual transform but does not participate in collisions or forces.

Enum: HorizontalAlign

Enumeration of horizontal text alignment options.

Field Name	Description

Enum: VerticalAlign

Enumeration of vertical text alignment options.

Field Name	Description