Sprite API documentation
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.
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
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.
How to query a sprite's slice values, either as a vector or selecting a specific dimension:
function init(self)
local slice = go.get("#sprite", "slice")
local slicex = go.get("#sprite", "slice.x")
assert(slice.x == slicex)
end
function init(self)
-- animate the entire slice vector at once
go.animate("#sprite", "slice", go.PLAYBACK_LOOP_PINGPONG, vmath.vector4(96, 96, 96, 96), go.EASING_INCUBIC, 2)
-- or animate a single component
go.animate("#sprite", "slice.y", go.PLAYBACK_LOOP_PINGPONG, 32, go.EASING_INCUBIC, 8)
end
The non-uniform scale of the sprite. The type of the property is vector3.
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
The image used when rendering the sprite. The type of the property is hash.
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
The material used when rendering the sprite. The type of the property is hash.
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
The normalized animation cursor. The type of the property is number.
How to get the normalized cursor value:
function init(self)
-- Get the cursor value on component "sprite"
cursor = go.get("#sprite", "cursor")
end
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
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.
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
READ ONLY The current animation id. An animation that plays currently for the sprite. The type of the property is hash.
How to get the animation
on component "sprite":
function init(self)
local animation = go.get("#sprite", "animation")
end
READ ONLY The frame count of the currently playing animation.
How to get the frame_count
on component "sprite":
function init(self)
local frame_count = go.get("#sprite", "frame_count")
end
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.
url - the sprite that should flip its animations
flip - true
if the sprite should flip its animations, false
if not
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
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.
url - the sprite that should flip its animations
flip - true
if the sprite should flip its animations, false
if not
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
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.
url - the sprite that should play the animation
id - hashed id of the animation to play
[complete_function] - function to call when the animation has completed.
self
message_id
"animation_done"
.message
current_tile
- the current tile of the sprite.id
- id of the animation that was completed.sender
[play_properties] - optional table with properties:
offset
playback_rate
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("animation_done") then
if message.id == hash("jump") then
-- jump 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
Post this message to a sprite component to make it play an animation from its tile set.
id - the id of the animation to play
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")})
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:
current_tile - the current tile of the sprite
id - id of the animation that was completed
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