SgMesh

Loads and renders static 3D mesh models. Supports textures, materials, and basic animation if provided. Central to placing custom geometry and detailed objects into the scene.

Inherits from

Usage

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

local SgMesh = require 'engine/sceneobjects/sgmesh'

Reference

class SgMesh
module:
create(options, parent)

Create a new mesh object in the scenegraph.

Parameters:

  • options (table) – A table of options to fill the parameters

  • parent (SceneObject) – The parent scene object to add this to

Returns:

a promise which will resolve to the created object

Return type:

Promise

Usage:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
-- Options can be omitted. This example shows the defaults,
-- only specify the ones you want different.
SgMesh:create({
    active = true,
    name = "",
    transform = Transform.new(),
    layers = {0},
    tags = {},
    receiveShadow = false,
    castShadow = false,
    material = nil,
    mesh = nil
})
getMeshCollectionEntry()
setMeshCollectionEntry(name)
Parameters:

name (any)

playAnimation(animationName)

Plays the specified animation on the mesh. Sets timeScale and weight of the animation to one.

Parameters:

animationName (str) – The name of the animation to play (mandatory).

Usage:

1
2
-- Example usage:
SgMesh:playAnimation("run")
stopAnimation(animationName)

Stops the specified animation on the mesh. Sets timeScale and weight of the animation to zero.

Parameters:

animationName (str) – The name of the animation to stop (mandatory).

Usage:

1
2
-- Example usage:
SgMesh:stopAnimation("run")
setAnimationWeight(animationName, targetWeight, transitionDuration, startValue)

Sets the weight of the specified animation.

Parameters:

  • animationName (str) – The name of the animation (mandatory).

  • targetWeight (number) – The target weight of the animation, between 0 and 1 (mandatory).

  • transitionDuration (number) – The duration to reach the target weight in seconds (optional). If it is not provided, takes the current value as the start value.

  • startValue (number) – The starting weight value (optional).

Usage:

1
2
-- Example usage:
SgMesh:setAnimationWeight("run", 0.8, 2, 0.2)
setAnimationTimeScale(animationName, targetTimeScale, transitionDuration, startValue)

Sets the time scale (playback speed) of the specified animation. Can be negative.

Parameters:

  • animationName (str) – The name of the animation (mandatory).

  • targetTimeScale (number) – The target time scale of the animation (mandatory). Can be negative to play the animation backwards.

  • transitionDuration (number) – The duration to reach the target time scale in seconds (optional).

  • startValue (number) – The starting time scale value (optional). Will be set immediately. If it is not provided, takes the current value as the start value.

Usage:

1
2
-- Example usage:
SgMesh:setAnimationTimeScale("run", 1.5, 3, 0.5)
setAnimationTime(animationName, animationTime)

Sets the relative playback time for the specified animation. Zero equals start, one equals end.

Parameters:

  • animationName (str) – The name of the animation (mandatory).

  • animationTime (number) – The playback time as a normalized value between 0 and 1 (mandatory).

Usage:

1
2
-- Example usage:
SgMesh:setAnimationTime("run", 0.5)
clampAnimation(animationName)

Pauses the specified animation on the last frame, preventing it from looping.

Parameters:

animationName (str) – The name of the animation to clamp (mandatory).

Usage:

1
2
-- Example usage:
SgMesh:clampAnimation("run")
unclampAnimation(animationName)

Unpauses the specified animation, allowing it to loop again.

Will prevent a clamp when the animation is about to be clamped.

Parameters:

animationName (str) – The name of the animation to unclamp (mandatory).

Usage:

1
2
-- Example usage:
SgMesh:unclampAnimation("run")
getAnimationDuration(animationName)

Gets the duration of the specified animation.

Parameters:

animationName (str) – The name of the animation (mandatory).

Returns:

The duration of the animation in seconds.

Return type:

number

Usage:

1
2
-- Example usage:
local duration = SgMesh:getAnimationDuration("run")
getAnimationWeight(animationName)

Gets the weight of the specified animation.

Parameters:

animationName (str) – The name of the animation (mandatory).

Returns:

The current weight of the animation, or nil if the animation does not exist.

Return type:

number or nil

Usage:

1
2
-- Example usage:
local weight = SgMesh:getAnimationWeight("run")
getAnimationTimeScale(animationName)

Gets the time scale (playback speed) of the specified animation.

Parameters:

animationName (str) – The name of the animation (mandatory).

Returns:

The current time scale of the animation, or nil if the animation does not exist.

Return type:

number or nil

Usage:

1
2
-- Example usage:
local timeScale = SgMesh:getAnimationTimeScale("run")

Examples