Struct bevy_spritesheet_animation::spritesheet::Spritesheet

pub struct Spritesheet { /* private fields */ }

An helper to obtain frame indices from a spritesheet with a given layout.

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

let clip_id = library.new_clip(|clip| {
    clip.push_frame_indices([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);

let clip1_id = library.new_clip(|clip| {
    // Use all the frames in row 2
    clip.push_frame_indices(spritesheet.row(2));
});

let clip2_id = library.new_clip(|clip| {
    // Pick 12 frames vertically starting at (0, 1), will wrap to the next columns
    clip.push_frame_indices(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_id = library.new_clip(|clip| {
    clip.push_frame_indices(spritesheet.all());

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

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

pub fn positions<I: IntoIterator<Item = (usize, usize)>>( &self, positions: I ) -> 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_id = library.new_clip(|clip| {
    clip.push_frame_indices(spritesheet.positions([(1, 0), (0, 1)]));

    // This clip will play frames B → C

    assert_eq!(clip.frame_indices(), 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_id = library.new_clip(|clip| {
    clip.push_frame_indices(spritesheet.row(1));

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

    assert_eq!(clip.frame_indices(), 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);

let clip1_id = library.new_clip(|clip| {
    clip.push_frame_indices(spritesheet.row_partial(1, 1..=3));

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

    assert_eq!(clip.frame_indices(), vec![6, 7, 8]);
});

let clip2_id = library.new_clip(|clip| {
    clip.push_frame_indices(spritesheet.row_partial(0, 2..));

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

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

let clip3_id = library.new_clip(|clip| {
    clip.push_frame_indices(spritesheet.row_partial(1, ..4));

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

    assert_eq!(clip.frame_indices(), 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_id = library.new_clip(|clip| {
    clip.push_frame_indices(spritesheet.column(1));

    // This clip will play frames C → F

    assert_eq!(clip.frame_indices(), 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_id = library.new_clip(|clip| {
    clip.push_frame_indices(spritesheet.column_partial(1, 1..));

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

    assert_eq!(clip.frame_indices(), 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_id = library.new_clip(|clip| {
    clip.push_frame_indices(spritesheet.horizontal_strip(2, 0, 3));

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

    assert_eq!(clip.frame_indices(), 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_id = library.new_clip(|clip| {
    clip.push_frame_indices(spritesheet.vertical_strip(1, 0, 3));

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

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

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