Model API documentation

Version: beta

FUNCTION
model.play_anim() play an animation on a model
model.cancel() cancel all animation on a model
model.get_go() retrieve the game object corresponding to a model skeleton bone
MESSAGE
model_animation_done reports the completion of a Model animation
PROPERTIES
cursor number model cursor
playback_rate number model playback_rate
animation hash model animation
textureN hash model textureN where N is 0-7
material hash model material

Functions

model.play_anim()

model.play_anim(url,anim_id,playback,[play_properties],[complete_function])

Plays an animation on a model component with specified playback mode and parameters. An optional completion callback function can be provided that will be called when the animation has completed playing. If no function is provided, a model_animation_done message is sent to the script that started the animation. The callback is not called (or message sent) if the animation is cancelled with model.cancel. The callback is called (or message sent) only for animations that play with the following playback modes:

  • go.PLAYBACK_ONCE_FORWARD
  • go.PLAYBACK_ONCE_BACKWARD
  • go.PLAYBACK_ONCE_PINGPONG

PARAMETERS

url string, hash, url the model for which to play the animation
anim_id string, hash id of the animation to play
playback constant playback mode of the animation
  • go.PLAYBACK_ONCE_FORWARD
  • go.PLAYBACK_ONCE_BACKWARD
  • go.PLAYBACK_ONCE_PINGPONG
  • go.PLAYBACK_LOOP_FORWARD
  • go.PLAYBACK_LOOP_BACKWARD
  • go.PLAYBACK_LOOP_PINGPONG
[play_properties] table optional table with properties Play properties table:
blend_duration
number Duration of a linear blend between the current and new animation.
offset
number The normalized initial value of the animation cursor when the animation starts playing.
playback_rate
number The rate with which the animation will be played. Must be positive.
[complete_function] function(self, message_id, message, sender) function to call when the animation has completed.
self
object The current object.
message_id
hash The name of the completion message, "model_animation_done".
message
table Information about the completion:
  • hash animation_id - the animation that was completed.
  • constant playback - the playback mode for the animation.
sender
url The invoker of the callback: the model component.

EXAMPLES

The following examples assumes that the model has id "model". How to play the "jump" animation followed by the "run" animation: 
local function anim_done(self, message_id, message, sender)
  if message_id == hash("model_animation_done") then
    if message.animation_id == hash("jump") then
      -- open animation done, chain with "run"
      local properties = { blend_duration = 0.2 }
      model.play_anim(url, "run", go.PLAYBACK_LOOP_FORWARD, properties, anim_done)
    end
  end
end

function init(self)
    local url = msg.url("#model")
    local play_properties = { blend_duration = 0.1 }
    -- first blend during 0.1 sec into the jump, then during 0.2 s into the run animation
    model.play_anim(url, "jump", go.PLAYBACK_ONCE_FORWARD, play_properties, anim_done)
end

model.cancel()

model.cancel(url)

Cancels all animation on a model component.

PARAMETERS

url string, hash, url the model for which to cancel the animation

model.get_go()

model.get_go(url,bone_id)

Gets the id of the game object that corresponds to a model skeleton bone. The returned game object can be used for parenting and transform queries. This function has complexity O(n), where n is the number of bones in the model skeleton. Game objects corresponding to a model skeleton bone can not be individually deleted.

PARAMETERS

url string, hash, url the model to query
bone_id string, hash id of the corresponding bone

RETURNS

id hash id of the game object

EXAMPLES

The following examples assumes that the model component has id "model". How to parent the game object of the calling script to the "right_hand" bone of the model in a player game object: 
function init(self)
    local parent = model.get_go("player#model", "right_hand")
    msg.post(".", "set_parent", {parent_id = parent})
end

Messages

model_animation_done

This message is sent when a Model animation has finished playing back to the script that started the animation. No message is sent if a completion callback function was supplied when the animation was started. No message is sent if the animation is cancelled with model.cancel(). This message is sent only for animations that play with the following playback modes:

  • go.PLAYBACK_ONCE_FORWARD
  • go.PLAYBACK_ONCE_BACKWARD
  • go.PLAYBACK_ONCE_PINGPONG

animation_id hash the id of the completed animation
playback constant the playback mode of the completed animation

EXAMPLES

function on_message(self, message_id, message, sender)
  if message_id == hash("model_animation_done") then
    if message.animation_id == hash("run") and message.playback == go.PLAYBACK_ONCE_FORWARD then
      -- The animation "run" has finished running forward.
    end
  end
end

Properties

cursor

The normalized animation cursor. The type of the property is number. Please note that model events may not fire as expected when the cursor is manipulated directly.

EXAMPLES

How to get the normalized cursor value: 
function init(self)
  -- Get the cursor value on component "model"
  cursor = go.get("#model", "cursor")
end
How to animate the cursor from 0.0 to 1.0 using linear easing for 2.0 seconds: 
function init(self)
  -- Get the current value on component "model"
  go.set("#model", "cursor", 0.0)
  -- Animate the cursor value
  go.animate("#model", "cursor", go.PLAYBACK_LOOP_FORWARD, 1.0, go.EASING_LINEAR, 2)
end

playback_rate

The animation playback rate. A multiplier to the animation playback rate. The type of the property is number.

EXAMPLES

How to set the playback_rate on component "model" to play at double the current speed: 
function init(self)
  -- Get the current value on component "model"
  playback_rate = go.get("#model", "playback_rate")
  -- Set the playback_rate to double the previous value.
  go.set("#model", "playback_rate", playback_rate * 2)
end
The playback_rate is a non-negative number, a negative value will be clamped to 0.

animation

The current animation set on the component. The type of the property is hash.

EXAMPLES

How to read the current animation from a model component: 
function init(self)
  -- Get the current animation on component "model"
  local animation = go.get("#model", "animation")
  if animation == hash("run_left") then
    -- Running left. Do something...
  end
end

textureN

The texture hash id of the model. Used for getting/setting model texture for unit 0-7

EXAMPLES

How to set texture using a script property (see resource.texture): 
go.property("my_texture", texture("/texture.png"))
function init(self)
  go.set("#model", "texture0", self.my_texture)
end
See resource.set_texture for an example on how to set the texture of an atlas.

material

The material used when rendering the model. The type of the property is hash.

EXAMPLES

How to set material using a script property (see resource.material): 
go.property("my_material", resource.material("/material.material"))
function init(self)
  go.set("#model", "material", self.my_material)
end