Struct Spritesheet

pub struct Spritesheet { /* private fields */ }

An helper to obtain frame indices from a spritesheet.

When creating a clip, you might specify its frames by using raw indices:

let clip = Clip::from_frames([6, 7, 8, 9, 10, 11]);

However, a clearer and less error-prone approach is to use a Spritesheet to retrieve indices with layout queries:

// We're working with a spritesheet with 8 columns and 4 rows

let spritesheet = Spritesheet::new(8, 4);

// Create a clip from all the frames in row 2

let clip1 = Clip::from_frames(spritesheet.row(2));

// Create another clip with the vertical strip starting at (0, 1)
// (will wrap to the next columns)

let clip2 = Clip::from_frames(spritesheet.vertical_strip(0, 1, 12));

Implementations

impl Spritesheet

pub fn new(columns: usize, rows: usize) -> Self

Creates a new spritesheet helper with the given layout.

Arguments

• columns - the number of columns in the spritesheet
• rows - the number of rows in the spritesheet

pub fn all(&self) -> Vec<usize>

Returns the frame indices for all of the spritesheet.

This is convenient if the whole spritesheet represents a single animation.

Example

// ┌───┐
// │A B│
// │C D│
// └───┘

let spritesheet = Spritesheet::new(2, 2);

let clip = Clip::from_frames(spritesheet.all());

// This clip will play frames A → B → C → D

assert_eq!(clip.frames(), vec![0, 1, 2, 3]);

pub fn positions( &self, positions: impl IntoIterator<Item = (usize, usize)>, ) -> Vec<usize>

Returns the frame indices corresponding to the given positions in the spritesheet.

This is convenient if the frames that you’re interested in are scattered all over the spritesheet.

Arguments

• positions - the list of (x, y) positions for each frame

Example

// ┌───┐
// │A B│
// │C D│
// └───┘

let spritesheet = Spritesheet::new(2, 2);

let clip = Clip::from_frames(spritesheet.positions([(1, 0), (0, 1)]));

// This clip will play frames B → C

assert_eq!(clip.frames(), vec![1, 2]);

pub fn row(&self, row: usize) -> Vec<usize>

Returns the frame indices for a whole row of the spritesheet.

This is convenient if some spritesheet row contains a single animation.

Arguments

• row - the index of the spritesheet row to add frames for

Example

// ┌─────┐
// │A B C│
// │D E F│
// └─────┘

let spritesheet = Spritesheet::new(3, 2);

let clip = Clip::from_frames(spritesheet.row(1));

// This clip will play frames D → E → F

assert_eq!(clip.frames(), vec![3, 4, 5]);

pub fn row_partial<R: RangeBounds<usize>>( &self, row: usize, column_range: R, ) -> Vec<usize>

Returns the frame indices for a section of a row of the spritesheet.

This is convenient if some spritesheet row contains an animation next to other unrelated frames.

Arguments

• row - the index of the spritesheet row to add frames for
• column_range - the range of columns to add frames for

Example

// ┌─────────┐
// │A B C D E│
// │F G H I J│
// └─────────┘

let spritesheet = Spritesheet::new(5, 2);

// This clip will play frames G → H → I

let clip1 = Clip::from_frames(spritesheet.row_partial(1, 1..=3));

assert_eq!(clip1.frames(), vec![6, 7, 8]);

// This clip will play frames C → D → E

let clip2 = Clip::from_frames(spritesheet.row_partial(0, 2..));

assert_eq!(clip2.frames(), vec![2, 3, 4]);

// This clip will play frames F → G → H → I

let clip3 = Clip::from_frames(spritesheet.row_partial(1, ..4));

assert_eq!(clip3.frames(), vec![5, 6, 7, 8]);

pub fn column(&self, column: usize) -> Vec<usize>

Returns the frame indices for a whole column of the spritesheet.

This is convenient if some spritesheet column contains a single animation.

Arguments

• column - the index of the spritesheet column to add frames for

Example

// ┌─────┐
// │A B C│
// │D E F│
// └─────┘

let spritesheet = Spritesheet::new(3, 2);

let clip = Clip::from_frames(spritesheet.column(1));

// This clip will play frames B → E

assert_eq!(clip.frames(), vec![1, 4]);

pub fn column_partial<R: RangeBounds<usize>>( &self, column: usize, row_range: R, ) -> Vec<usize>

Returns the frame indices for a section of a column of the spritesheet.

This is convenient if some spritesheet column contains an animation among other unrelated frames.

Arguments

• column - the index of the spritesheet column to add frames for
• row_range - the range of rows to add frames for

Example

// ┌─────┐
// │A B C│
// │D E F│
// │G H I│
// │J K L│
// └─────┘

let spritesheet = Spritesheet::new(3, 4);

let clip = Clip::from_frames(spritesheet.column_partial(1, 1..));

// This clip will play frames E → H → K

assert_eq!(clip.frames(), vec![4, 7, 10]);

pub fn horizontal_strip(&self, x: usize, y: usize, count: usize) -> Vec<usize>

Returns the frame indices for an horizontal strip in the spritesheet, wrapping from row to row.

This is convenient if some animations span several rows of a spritesheet.

Arguments

• x - the x position of the beginning of the strip
• y - the y position of the beginning of the strip
• count - the number of frames to add

Example

// ┌─────┐
// │A B C│
// │D E F│
// └─────┘

let spritesheet = Spritesheet::new(3, 2);

let clip = Clip::from_frames(spritesheet.horizontal_strip(2, 0, 3));

// This clip will play frames C → D → E

assert_eq!(clip.frames(), vec![2, 3, 4]);

pub fn vertical_strip(&self, x: usize, y: usize, count: usize) -> Vec<usize>

Returns the frame indices for a vertical strip in the spritesheet, wrapping from column to column.

This is convenient if some animations span several columns of a spritesheet.

Arguments

• x - the x position of the beginning of the strip
• y - the y position of the beginning of the strip
• count - the number of frames to add

Example

// ┌─────┐
// │A B C│
// │D E F│
// └─────┘

let spritesheet = Spritesheet::new(3, 2);

let clip = Clip::from_frames(spritesheet.vertical_strip(1, 0, 3));

// This clip will play frames B → E → C

assert_eq!(clip.frames(), vec![1, 4, 2]);

pub fn atlas_layout( &self, frame_width: u32, frame_height: u32, ) -> TextureAtlasLayout

Creates a TextureAtlasLayout from the spritesheet.

Arguments

• frame_width - the width of a single frame
• frame_height - the height of a single frame

Example

fn setup(
    mut commands: Commands,
    mut library: ResMut<AnimationLibrary>,
    mut atlas_layouts: ResMut<Assets<TextureAtlasLayout>>,
    assets: Res<AssetServer>,
) {
    let spritesheet = Spritesheet::new(8, 8);

    // ... omitted: create an animation ...

    let image = assets.load("character.png");

    let atlas = TextureAtlas {
        layout: atlas_layouts.add(spritesheet.atlas_layout(100, 200)),
        ..default()
    };

    commands.spawn((
        Sprite::from_atlas_image(image, atlas),
        SpritesheetAnimation::from_id(animation_id),
    ));
}

Trait Implementations

impl Clone for Spritesheet

fn clone(&self) -> Spritesheet

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Spritesheet

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Copy for Spritesheet