Sprites

Overview

You can draw static sprites and animations to the game's canvas using the sprite! macro.

API

sprite!

Sprites from your project's sprites folder can be drawn using the sprite macro.

sprite!(
    name: &str,
    x = i32,
    y = i32,
    w = u32,
    h = u32,
    color = u32,
    opacity = f32,
    rotation = i32,
    scale_x = f32,
    scale_y = f32,
    flip_x = bool,
    flip_y = bool,
)

animation::get

Gets the SpriteAnimation data associated with a sprite animation key.

animation::get(animation_key: &str) -> &mut SpriteAnimation

Usage

Static Sprites

To draw a sprite, simply call the macro and include any parameters you need. The only one that is required is the file name (minus the extension):

sprite!("goblin", x = 120, y = 50, rotate = 180);

And with that, we have ourselves an upside-down goblin:

Let's break it down:

• The first parameter ("goblin") is the filename of your sprite excluding the file extension.
• Adjust the x and y parameters to position the sprite where you want it.
• Adjust the rotate parameter to control the sprite's degrees of rotation.

Basic Looping Animations

The sprite macro will follow any animation rules set in the file, so if you use an animated file type (like .gif or .webp), it will animate automatically.

So if we write some code like this:

// Display a sprite named "doge".
sprite!("doge", x = 112, y = 50);

...it will be rendered like this:

The speed and playback settings of the animation are determined by the settings on your file.

Advanced Animations

Introduction

A SpriteAnimation is the data structure that holds your animations values. Create a new SpriteAnimation by passing an animation key to animation::get:

let anim = animation::get("foo");

If there is no entry for the value you put in, then it will create a new animation. If the value exists already, then it will return that to you. Then, you can change the animation values, including setting the sprite that you want this animation to play:

let anim = animation::get("foo"); 
anim.use_sprite("turbi_idle"); // set the sprite file you want to use
anim.set_speed(1.5); // increase the speed of the animation

Once you have your settings correct, you can call the sprite! macro to draw the animation:

let anim = animation::get("foo");
anim.use_sprite("turbi_idle"); // set the sprite file you want to use
anim.set_speed(1.5); // increase the speed of the animation
sprite!(animation_key = "foo"); 

Transitioning animations

There are several ways you can transition between animations, but one of the simplest is to use the default_sprite field in the sprite! macro. If the animation's sprite isn't set, or if it's animation is finished, then it will use the default_sprite instead. This is great for any time you want to play an animation all the way through one time, and then immediately go back to a default. For example, if your character dashes, you could play the dash animation, but keep an idle animation as the default. Then, when the dash is done, you'll go back to idle.

let anim = animation::get("player_character");
if gamepad(0).a.just_pressed() {
    anim.use_sprite("player_dash");
    a.set_repeat(1); // only play the animation 1 time
}
sprite!(
    animation_key = "player_character",
    default_sprite = "player_idle", // turbo will use this sprite once the dash animation has completed one loop
);

The default_sprite is used if the animation_key doesn't have a sprite assigned to it, or if the assigned animation is finished.

Animation Values

SpriteAnimation has a number of functions you can call to change it's values. The general pattern is that you can access a value, or change it with set_.

There are also a few helpful functions you can call on your SpriteAnimation.

Aseprite Tags

Turbo supports working directly with aseprite files. If you use tags to organize multiple animations in your aseprite animation timeline, you can target those with a special synax:

sprite!("aseprite_file_name#tag-name");