Skip to content

SgBillboard

Displays a 2D image or quad that always faces the camera, regardless of scene orientation. Commonly used for sprites, icons, particles, or simple UI elements placed in 3D space. Can be useful for optimizing visuals that don't need full 3D geometry.

Inherits from

SceneObject

Usage

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

local SgBillboard = require 'engine/sceneobjects/sgbillboard'

Reference

create

static create(self, options, parent)

Create a new billboard 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.
SgBillboard.create({
    active = true,
    name = "",
    transform = Transform.new(),
    layers = {0},
    tags = {},
    receiveShadow = false,
    castShadow = false
})

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 A Boolean attribute indicating whether the 3D object is static or not. Static objects can and will never be transformed during runtime.
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 Indicates if the 3D object is being rendered.
text Text Text
textAlignment Enum center The alignment of the text | Options: left, center, right
sizeAttenuation Boolean true Scales the Billboard with respect to distance to the camera.
size Float 1
textStrokeWidth Float 2 The width of the border of the text.
textStrokeColor Color Color.new(255, 255, 255, 255) The color of the border of the text.
textColor Color Color.new(0, 0, 0, 255) The infill color of the text.
padding Vector2d Vector2.new(5, 5) Two values controlling the vertical and horizontal padding size. Higher values increase the size of the padding.
paddingColor Color Color.new(255, 255, 255, 255) The background color of the padding section.
paddingLineColor Color Color.new(255, 255, 255, 255) The color of the border delimited by the padding.
paddingLineWidth Integer 1 The width of the border of the padding section.
border Vector2d Vector2.new(2, 2) Two values controlling the vertical and horizontal border size. Higher values increase the size of the border.
borderColor Color Color.new(255, 255, 255, 255) The background color of the border section.
borderLineColor Color Color.new(255, 255, 255, 255) The color of the outer border of the sprite.
borderLineWidth Integer 1 The width of the outer border.
outerRadius Integer 2 The outer radius of the sprite. Higher values increase the roundness.
innerRadius Integer 2 The inner radius of the sprite. Higher values increase the roundness.
uVScale Vector2d Vector2.new(1, 1)