Skip to content

SgRibbon

Generates a flowing ribbon-like mesh along a path, often used for trails or motion effects. Useful for visualizing movement, magic spells, or streaks behind fast-moving objects. Shape, width, and tapering can be customized for different styles.

Inherits from

SceneObject

Usage

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

local SgRibbon = require 'engine/sceneobjects/sgribbon'

Reference

create

static create(self, options, parent)

Create a new ribbon 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.
SgRibbon.create({
    active = true,
    name = "",
    transform = Transform.new(),
    layers = {0},
    tags = {},
    receiveShadow = false,
    castShadow = false,
    material = nil,
    ringVertexCount = 16,
    pathStepCount = 16,
    startTime = 0,
    endTime = 1,
    closed = false,
    addCaps = true,
    vertexColors = true,
    ringFormulaX = 'cos(theta) * 0.5',
    ringFormulaY = '0',
    ringFormulaZ = 'sin(theta) * 0.5',
    pathFormulaX = '0',
    pathFormulaY = 'sin(t)',
    pathFormulaZ = 't',
    colorFormulaR = 'abs(sin(t))',
    colorFormulaG = '0',
    colorFormulaB = 'abs(cos(t))',
    scaleFormula = '1 + 0.3 * sin(t * 2)',
    twistFormula = 't * PI * 2',
    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.
ringVertexCount Integer 16 Vertices around the cross-section of the ribbon tube.
pathSteps Integer 16 Number of subdivisions along the path when generating the ribbon mesh.
startTime Float 0 Path parameter (0–1) where the ribbon begins along the curve.
endTime Float 1 Path parameter (0–1) where the ribbon ends along the curve.
uVScale Vector2d Vector2.new(1, 1) Scales texture coordinates on the generated ribbon surface.
closed Boolean false Connects the last path point back to the first to form a closed loop.
vertexColors Boolean true Uses per-vertex colors from the path when building the ribbon geometry.
x Formula cos(theta) * 0.5 Formula for X offset of the ribbon cross-section relative to the path.
y Formula 0 Formula for Y offset of the ribbon cross-section relative to the path.
z Formula sin(theta) * 0.5 Formula for Z offset of the ribbon cross-section relative to the path.
x Formula 0 Formula for X offset of the ribbon cross-section relative to the path.
y Formula sin(t) Formula for Y offset of the ribbon cross-section relative to the path.
z Formula t Formula for Z offset of the ribbon cross-section relative to the path.
scale Formula 1 + 0.3 * sin(t * 2) Formula controlling ribbon width along the path (can vary with path parameter).
twist Formula t * PI * 2 Formula controlling twist rotation along the path.
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.

updateGeometry

updateGeometry()

recreate the geometry of the ribbon. This can be called after changing any of the ribbon parameters that will invalidate the current geometry. It only makes sense to call when setAutoRecreate(false) was called before because otherwise changing any fields will trigger a regeneration of the ribbon anyway