Model API documentation
Version: alpha (1.14.2)
| RECORDS | |
|---|---|
| model.aabb | Axis-aligned bounding box |
| model.animation_layer_options | Model animation layer options |
| model.cancel_options | Model animation cancellation options |
| model.play_properties | Model animation playback properties |
| FUNCTIONS | |
|---|---|
| model.animation_layer() | create a reusable animation layer |
| model.cancel() | cancel animation on a model |
| model.destroy_animation_layer() | destroy an animation layer definition |
| model.get_aabb() | get the AABB of the whole model in local coordinate space |
| model.get_blend_weights() | get current morph (blend shape) weights |
| model.get_go() | retrieve the game object corresponding to a model skeleton bone |
| model.get_mesh_aabb() | get the AABB of all meshes |
| model.get_mesh_enabled() | get the enabled state of a mesh |
| model.play_anim() | play an animation on a model |
| model.reset_constant() | DEPRECATED! reset a shader constant for a model |
| model.set_blend_weights() | set morph (blend shape) weights from a table |
| model.set_mesh_enabled() | enable or disable a mesh |
| MESSAGES | |
|---|---|
| model_animation_done | reports the completion of a Model animation |
| PROPERTIES | |
|---|---|
| animation | hash model animation |
| cursor | number model cursor |
| playback_rate | number model playback_rate |
| textureN | hash model textureN where N is 0-7 |
Axis-aligned bounding box
FIELDS
min |
vector3 |
minimum local-space bounds |
max |
vector3 |
maximum local-space bounds |
Model animation layer options
FIELDS
order |
integer |
positive evaluation order; names and orders must be unique among layers on a model |
[weight] |
number |
influence in [0, 1], defaults to 1; a zero-weight layer still advances and completes |
[bones] |
(string|hash)[] |
bone names whose subtrees are selected; omit or pass an empty array to select all bones; names must exist on each target model |
Model animation cancellation options
FIELDS
[layer] |
number |
handle returned by model.animation_layer; omit to cancel all animation |
Model animation playback properties
FIELDS
[blend_duration] |
number |
duration of a linear blend from the current animation |
[offset] |
number |
normalized initial animation cursor |
[layer] |
number |
animation layer returned by model.animation_layer; omit to play on the base layer |
[playback_rate] |
number |
positive animation playback rate |
model.animation_layer(name:string|hash, options:model.animation_layer_options)→layer_id:number
Creates an immutable layer definition, independent of any model component.
Reuse the returned handle in the layer property of model.play_anim.
Each model keeps its own playback cursor, crossfade and completion callback.
Release the definition with model.destroy_animation_layer when it is no longer
needed. Storing or discarding the numeric handle does not affect its lifetime.
Destroying a handle prevents reuse but leaves existing playback undisturbed.
The base animation is evaluated first, followed by layers in increasing order.
Layers override the pose beneath them with their weight; weights are not normalized.
Masks select local bone transforms, including descendants of each listed bone.
Bones still inherit movement from their parents. Missing animation channels use
the skeleton's rest transforms. Additional layers only affect skeletal animation.
PARAMETERS
name |
stringhash |
non-empty layer name |
options |
model.animation_layer_options |
layer configuration, copied at creation |
RETURNS
layer_id |
number |
opaque layer handle |
EXAMPLES
local upper_body = model.animation_layer("upper_body", {
order = 1, weight = 0.8, bones = { "spine" }
})
function init(self)
model.play_anim("#model", "run", go.PLAYBACK_LOOP_FORWARD)
model.play_anim("#model", "wave", go.PLAYBACK_ONCE_FORWARD, { layer = upper_body })
end
model.cancel(url:string|hash|url, [options:model.cancel_options])
Without a layer, cancels all animation, freezes the base pose and releases additional layers, without invoking their completion callbacks. With a layer, removes only that layer from this model. Its contribution disappears on the next pose update, revealing the base and remaining layers. Their playback is unaffected. The cancelled layer's completion callback is not invoked. Cancelling a layer that is not attached to the model has no effect. The handle remains reusable and other models using it are unaffected.
PARAMETERS
url |
stringhashurl |
the model for which to cancel the animation |
[options] |
model.cancel_options |
optional cancellation properties |
EXAMPLES
model.cancel("#model", { layer = upper_body })
model.destroy_animation_layer(layer_id:number)
Invalidates a handle returned by model.animation_layer. Further use of the handle, including another destroy, raises an error. Existing animations continue and keep the definition alive until cancelled or their model is destroyed/reloaded. Once-mode animations retain their final pose. Cancel individual layers before destroying their handle if their contribution should be removed immediately. Remaining definitions are released when the script context is finalized.
PARAMETERS
layer_id |
number |
opaque animation layer handle |
model.get_aabb(url:string|hash|url)→aabb:model.aabb
Get AABB of the whole model in local coordinate space.
PARAMETERS
url |
stringhashurl |
the model |
RETURNS
aabb |
model.aabb |
model bounds; an empty model returns zero vectors |
EXAMPLES
model.get_aabb("#model") -> { min = vmath.vector3(-2.5, -3.0, 0), max = vmath.vector3(1.5, 5.5, 0) }
model.get_aabb("#empty") -> { min = vmath.vector3(0, 0, 0), max = vmath.vector3(0, 0, 0) }
model.get_blend_weights(url:string|hash|url)→weights:number[]
Returns a table of numbers with one entry per morph target on the first mesh of the model that has morph targets. Values reflect the rig state at call time (after animation, and any active script override from model.set_blend_weights).
PARAMETERS
url |
stringhashurl |
the model component |
RETURNS
weights |
number[] |
array of weight values, or empty table if the model has no morph targets |
EXAMPLES
local w = model.get_blend_weights("#model")
for i = 1, #w do
print(i, w[i])
end
-- change the data in the table and then set the weights again
w[1] = 0.75
w[2] = 0.25
model.set_blend_weights("#model", w)
model.get_go(url:string|hash|url, bone_id:string|hash)→id:hash
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 |
stringhashurl |
the model to query |
bone_id |
stringhash |
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
model.get_mesh_aabb(url:string|hash|url)→aabb:table<hash, model.aabb>
Get AABB of all meshes.
PARAMETERS
url |
stringhashurl |
the model |
RETURNS
aabb |
table<hash, model.aabb> |
mesh bounds keyed by mesh identifier |
EXAMPLES
model.get_mesh_aabb("#model") -> { hash("Sword") = { min = vmath.vector3(-0.5, -0.5, 0), max = vmath.vector3(0.5, 0.5, 0) }, hash("Shield") = { min = vmath.vector3(-0.5, -0.5, -0.5), max = vmath.vector3(0.5, 0.5, 0.5) } }
model.get_mesh_enabled(url:string|hash|url, mesh_id:string|hash|url)→enabled:boolean
Get the enabled state of a mesh
PARAMETERS
url |
stringhashurl |
the model |
mesh_id |
stringhashurl |
the id of the mesh |
RETURNS
enabled |
boolean |
true if the mesh is visible, false otherwise |
EXAMPLES
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
model.play_anim(url:string|hash|url, anim_id:string|hash, playback:go.PLAYBACK, [play_properties:model.play_properties], [complete_function:fun(self:script_instance, message_id:hash, message:message.model.model_animation_done, sender:url)])
Plays an animation on a model component with specified playback
mode and parameters.
With play_properties.layer, only playback on that layer is replaced. Other
layers and base playback continue independently. blend_duration crossfades
within the selected layer, or fades its influence in on first use. Once-mode
animations hold their final pose until replaced or cancelled. Layered completion
callbacks and messages include the layer name hash in message.layer.
Base playback omits this field. Callback arguments are unchanged.
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_FORWARDgo.PLAYBACK_ONCE_BACKWARDgo.PLAYBACK_ONCE_PINGPONGPARAMETERS
url |
stringhashurl |
the model for which to play the animation |
anim_id |
stringhash |
id of the animation to play |
playback |
go.PLAYBACK |
playback mode of the animation |
[play_properties] |
model.play_properties |
optional playback properties |
[complete_function] |
function(
self:script_instance,
message_id:hash,
message:message.model.model_animation_done,
sender:url) |
function to call when the animation has completed.
|
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.reset_constant(url:string|hash|url, constant:string|hash)
Resets a shader constant for a model component. The constant must be defined in the material assigned to the model. Resetting a constant through this function implies that the value defined in the material will be used. Which model to reset a constant for is identified by the URL.
PARAMETERS
url |
stringhashurl |
the model that should have a constant reset. |
constant |
stringhash |
name of the constant. |
EXAMPLES
The following examples assumes that the model has id "model" and that the default-material in builtins is used, which defines the constant "tint". If you assign a custom material to the model, you can reset the constants defined there in the same manner. How to reset the tinting of a model:function init(self)
model.reset_constant("#model", "tint")
end
model.set_blend_weights(url:string|hash|url, [weights:number[]|nil])
Copies numeric values from weights into each morph target slot for every mesh on the model that has morph targets.
At most as many weights are applied as each mesh has morph targets; extra entries in the table are ignored.
Missing weights leave the tail zero-filled for meshes with more targets than entries.
The override is re-applied every frame after animations run, until cleared by omitting weights or passing nil.
To reset the weights, use model.set_blend_weights(url) or model.set_blend_weights(url, nil).
PARAMETERS
url |
stringhashurl |
the model component |
[weights] |
number[]nil |
array of weight values (1-based indices). Omit or pass nil to clear the override and return morphs to animation only
|
EXAMPLES
-- set the weights for the first 4 morph targets
model.set_blend_weights("#model", { 0, 1, 0.5, 0 })
-- clear the override, animation will continue if the weights are driven by an animation
model.set_blend_weights("#model") -- clear script override
model.set_mesh_enabled(url:string|hash|url, mesh_id:string|hash|url, enabled:boolean)
Enable or disable visibility of a mesh
PARAMETERS
url |
stringhashurl |
the model |
mesh_id |
stringhashurl |
the id of the mesh |
enabled |
boolean |
true if the mesh should be visible, false if it should be hideen |
EXAMPLES
function init(self)
model.set_mesh_enabled("#model", "Sword", false) -- hide the sword
model.set_mesh_enabled("#model", "Axe", true) -- show the axe
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_FORWARDgo.PLAYBACK_ONCE_BACKWARDgo.PLAYBACK_ONCE_PINGPONGanimation_id |
hash |
the id of the completed animation |
playback |
go.PLAYBACK |
the playback mode of the completed animation |
layer |
hash |
the layer name for layered playback; absent for base playback |
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
The current animation set on the component. The type of the property is hash.
Pass { key = hash("layer_name") } in the go.get
options to address a layer on this model. Omit the key to address base playback.
The name remains usable while the model retains the layer, even after its handle is destroyed.
This property is read-only; use model.play_anim to change the animation.
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
The normalized animation cursor. The type of the property is number.
Pass { key = hash("layer_name") } in the go.get
options to address a layer on this model. Omit the key to address base playback.
The name remains usable while the model retains the layer, even after its handle is destroyed.
Please note that model events may not fire as expected when the cursor is manipulated directly.
go.set accepts the same selector. Changes affect only this model's layer playback.
EXAMPLES
How to read and change a layer's cursor by name:local cursor = go.get("#model", "cursor", { key = hash("upper_body") })
go.set("#model", "cursor", cursor, { key = hash("upper_body") })
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.
Pass { key = hash("layer_name") } in the go.get
options to address a layer on this model. Omit the key to address base playback.
The name remains usable while the model retains the layer, even after its handle is destroyed.
go.set accepts the same selector. Changes affect only this model's layer playback.
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 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