sprite
Sprite API documentation
Functions
sprite.play_flipbook(2 overloads): void(url: string | Hash | Url, id: string | Hash, complete_function?: (self: unknown, message_id: Hash, message: { current_tile: number; id: Hash }, sender: Url) => void)(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:sprite.PlayProperties)
sprite.reset_constant(url: string | Hash | Url, constant: string | Hash): voidDsprite.set_hflip(url: string | Hash | Url, flip: boolean): voidsprite.set_vflip(url: string | Hash | Url, flip: boolean): void
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.
(url: string | Hash | Url, id: string | Hash, complete_function?: (self: unknown, message_id: Hash, message: { current_tile: number; id: Hash }, sender: Url) => void)(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: sprite.PlayProperties)Parameters
url:string | Hash | Url— the sprite that should play the animationid:string | Hash— hashed id of the animation to playcomplete_function:((self: unknown, message_id: Hash, message: { current_tile: number; id: Hash }, sender: Url) => void) | undefined— function to call when the animation has completed.selfscript_instance The current script instance.message_idhash The name of the completion message,"animation_done".messagemessage.sprite.animation_done Information about the completion.senderurl The invoker of the callback: the sprite component.play_properties:sprite.PlayProperties— 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
endexport 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)
endsprite.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")
endParameters
url:string | Hash | Url— the sprite that should have a constant resetconstant: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)
endParameters
url:string | Hash | Url— the sprite that should flip its animationsflip:boolean—trueif the sprite should flip its animations,falseif 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)
endParameters
url:string | Hash | Url— the sprite that should flip its animationsflip:boolean—trueif the sprite should flip its animations,falseif 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.