Model API documentation
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.
How to get the normalized cursor value:
function init(self)
-- Get the cursor value on component "model"
cursor = go.get("#model", "cursor")
end
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
The animation playback rate. A multiplier to the animation playback rate. The type of the property is number.
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 current animation set on the component. The type of the property is hash.
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
The texture hash id of the model. Used for getting/setting model texture for unit 0-7
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
The material used when rendering the model. The type of the property is hash.
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
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
url - the model for which to play the animation
anim_id - id of the animation to play
playback - 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] - optional table with properties Play properties table:
blend_duration
offset
playback_rate
[complete_function] - function to call when the animation has completed.
self
message_id
"model_animation_done"
.message
animation_id
- the animation that was completed.playback
- the playback mode for the animation.sender
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
Cancels all animation on a model component.
url - the model for which to cancel the animation
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.
url - the model to query
bone_id - id of the corresponding bone
id - id of the game object
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
Enable or disable visibility of a mesh
url - the model
mesh_id - the id of the mesh
enabled - true if the mesh should be visible, false if it should be hideen
function init(self)
model.set_mesh_enabled("#model", "Sword", false) -- hide the sword
model.set_mesh_enabled("#model", "Axe", true) -- show the axe
end
Get the enabled state of a mesh
url - the model
mesh_id - the id of the mesh
enabled - true if the mesh is visible, false otherwise
function init(self)
if model.get_mesh_enabled("#model", "Sword") then
-- set properties specific for the sword
self.weapon_properties = game.data.weapons["Sword"]
end
end
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 - the id of the completed animation
playback - the playback mode of the completed animation
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