Sprites
Draw images in a 2D scene with Sprite: loading the image, tinting, flipping, custom sizes, anchors, nine-slicing, tiling and picking.
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#
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#
| Constructor | What 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#
| Field | What it does |
|---|---|
image | The Handle<Image> to draw. |
texture_atlas | Option<TextureAtlas>: draw one region of the image. |
color | A tint multiplied with the image. Values above 1.0 make it glow with bloom. |
flip_x, flip_y | Mirror the image along an axis. |
custom_size | Option<Vec2>: draw at this size instead of the image's size. |
rect | Option<Rect>: draw only this part of the image. |
image_mode | How the image fills its size: SpriteImageMode (below). |
alpha_mode | SpriteAlphaMode::Blend (the default), Opaque or Mask(threshold). |
Change any field from a system with Query<&mut Sprite>:
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.
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:
| Mode | What it does |
|---|---|
SpriteImageMode::Auto | The 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. |
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:
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.
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#
| Example | What it shows |
|---|---|
sprite | One sprite from an image. |
move_sprite | Moving a sprite from a system. |
sprite_flipping | flip_x and flip_y. |
sprite_scale | The Scale image modes. |
sprite_slice | Nine-slicing. |
sprite_tile | Tiling. |
transparency_2d | Alpha blending. |
Run one from the engine core's workspace: cargo run --example sprite_slice.