Struct Sprite 

pub struct Sprite {
    pub texture: AssetHandle<TextureAsset>,
    pub texture_path: Option<String>,
    pub color: Color,
    pub source_rect: Option<Rect>,
    pub flip_x: bool,
    pub flip_y: bool,
    pub anchor: Vec2,
    pub custom_size: Option<Vec2>,
}

A 2D sprite component for rendering textured quads.

The Sprite component defines how a texture should be rendered in 2D space. It must be paired with a Transform2D or GlobalTransform2D component to define the sprite’s position, rotation, and scale.

Fields

• texture: Handle to the texture asset to render
• color: Color tint multiplied with texture pixels (default: white)
• source_rect: Optional UV rectangle for sprite sheets (default: full texture)
• flip_x: Flip the sprite horizontally (default: false)
• flip_y: Flip the sprite vertically (default: false)
• anchor: Normalized anchor point for rotation/positioning (default: center)
• custom_size: Optional override for sprite size (default: texture size)

Examples

Basic Sprite

use goud_engine::ecs::components::Sprite;
use goud_engine::assets::{AssetServer, loaders::TextureAsset};

let mut asset_server = AssetServer::new();
let texture = asset_server.load::<TextureAsset>("player.png");

let sprite = Sprite::new(texture);

Sprite with Custom Properties

use goud_engine::ecs::components::Sprite;
use goud_engine::core::math::{Color, Vec2};

let sprite = Sprite::new(texture)
    .with_color(Color::rgba(1.0, 0.5, 0.5, 0.8))
    .with_flip_x(true)
    .with_anchor(0.5, 1.0)
    .with_custom_size(Vec2::new(64.0, 64.0));

Sprite Sheet Frame

use goud_engine::ecs::components::Sprite;
use goud_engine::core::math::Rect;

// Extract a 32x32 tile from the sprite sheet
let sprite = Sprite::new(texture)
    .with_source_rect(Rect::new(64.0, 32.0, 32.0, 32.0));

Fields

texture: AssetHandle<TextureAsset>

Handle to the texture asset to render.

texture_path: Option<String>

Optional path to the texture asset for serialization.

When a scene is serialized the handle cannot be persisted, but this path string can. At load time a higher-level system resolves the path back to an AssetHandle.

color: Color

Color tint multiplied with texture pixels.

Each component is in range [0.0, 1.0]. White (1, 1, 1, 1) renders the texture unmodified. RGB values tint the color, alpha controls transparency.

source_rect: Option<Rect>

Optional source rectangle for sprite sheets and atlases.

If None, the entire texture is rendered. If Some, only the specified rectangle (in pixel coordinates) is rendered.

For normalized UV coordinates, multiply by texture dimensions.

flip_x: bool

Flip the sprite horizontally.

When true, the texture is mirrored along the Y-axis.

flip_y: bool

Flip the sprite vertically.

When true, the texture is mirrored along the X-axis.

anchor: Vec2

Normalized anchor point for rotation and positioning.

Coordinates are in range [0.0, 1.0]:

• (0.0, 0.0) = Top-left corner
• (0.5, 0.5) = Center (default)
• (1.0, 1.0) = Bottom-right corner

The anchor point is the origin for rotation and the point that aligns with the entity’s Transform2D position.

custom_size: Option<Vec2>

Optional custom size override.

If None, the sprite renders at the texture’s pixel dimensions (or source_rect dimensions if specified). If Some, the sprite is scaled to this size.

Implementations

impl Sprite

pub fn new(texture: AssetHandle<TextureAsset>) -> Sprite

Creates a new sprite with default settings.

The sprite will render the entire texture with:

• White color tint (no modification)
• No source rectangle (full texture)
• No flipping
• Center anchor point (0.5, 0.5)
• No custom size (uses texture dimensions)

Example

use goud_engine::ecs::components::Sprite;

let sprite = Sprite::new(texture);

pub fn with_texture_path(self, path: impl Into<String>) -> Sprite

Sets the texture asset path for serialization.

The path is stored alongside the sprite so it survives serialization. A higher-level system is responsible for resolving it back to an AssetHandle after deserialization.

Example

use goud_engine::ecs::components::Sprite;

let sprite = Sprite::new(texture)
    .with_texture_path("player.png");
assert_eq!(sprite.texture_path.as_deref(), Some("player.png"));

pub fn with_color(self, color: Color) -> Sprite

Sets the color tint for this sprite.

The color is multiplied with each texture pixel. Use white (1, 1, 1, 1) for no tinting.

Example

use goud_engine::ecs::components::Sprite;
use goud_engine::core::math::Color;

let sprite = Sprite::new(texture)
    .with_color(Color::rgba(1.0, 0.0, 0.0, 0.5)); // Red, 50% transparent

