model2 new1 changed1 deprecated
Model API documentation
Functions
model.cancel(url: string | Hash | Url): voidmodel.get_aabb(url: string | Hash | Url):model.Aabbmodel.get_blend_weights(url: string | Hash | Url): number[]Nmodel.get_go(url: string | Hash | Url, bone_id: string | Hash): Hashmodel.get_mesh_aabb(url: string | Hash | Url): LuaTable<Hash,model.Aabb>model.get_mesh_enabled(url: string | Hash | Url, mesh_id: string | Hash): booleanmodel.play_anim(url: string | Hash | Url, anim_id: string | Hash, playback:go.Playback, play_properties?:model.PlayProperties, complete_function?: (self: unknown, message_id: Hash, message: BuiltinMessages["model_animation_done"]) => void): voidmodel.reset_constant(url: string | Hash | Url, constant: string | Hash): voidDmodel.set_blend_weights(url: string | Hash | Url, weights?: number[]): voidNmodel.set_mesh_enabled(url: string | Hash | Url, mesh_id: string | Hash, enabled: boolean): void
model.cancel(url: string | Hash | Url): void
Cancels all animation on a model component.
Parameters
url:string | Hash | Url— the model for which to cancel the animation
model.get_aabb(url: string | Hash | Url): model.Aabb
Get AABB of the whole model in local coordinate space.
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_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) }Parameters
url:string | Hash | Url— the model
Returns
aabb:model.Aabb— model bounds; an empty model returns zero vectors
model.get_blend_weights(url: string | Hash | Url): number[]N
- Since Defold 1.13.0
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).
const w = model.get_blend_weights("#model");
w.forEach((weight, i) => {
print(i + 1, weight);
});
// change the data in the table and then set the weights again
w[0] = 0.75;
w[1] = 0.25;
model.set_blend_weights("#model", w);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)Parameters
url:string | Hash | Url— the model component
Returns
weights:number[]— array of weight values, or empty table if the model has no morph targets
model.get_go(url: string | Hash | Url, bone_id: string | Hash): 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.
// The following examples assume 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:
export default defineScript({
init(self) {
const parent = model.get_go("player#model", "right_hand");
msg.post(".", "set_parent", { parent_id: parent });
},
});function init(self)
local parent = model.get_go("player#model", "right_hand")
msg.post(".", "set_parent", {parent_id = parent})
endParameters
url:string | Hash | Url— the model to querybone_id:string | Hash— id of the corresponding bone
Returns
id:Hash— id of the game object
model.get_mesh_aabb(url: string | Hash | Url): LuaTable<Hash, model.Aabb>
Get AABB of all meshes.
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_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) } }Parameters
url:string | Hash | Url— the model
Returns
aabb:LuaTable<Hash, model.Aabb>— mesh bounds keyed by mesh identifier
model.get_mesh_enabled(url: string | Hash | Url, mesh_id: string | Hash): boolean
Get the enabled state of a mesh
// shared weapon data, e.g. required from your own module
const game = { data: { weapons: { Sword: { damage: 10 } } } };
export default defineScript({
init() {
if (model.get_mesh_enabled("#model", "Sword")) {
// set properties specific for the sword
return { weapon_properties: game.data.weapons["Sword"] };
}
return { weapon_properties: undefined };
},
});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
endParameters
url:string | Hash | Url— the modelmesh_id:string | Hash— the id of the mesh
Returns
enabled:boolean— true if the mesh is visible, false otherwise
model.play_anim(url: string | Hash | Url, anim_id: string | Hash, playback: go.Playback, play_properties?: model.PlayProperties, complete_function?: (self: unknown, message_id: Hash, message: BuiltinMessages["model_animation_done"]) => void): void
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_FORWARDgo.PLAYBACK_ONCE_BACKWARDgo.PLAYBACK_ONCE_PINGPONG
// The following examples assume that the model has id "model".
// How to play the "jump" animation followed by the "run" animation:
const url = msg.url("#model");
function anim_done(self: unknown, message_id: Hash, message: { animation_id: Hash }) {
if (message_id === hash("model_animation_done")) {
if (message.animation_id === hash("jump")) {
// open animation done, chain with "run"
const properties = { blend_duration: 0.2 };
model.play_anim(url, "run", go.PLAYBACK_LOOP_FORWARD, properties, anim_done);
}
}
}
export default defineScript({
init(self) {
const 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);
},
});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)
endParameters
url:string | Hash | Url— the model for which to play the animationanim_id:string | Hash— id of the animation to playplayback:go.Playback— playback mode of the animationplay_properties?:model.PlayProperties— optional playback propertiescomplete_function?:(self: unknown, message_id: Hash, message: BuiltinMessages["model_animation_done"]) => void— function to call when the animation has completed.selfscript_instance The current script instance.message_idhash The name of the completion message,"model_animation_done".messagemessage.model.model_animation_done Information about the completion.senderurl The invoker of the callback: the model component.
model.reset_constant(url: string | Hash | Url, constant: string | Hash): voidD
- Deprecated since 1.13.0
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.
model.reset_constant("#model", "tint");function init(self)
model.reset_constant("#model", "tint")
endParameters
url:string | Hash | Url— the model that should have a constant reset.constant:string | Hash— name of the constant.
model.set_blend_weights(url: string | Hash | Url, weights?: number[]): voidN
- Since Defold 1.13.0
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).
// 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-- 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 overrideParameters
url:string | Hash | Url— the model componentweights?:number[]— array of weight values (1-based indices). Omit or passnilto clear the override and return morphs to animation only
model.set_mesh_enabled(url: string | Hash | Url, mesh_id: string | Hash, enabled: boolean): void
Enable or disable visibility of a mesh
export default defineScript({
init(self) {
model.set_mesh_enabled("#model", "Sword", false); // hide the sword
model.set_mesh_enabled("#model", "Axe", true); // show the axe
},
});function init(self)
model.set_mesh_enabled("#model", "Sword", false) -- hide the sword
model.set_mesh_enabled("#model", "Axe", true) -- show the axe
endParameters
url:string | Hash | Url— the modelmesh_id:string | Hash— the id of the meshenabled:boolean— true if the mesh should be visible, false if it should be hideen
Properties
animation: Hash
The current animation set on the component. The type of the property is hash.
cursor: number
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.
material: HashC
- Removed in Defold 1.13.0
The material used when rendering the model. The type of the property is hash.
playback_rate: number
The animation playback rate. A multiplier to the animation playback rate. The type of the property is number.
textureN: Hash
The texture hash id of the model, read and written on the texture unit the key's number names (texture3 is unit 3).