Skip to Content
defold-typescript
Get startedGuidesAPILibraries
Defold

model

Model API documentation

Functions

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): { min: Vector3; max: Vector3 }

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: { min: Vector3; max: Vector3 } — model bounds; an empty model returns zero vectors

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})
end

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

model.get_mesh_aabb(url: string | Hash | Url): LuaMap<Hash, { min: Vector3; max: Vector3 }>

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: LuaMap<Hash, { min: Vector3; max: Vector3 }> — 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
end

Parameters

  • url: string | Hash | Url — the model
  • mesh_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: Exclude<go.Playback, typeof go.PLAYBACK_NONE>, play_properties?: { blend_duration?: number; offset?: number; playback_rate?: number }, 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_FORWARD
  • go.PLAYBACK_ONCE_BACKWARD
  • go.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)
end

Parameters

  • url: string | Hash | Url — the model for which to play the animation
  • anim_id: string | Hash — id of the animation to play
  • playback: Exclude<go.Playback, typeof go.PLAYBACK_NONE> — playback mode of the animation
  • play_properties?: { blend_duration?: number; offset?: number; playback_rate?: number } — optional playback properties
  • complete_function?: (self: unknown, message_id: Hash, message: BuiltinMessages["model_animation_done"]) => void — function to call when the animation has completed. self script_instance The current script instance. message_id hash The name of the completion message, "model_animation_done". message message.model.model_animation_done Information about the completion. sender url The invoker of the callback: the model component.

model.reset_constant(url: string | Hash | Url, constant: string | Hash): void

  • 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")
end

Parameters

  • url: string | Hash | Url — the model that should have a constant reset.
  • constant: string | Hash — name of the constant.

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
end

Parameters

  • url: string | Hash | Url — the model
  • mesh_id: string | Hash — the id of the mesh
  • enabled: 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: Hash

  • 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).

On this page