3D skinned animation

Skeletal animation of 3D models use the bones of the model to apply deformation to vertices in the model.

For details on how to import 3D data into a Model for animation, see the Model documentation.

Playing animations

Models are animated with the model.play_anim() function:

function init(self)
    -- Start the "wiggle" animation back and forth on #model
    model.play_anim("#model", "wiggle", go.PLAYBACK_LOOP_PINGPONG)
end

The bone hierarchy

The bones in the Model skeleton are represented internally as game objects.

You can retrieve the instance id of the bone game object in runtime. The function model.get_go() returns the id of the game object for the specified bone.

-- Get the middle bone go of our wiggler model
local bone_go = model.get_go("#wiggler", "Bone_002")

-- Now do something useful with the game object...

Cursor animation

In addition to using the model.play_anim() to advance a model animation, Model components expose a “cursor” property that can be manipulated with go.animate() (more about property animations):

-- Set the animation on #model but don't start it
model.play_anim("#model", "wiggle", go.PLAYBACK_NONE)
-- Set the cursor to the beginning of the animation
go.set("#model", "cursor", 0)
-- Tween the cursor between 0 and 1 pingpong with in-out quad easing.
go.animate("#model", "cursor", go.PLAYBACK_LOOP_PINGPONG, 1, go.EASING_INOUTQUAD, 3)

Completion callbacks

The model animation model.play_anim()) support an optional Lua callback function as the last argument. This function will be called when the animation has played to the end. The function is never called for looping animations, nor when an animation is manually canceled via go.cancel_animations(). The callback can be used to trigger events on animation completion or to chain multiple animations together.

local function wiggle_done(self, message_id, message, sender)
    -- Done animating
end

function init(self)
    model.play_anim("#model", "wiggle", go.PLAYBACK_ONCE_FORWARD, nil, wiggle_done)
end

Playback Modes

Animations can be played either once or in a loop. How the animation plays is determined by the playback mode:

• go.PLAYBACK_NONE
• go.PLAYBACK_ONCE_FORWARD
• go.PLAYBACK_ONCE_BACKWARD
• go.PLAYBACK_ONCE_PINGPONG
• go.PLAYBACK_LOOP_FORWARD
• go.PLAYBACK_LOOP_BACKWARD
• go.PLAYBACK_LOOP_PINGPONG