Skip to Content
defold-typescript
Get startedGuidesAPILibraries
Defold

sprite

Sprite API documentation

Functions

sprite.play_flipbook(2 overloads): void

Play an animation on a sprite component from its tile set An optional completion callback function can be provided that will be called when the animation has completed playing. If no function is provided, a animation_done message is sent to the script that started the animation.

  1. (url: string | Hash | Url, id: string | Hash, complete_function?: (self: unknown, message_id: Hash, message: { current_tile: number; id: Hash }, sender: Url) => void)

  2. (url: string | Hash | Url, id: string | Hash, complete_function: ((self: unknown, message_id: Hash, message: { current_tile: number; id: Hash }, sender: Url) => void) | undefined, play_properties: { offset?: number; playback_rate?: number })

    Parameters

    • url: string | Hash | Url — the sprite that should play the animation
    • id: string | Hash — hashed id of the animation to play
    • complete_function: ((self: unknown, message_id: Hash, message: { current_tile: number; id: Hash }, sender: Url) => void) | undefined — function to call when the animation has completed. self script_instance The current script instance. message_id hash The name of the completion message, "animation_done". message message.sprite.animation_done Information about the completion. sender url The invoker of the callback: the sprite component.
    • play_properties: { offset?: number; playback_rate?: number } — optional playback properties

The following examples assumes that the model has id "sprite". How to play the "jump" animation followed by the "run" animation:

const url = msg.url("#sprite");

function anim_done(self: unknown, message_id: Hash, message: { id: Hash }) {
  if (message_id === hash("animation_done") && message.id === hash("jump")) {
    // jump animation done, chain with "run"
    sprite.play_flipbook(url, "run");
  }
}
local function anim_done(self, message_id, message, sender)
  if message_id == hash("animation_done") then
    if message.id == hash("jump") then
      -- jump animation done, chain with "run"
      sprite.play_flipbook(url, "run")
    end
  end
end
export default defineScript({
  init() {
    const url = msg.url("#sprite");
    sprite.play_flipbook(url, "jump", (self, message_id, message) => {
      if (message_id === hash("animation_done") && message.id === hash("jump")) {
        // jump animation done, chain with "run"
        sprite.play_flipbook(url, "run");
      }
    });
  },
});
function init(self)
  local url = msg.url("#sprite")
  sprite.play_flipbook(url, "jump", anim_done)
end

sprite.reset_constant(url: string | Hash | Url, constant: string | Hash): voidD

  • Deprecated since 1.13.0

Resets a shader constant for a sprite component. The constant must be defined in the material assigned to the sprite. Resetting a constant through this function implies that the value defined in the material will be used. Which sprite to reset a constant for is identified by the URL.

sprite.reset_constant("#sprite", "tint");
function init(self)
  sprite.reset_constant("#sprite", "tint")
end

Parameters

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

sprite.set_hflip(url: string | Hash | Url, flip: boolean): void

Sets horizontal flipping of the provided sprite's animations. The sprite is identified by its URL. If the currently playing animation is flipped by default, flipping it again will make it appear like the original texture. The sprite is flipped around the pivot of its image, which gives the same result as a negative x scale.

// How to flip a sprite so it faces the horizontal movement (it is assumed that
// the sprite component has id "sprite" and the original animation faces right):
export default defineScript({
  init() {
    return { velocity: vmath.vector3() };
  },

  update(self, dt) {
    // calculate self.velocity somehow
    sprite.set_hflip("#sprite", self.velocity.x < 0);
  },
});
function update(self, dt)
  -- calculate self.velocity somehow
  sprite.set_hflip("#sprite", self.velocity.x < 0)
end

Parameters

  • url: string | Hash | Url — the sprite that should flip its animations
  • flip: boolean — true if the sprite should flip its animations, false if not

sprite.set_vflip(url: string | Hash | Url, flip: boolean): void

Sets vertical flipping of the provided sprite's animations. The sprite is identified by its URL. If the currently playing animation is flipped by default, flipping it again will make it appear like the original texture. The sprite is flipped around the pivot of its image, which gives the same result as a negative y scale.

// How to flip a sprite in a game which negates gravity as a game mechanic (it is
// assumed that the sprite component has id "sprite" and the original animation
// is up-right):
export default defineScript({
  init() {
    return { up_side_down: false };
  },

  update(self, dt) {
    // calculate self.up_side_down somehow, then:
    sprite.set_vflip("#sprite", self.up_side_down);
  },
});
function update(self, dt)
  -- calculate self.up_side_down somehow, then:
  sprite.set_vflip("#sprite", self.up_side_down)
end

Parameters

  • url: string | Hash | Url — the sprite that should flip its animations
  • flip: boolean — true if the sprite should flip its animations, false if not

Properties

animation: Hash

READ ONLY The current animation id. An animation that plays currently for the sprite. The type of the property is hash.

cursor: number

The normalized animation cursor. The type of the property is number.

frame_count: Hash

READ ONLY The frame count of the currently playing animation.

image: Hash

The image used when rendering the sprite. The type of the property is hash.

material: Hash

The material used when rendering the sprite. 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. The playback_rate is a non-negative number, a negative value will be clamped to 0.

scale: Vector3

The non-uniform scale of the sprite. The type of the property is vector3.

size: Vector3

The size of the sprite, not allowing for any additional scaling that may be applied. The type of the property is vector3. It is not possible to set the size if the size mode of the sprite is set to auto.

slice: Vector4

The slice values of the sprite. The type of the property is a vector4 that corresponds to the left, top, right, bottom values of the sprite in the editor. It is not possible to set the slice property if the size mode of the sprite is set to auto.

On this page