Sprite API documentation

Version: beta

Functions, messages and properties used to manipulate sprite components.

FUNCTION
sprite.play_flipbook()	Play an animation on a sprite component
sprite.reset_constant()	reset a shader constant for a sprite
sprite.set_constant()	set a shader constant for a sprite
sprite.set_hflip()	set horizontal flipping on a sprite's animations
sprite.set_vflip()	set vertical flipping on a sprite's animations

MESSAGE
animation_done	reports that an animation has completed
play_animation	play a sprite animation

PROPERTIES
cursor	number sprite cursor
image	hash sprite image
material	hash sprite material
playback_rate	number sprite playback_rate
scale	vector3 sprite scale
size	vector3 sprite size

Functions

sprite.play_flipbook()

sprite.play_flipbook(url,id,[complete_function],[play_properties])

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.

PARAMETERS

`url`	string \| hash \| url the sprite that should play the animation
`id`	hash name hash of the animation to play
`[complete_function]`	function(self, message_id, message, sender)) function to call when the animation has completed. `self` object The current object. `message_id` hash The name of the completion message, `"animation_done"`. `message` table Information about the completion: number `current_tile` - the current tile of the sprite. hash `id` - id of the animation that was completed. `sender` url The invoker of the callback: the sprite component.
`[play_properties]`	table optional table with properties: `offset` number the normalized initial value of the animation cursor when the animation starts playing. `playback_rate` number the rate with which the animation will be played. Must be positive.

EXAMPLES

The following examples assumes that the model has id "sprite".

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.id == hash("jump") then
      -- open animation done, chain with "run"
      sprite.play_flipbook(url, "run")
    end
  end
end

function init(self)
  local url = msg.url("#sprite")
  sprite.play_flipbook(url, "jump", anim_done)
end

sprite.reset_constant()

sprite.reset_constant(url,constant)

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.

PARAMETERS

`url`	string \| hash \| url the sprite that should have a constant reset
`constant`	string \| hash name of the constant

EXAMPLES

The following examples assumes that the sprite has id "sprite" and that the default-material in builtins is used, which defines the constant "tint". If you assign a custom material to the sprite, you can reset the constants defined there in the same manner.

How to reset the tinting of a sprite:

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

sprite.set_constant()

sprite.set_constant(url,constant,value)

Sets a shader constant for a sprite component. The constant must be defined in the material assigned to the sprite. Setting a constant through this function will override the value set for that constant in the material. The value will be overridden until sprite.reset_constant is called. Which sprite to set a constant for is identified by the URL.

PARAMETERS

`url`	string \| hash \| url the sprite that should have a constant set
`constant`	string \| hash name of the constant
`value`	vector4 of the constant

EXAMPLES

The following examples assumes that the sprite has id "sprite" and that the default-material in builtins is used, which defines the constant "tint". If you assign a custom material to the sprite, you can set the constants defined there in the same manner.

How to tint a sprite red:

function init(self)
  sprite.set_constant("#sprite", "tint", vmath.vector4(1, 0, 0, 1))
end

sprite.set_hflip()

sprite.set_hflip(url,flip)

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.

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

EXAMPLES

How to flip a sprite so it faces the horizontal movement:

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

It is assumed that the sprite component has id "sprite" and that the original animations faces right.

sprite.set_vflip()

sprite.set_vflip(url,flip)

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.

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

EXAMPLES

How to flip a sprite in a game which negates gravity as a game mechanic:

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

It is assumed that the sprite component has id "sprite" and that the original animations are up-right.

Messages

animation_done

reports that an animation has completed

This message is sent to the sender of a play_animation message when the animation has completed.

Note that this message is sent only for animations that play with the following playback modes:

Once Forward
Once Backward
Once Ping Pong

See play_animation for more information and examples of how to use this message.

`current_tile`	number the current tile of the sprite
`id`	hash id of the animation that was completed

EXAMPLES

How to sequence two animations together.

function init(self)
  -- play jump animation at init
  msg.post("#sprite", "play_animation", {id = hash("jump")})
end

function on_message(self, message_id, message, sender)
  -- check for animation done response
  if message_id == hash("animation_done") then
    -- start the walk animation
    msg.post("#sprite", "play_animation", { id = hash("walk") })
  end
end

play_animation

play a sprite animation

Post this message to a sprite component to make it play an animation from its tile set.

`id`	hash the id of the animation to play

EXAMPLES

In the example, it is assumed that the instance of the script has a sprite-component with id "sprite". The sprite itself is assumed to be bound to a tile set with animations "walk" and "jump".

msg.post("#sprite", "play_animation", {id = hash("jump")})

Properties

cursor

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

number sprite cursor

EXAMPLES

How to get the normalized cursor value:

function init(self)
  -- Get the cursor value on component "sprite"
  cursor = go.get("#sprite", "cursor")
end

How to animate the cursor from 0.0 to 1.0 using linear easing for 2.0 seconds:

function init(self)
  -- Get the current value on component "sprite"
  go.set("#sprite", "cursor", 0.0)
  -- Animate the cursor value
  go.animate("#sprite", "cursor", go.PLAYBACK_LOOP_FORWARD, 1.0, go.EASING_LINEAR, 2)
end

image

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

hash sprite image

EXAMPLES

How to set image using a script property (see resource.atlas)

go.property("my_image", resource.atlas("/atlas.atlas"))
function init(self)
  go.set("#sprite", "image", self.my_image)
end

See resource.set_texture for an example on how to set the texture of an atlas.

material

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

hash sprite material

EXAMPLES

How to set material using a script property (see resource.material)

go.property("my_material", resource.material("/material.material"))
function init(self)
  go.set("#sprite", "material", self.my_material)
end

playback_rate

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.

number sprite playback_rate

EXAMPLES

How to set the playback_rate on component "sprite" to play at double the current speed:

function init(self)
  -- Get the current value on component "sprite"
  playback_rate = go.get("#sprite", "playback_rate")
  -- Set the playback_rate to double the previous value.
  go.set("#sprite", "playback_rate", playback_rate * 2)
end

scale

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

vector3 sprite scale

EXAMPLES

How to scale a sprite independently along the X and Y axis:

function init(self)
  -- Double the y-axis scaling on component "sprite"
     local yscale = go.get("#sprite", "scale.y")
     go.set("#sprite", "scale.y", yscale * 2)
end

size

READ ONLY Returns the size of the sprite, not allowing for any additional scaling that may be applied. The type of the property is vector3.

vector3 sprite size

EXAMPLES

How to query a sprite's size, either as a vector or selecting a specific dimension:

function init(self)
  -- get size from component "sprite"
  local size = go.get("#sprite", "size")
  local sx = go.get("#sprite", "size.x")
  -- do something useful
  assert(size.x == sx)
end