pub fn with_source_rect(self, rect: Rect) -> Sprite

Sets the source rectangle for sprite sheet rendering.

The rectangle is specified in pixel coordinates relative to the top-left corner of the texture.

Example

use goud_engine::ecs::components::Sprite;
use goud_engine::core::math::Rect;

// Extract a 32x32 tile at position (64, 32)
let sprite = Sprite::new(texture)
    .with_source_rect(Rect::new(64.0, 32.0, 32.0, 32.0));

pub fn without_source_rect(self) -> Sprite

Removes the source rectangle, rendering the full texture.

Example

let mut sprite = Sprite::new(texture)
    .with_source_rect(Rect::new(0.0, 0.0, 32.0, 32.0));

sprite = sprite.without_source_rect();
assert!(sprite.source_rect.is_none());

pub fn with_flip_x(self, flip: bool) -> Sprite

Sets the horizontal flip flag.

When true, the sprite is mirrored along the Y-axis.

Example

use goud_engine::ecs::components::Sprite;

let sprite = Sprite::new(texture).with_flip_x(true);

pub fn with_flip_y(self, flip: bool) -> Sprite

Sets the vertical flip flag.

When true, the sprite is mirrored along the X-axis.

Example

use goud_engine::ecs::components::Sprite;

let sprite = Sprite::new(texture).with_flip_y(true);

pub fn with_flip(self, flip_x: bool, flip_y: bool) -> Sprite

Sets both flip flags at once.

Example

use goud_engine::ecs::components::Sprite;

let sprite = Sprite::new(texture).with_flip(true, true);

pub fn with_anchor(self, x: f32, y: f32) -> Sprite

Sets the anchor point with individual coordinates.

Coordinates are normalized in range [0.0, 1.0]:

• (0.0, 0.0) = Top-left
• (0.5, 0.5) = Center
• (1.0, 1.0) = Bottom-right

Example

use goud_engine::ecs::components::Sprite;

// Bottom-center anchor for ground-aligned sprites
let sprite = Sprite::new(texture).with_anchor(0.5, 1.0);

pub fn with_anchor_vec(self, anchor: Vec2) -> Sprite

Sets the anchor point from a Vec2.

Example

use goud_engine::ecs::components::Sprite;
use goud_engine::core::math::Vec2;

let sprite = Sprite::new(texture)
    .with_anchor_vec(Vec2::new(0.5, 1.0));

pub fn with_custom_size(self, size: Vec2) -> Sprite

Sets a custom size for the sprite.

When set, the sprite is scaled to this size regardless of the texture dimensions.

Example

use goud_engine::ecs::components::Sprite;
use goud_engine::core::math::Vec2;

// Force sprite to 64x64 size
let sprite = Sprite::new(texture)
    .with_custom_size(Vec2::new(64.0, 64.0));

pub fn without_custom_size(self) -> Sprite

Removes the custom size, using texture dimensions.

Example

use goud_engine::ecs::components::Sprite;
use goud_engine::core::math::Vec2;

let mut sprite = Sprite::new(texture)
    .with_custom_size(Vec2::new(64.0, 64.0));

sprite = sprite.without_custom_size();
assert!(sprite.custom_size.is_none());

pub fn size_or_rect(&self) -> Vec2

Gets the effective size of the sprite.

Returns the custom size if set, otherwise the source rect size if set, otherwise falls back to a default size (requires texture dimensions).

For actual rendering, you’ll need to query the texture asset to get its dimensions when custom_size and source_rect are both None.

Example

use goud_engine::ecs::components::Sprite;
use goud_engine::core::math::{Vec2, Rect};

let sprite = Sprite::new(texture)
    .with_source_rect(Rect::new(0.0, 0.0, 32.0, 32.0));

let size = sprite.size_or_rect();
assert_eq!(size, Vec2::new(32.0, 32.0));

pub fn has_source_rect(&self) -> bool

Returns true if the sprite has a source rectangle set.

pub fn has_custom_size(&self) -> bool

Returns true if the sprite has a custom size set.

pub fn is_flipped(&self) -> bool

Returns true if the sprite is flipped on either axis.

Trait Implementations

impl Clone for Sprite

fn clone(&self) -> Sprite

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Sprite

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

Formats the value using the given formatter.

impl Default for Sprite

fn default() -> Sprite

Creates a sprite with an invalid texture handle.

This is primarily useful for deserialization or when the texture will be set later. The sprite will not render correctly until a valid texture handle is assigned.

impl<'de> Deserialize<'de> for Sprite

fn deserialize<__D>( __deserializer: __D, ) -> Result<Sprite, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Sprite

fn eq(&self, other: &Sprite) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Sprite

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Component for Sprite

impl StructuralPartialEq for Sprite