NEOLearn

Sprites

Draw images in a 2D scene with Sprite: loading the image, tinting, flipping, custom sizes, anchors, nine-slicing, tiling and picking.

Updated October 20, 2026

On this page

A Sprite draws an image (or a solid colour) at its entity's Transform. It is the basic building block of a 2D game. Spawning a Sprite also adds the components it needs to be drawn: Transform, Visibility and Anchor.

Spawn a sprite#

src/main.rs
use neo::prelude::*;

fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn(Camera2d);

    commands.spawn((
        Sprite::from_image(asset_server.load("branding/icon.png")),
        Transform::from_xyz(100.0, 0.0, 0.0),
    ));
}

The image loads in the background. Until it's ready, nothing is drawn. Image files go through the asset server; NEO's builds read PNG, HDR and KTX2 images out of the box. Other formats, such as JPEG, need their cargo feature (jpeg, webp, ...).

Constructors#

ConstructorWhat it makes
Sprite::from_image(handle)The image at its own size.
Sprite::from_color(color, size)A solid rectangle of size world units.
Sprite::sized(size)A white rectangle of size; set image or color afterwards.
Sprite::from_atlas_image(handle, atlas)One frame of a sprite sheet; see Texture atlases.

Fields#

FieldWhat it does
imageThe Handle<Image> to draw.
texture_atlasOption<TextureAtlas>: draw one region of the image.
colorA tint multiplied with the image. Values above 1.0 make it glow with bloom.
flip_x, flip_yMirror the image along an axis.
custom_sizeOption<Vec2>: draw at this size instead of the image's size.
rectOption<Rect>: draw only this part of the image.
image_modeHow the image fills its size: SpriteImageMode (below).
alpha_modeSpriteAlphaMode::Blend (the default), Opaque or Mask(threshold).

Change any field from a system with Query<&mut Sprite>:

Rust
fn face_left(mut sprites: Query<&mut Sprite, With<Player>>) {
    for mut sprite in &mut sprites {
        sprite.flip_x = true;
    }
}

Anchors#

Anchor is a separate component that says which point of the sprite sits at its transform's position. The default is the centre. The constants are Anchor::CENTER, TOP_LEFT, TOP_CENTER, TOP_RIGHT, CENTER_LEFT, CENTER_RIGHT, BOTTOM_LEFT, BOTTOM_CENTER and BOTTOM_RIGHT, or any Anchor(Vec2) from -0.5 to 0.5 on each axis.

Rust
commands.spawn((
    Sprite::from_image(asset_server.load("characters/hero.png")),
    // the feet stand on the transform's position
    Anchor::BOTTOM_CENTER,
));

Image modes#

image_mode controls how the image fills custom_size:

ModeWhat it does
SpriteImageMode::AutoThe default. Stretch the image to custom_size, if set.
SpriteImageMode::Scale(mode)Keep the aspect ratio: FillCenter, FillStart, FillEnd, FitCenter, FitStart or FitEnd.
SpriteImageMode::Sliced(TextureSlicer)Nine-slice: corners keep their size, edges and centre stretch or tile. Good for panels and speech bubbles.
SpriteImageMode::Tiled { tile_x, tile_y, stretch_value }Repeat the image instead of stretching it.
A nine-sliced panel
commands.spawn(Sprite {
    image: asset_server.load("textures/slice_square.png"),
    image_mode: SpriteImageMode::Sliced(TextureSlicer {
        border: BorderRect::all(20.0),
        center_scale_mode: SliceScaleMode::Stretch,
        sides_scale_mode: SliceScaleMode::Tile { stretch_value: 0.5 },
        max_corner_scale: 1.0,
    }),
    custom_size: Some(Vec2::new(300.0, 120.0)),
    ..default()
});

Pixel art#

Images are filtered linearly by default, which blurs pixel art when it's scaled. Switch the default sampler to nearest-neighbour when you add the plugins:

Rust
App::new().add_plugins(DefaultPlugins.set(ImagePlugin::default_nearest()));

To keep a low-resolution look crisp while things move and rotate, render to a small texture first; see Pixel-perfect rendering.

Draw order and transparency#

Sprites are sorted by their translation.z: higher values draw in front. Sprites with the same Z have no guaranteed order, so give overlapping sprites different Z values. Transparent pixels blend with whatever is behind them.

Picking sprites#

Sprite picking is on in NEO's builds. Only sprites with a Pickable component are considered. By default a pixel counts as part of the sprite when its alpha is at least 0.1; change SpritePickingSettings::picking_mode to SpritePickingMode::BoundingBox to use the whole rectangle.

Rust
commands
    .spawn((Sprite::from_image(asset_server.load("ui/coin.png")), Pickable::default()))
    .observe(|click: On<PointerClick>| info!("picked {}", click.entity));

More in Picking.

Examples#

ExampleWhat it shows
spriteOne sprite from an image.
move_spriteMoving a sprite from a system.
sprite_flippingflip_x and flip_y.
sprite_scaleThe Scale image modes.
sprite_sliceNine-slicing.
sprite_tileTiling.
transparency_2dAlpha blending.

Run one from the engine core's workspace: cargo run --example sprite_slice.

Next steps#