Manual

Manual

Sprites

A sprite draws an image, or a part of one, flat in the world. This page covers the Sprite component and the images it draws, sprite sheets cut in the Sprite Editor, sprites that play their slices as an animation, the order sprites are drawn in, sprites kept out of the 2D lights, and the 2D camera that draws them all.

Make a sprite

Sprites are Bevy's own: an entity with Bevy's Sprite component, drawn by a 2D camera. There are three ways to make one:

  • Entity ▸ 2D Object (also in the Hierarchy's + menu) makes a Sprite that draws nothing yet, or a sprite of one of the engine's five white shapes: Square, Circle, Capsule, Triangle and Hexagon. The shapes are there to block out a level before there is art; their Color tints them.
  • Drag an image from the Project panel onto the Scene panel or the Hierarchy. You get a sprite drawing it, named after the file.
  • Drag a slice of a sprite sheet the same way (see Sprite sheets). The sprite draws that slice and is named after it.

Only a 2D camera draws sprites. File ▸ New Scene... has a 2D template whose Main Camera is a 2D camera, and Entity ▸ Camera ▸ Camera 2D adds one to any scene (see The 2D camera). When a scene's cameras are all 3D, the Game panel says No 2D camera: sprites are not drawn.

In the Scene panel, sprites show in the 2D view (press 2) and in the 3D one, drawn over the 3D scene. A click picks a sprite where its image shows, not in its clear corners, and the orange outline follows what shows.

Images for sprites

Any image in the project can be a sprite's. Pick it in the Project panel and set its import settings in the Inspector:

  • Texture Type: Sprite (2D and UI). A sprite image has no mipmaps and clamps at its edges. See Textures for the other settings.
  • Sprite Mode: Single draws the whole image. Multiple cuts it into slices in the Sprite Editor, and shows the Sprite Editor button with how many slices it has.
  • Pixels Per Unit: how many of the image's pixels make one world unit, 100 unless you change it. At 100, a 64-pixel sprite is 0.64 units across. A unit is a meter to Physics 2D, so pick the number that makes your characters the right size.

For pixel art, set Filter Mode to Point so the pixels stay sharp at any zoom, and give every image the same Pixels Per Unit so their pixels match.

Click Apply for the settings to take effect.

Sprite

The Inspector's Sprite section holds what the sprite draws and where it goes among the others.

FieldWhat it does
ImageThe image it draws. Drop an image or a slice on the slot, or pick one with its button: the list has the engine's shapes under Built In, then the project's images, each followed by its slices. None draws nothing. A slice reads as coins ▸ coins_3. Click the slot to find the file in the Project panel.
ColorA tint multiplied over the image. White draws it as it is.
FlipX mirrors it left to right, Y top to bottom.
Draw ModeHow the image fills the sprite's Size: Simple, Scaled, Sliced or Tiled. See Draw modes.
SizeHow big it is drawn, in world units, shown as W and H. Grayed while it is the image's own size, its pixels over its Pixels Per Unit. Type a number to set it. Right-click either number and choose Use the Image's Size to go back.
PivotThe point it turns about and is placed by: one of nine places (Center, Top Left, Top, Top Right, Left, Right, Bottom Left, Bottom, Bottom Right), or numbers, 0 at the middle and 0.5 at an edge, up being positive. A sprite drawing a slice uses the slice's pivot, shown grayed; change it in the Sprite Editor.
Sorting LayerThe sorting layer it is drawn on. The list ends with Add Sorting Layer..., which opens Project Settings at the layers. A layer that has been removed shows in amber, and the sprite is drawn on Default. See Draw order.
Order in LayerA whole number. On one layer, a higher order is drawn over a lower one.

A scene keeps the image by its path and identity, so a moved image still loads, and a slice by its own identity, so the image can be cut again without losing it.

Draw modes

Draw ModeWhat it does
SimpleStretches the whole image over the Size.
ScaledFits the image into the Size keeping its proportions, filling or fitting it as the list under it says.
SlicedNine-slice drawing: the corners keep their size, and the sides and middle stretch or tile. The border, how far in from each side the corners reach in pixels, is set under it, or comes from the slice's Border when the sprite draws a slice. Good for panels and platforms that change size.
TiledRepeats the image across the Size, along X, Y or both.

Resize a sprite in the Scene view

With the Rect tool (T), dragging a side or corner of a sprite changes its Size, not its scale, so a Sliced or Tiled sprite grows the way it should. Hold Shift to keep its proportions, Alt to resize about the pivot, and Space to scale it instead. With one sprite picked, dragging the Rect tool's pivot circle moves the sprite's Pivot, snapping to the nine places as it passes them. A 2D collider on the sprite follows its new Size. The Scene view covers the tools.

Sprite sheets and the Sprite Editor

A sprite sheet is one image cut into slices: the frames of a character, the tiles of a level, the icons of an interface. Each slice is a rectangle of the image with a name, a pivot and a border, and a sprite draws it by the slice's identity. The slices are saved in the image's .abyss sidecar, and a build packs them beside the image.

Open an image in the Sprite Editor

  1. Pick the image in the Project panel and set its Texture Type to Sprite (2D and UI) and its Sprite Mode to Multiple. Click Apply.
  2. Click Sprite Editor under Sprite Mode. If you changed import settings without applying them, the editor asks whether to Apply them first.

Window ▸ Sprite Editor (Ctrl+7) opens the panel too, and a double-click on a slice in the Project panel opens it on that slice. The panel shows the image on a checkerboard, so clear pixels show as clear, with its slices outlined over it. The wheel zooms about the pointer, the middle or right button pans (or Alt and the left button), and F frames the image again.

Cut it by a grid or automatically

The Slice button at the top opens a menu of how to cut the image, and its own Slice button at the bottom cuts it.

SettingWhat it does
TypeGrid By Cell Size, Grid By Cell Count or Automatic.
Pixel SizeGrid By Cell Size: how wide and tall a cell is, in pixels. 64 by 64 to begin with.
Column & RowGrid By Cell Count: how many columns and rows.
OffsetA grid: how far in from the image's top left corner it starts, in pixels.
PaddingA grid: the gap between cells, in pixels.
Keep Empty RectsA grid: makes a slice of a cell with nothing in it too. Off, empty cells are left out.
PivotThe pivot every new slice gets, from the nine places.

Automatic draws a rectangle round each island of pixels that are not clear, joining islands whose rectangles overlap and leaving out specks a few pixels across, in rows from the top, each row from the left.

Slices are named after the image and their place in the cut, from the top left: coins_0, coins_1 and so on. Cutting the image again replaces the slices, but a new slice that lies over an old one keeps the old one's identity, pivot and border, and its name if you typed one. So the sprites and tiles drawing a slice stay on it when you change the grid.

Edit slices by hand

  • Click a slice to pick it. Its rectangle turns blue, with dots at its corners and sides and a circle at its pivot.
  • Drag inside it to move it, a side or a corner to resize it, and its pivot circle to move the pivot, which snaps to the nine places as it passes them.
  • Drag where there is no slice to draw a new one, named after the image and a number no other slice has.
  • Delete takes the picked slice away. Escape during a drag puts the slice back.

The side of the panel shows the picked slice: Name, Position and Size in the image's pixels from its top left corner, Border (left, top, right and bottom, in pixels, drawn in green on the canvas; a Sliced sprite's corners reach that far in), and Pivot as a list of the nine places and as numbers.

The list at the top left switches the canvas between Slices and Tile Shape, which draws what of a tile each slice fills for physics and shadows; see Tile shapes.

Apply and Revert

Nothing is written until you click Apply at the top right. Until then, while the Sprite Editor has the keyboard, Ctrl+Z takes back each edit, a drag being one step, Ctrl+Y or Ctrl+Shift+Z does it again, and Revert puts back what the sidecar holds. Apply writes the slices into the image's sidecar, and every sprite and Tilemap using them is drawn with them at once.

Draw a slice

An image cut into slices has an arrow on its tile in the Project panel. Click it to show the slices beside the image, each with its picture. Then:

  • Drag a slice onto the Scene panel or the Hierarchy to make a sprite drawing it.
  • Drag a slice onto a sprite's Image slot to have that sprite draw it.

A sprite drawing a slice is placed by the slice's pivot, and drawn Sliced by the slice's border. If a slice is taken away, its sprites draw the whole image, and the log says so.

Animated sprites from slices

Pick several images or slices in the Project panel with Ctrl+click, and drag them together onto the Scene panel or the Hierarchy. The editor makes a sprite that plays them:

  • an animation clip, an .anim file, of all of them in the natural order of their names (walk_2 before walk_10, whatever order you picked them in), twelve frames a second, looping;
  • an animator controller with one state playing that clip;
  • a sprite showing the first frame, with an Animator running the controller.

The clip and the controller go beside the first image and are named after it, a number at the end left off: walk.anim and its controller for walk_0.png to walk_7.png. There is nothing to type. Open the clip in Window ▸ Animation (Ctrl+6) to change its timing or add events, and build up the controller in the Animator panel; see Animation clips and The Animator.

The 2D camera

A 2D camera is Bevy's Camera2d. In the Inspector it is the Camera section marked 2D; Add Component ▸ Camera 2D adds one, and Entity ▸ Camera ▸ Camera 2D makes one.

The editor makes a 2D camera orthographic, showing ten world units from the bottom of the view to the top, an orthographic Size of 5, whatever the window's size. A 64-pixel sprite at 100 pixels per unit, 0.64 units tall, is then about a sixteenth of the view's height. Raise the Size to see more of the level.

Every camera's settings are described in Cameras. For pixel art drawn at its own size, for a camera that follows the player, and for backgrounds that move slower than the level, see 2D cameras.

Draw order

Sprites do not hide each other by depth. What is drawn over what is decided, in this order, by:

  1. the Sorting Layer: a sprite on a layer further down the list is drawn over every sprite on a layer above it;
  2. the Order in Layer: on one layer, a higher order is drawn over a lower one;
  3. the project's Sort Axis, between two sprites of one layer and one order.

Tilemaps, and particle emitters, trails and lines drawn flat, take part in the same order through their own Sorting Layer and Order in Layer. In the Scene panel, a click picks what is drawn on top first.

Sorting layers

The layers are in Edit ▸ Project Settings ▸ Tags and Layers, under Sorting Layers:

  • Default is always first, drawn under the others, and always called Default. Every sprite starts on it.
  • + adds a layer at the end of the list, drawn over the others, called New Layer until you type a name over it.
  • Drag a layer by its handle to move it. Default stays first.
  • Pick a layer and click the bin to remove it. Sprites on it are drawn on Default, and the log says so.

A sprite keeps its layer by an identity that stays with the layer as you rename and move it, so renaming a layer changes nothing in your scenes. The list is saved in settings/sorting.json and packed with the game.

Sorting layers are not the entity layers of Layers on the same page, which decide what a camera draws; see Layers.

Sort Axis

Sort Axis, under the sorting layers, decides between two sprites on one layer at one order:

  • Z (the default): the one further along +Z is drawn over the other.
  • Y: the one lower in the world is drawn over the other. In a game seen from above, a character standing in front of another, lower on the screen, is drawn in front.

A sprite's place along the axis is where its pivot is, so give characters a pivot at their feet (Bottom) for Y sorting.

Sorting Group

A sprite character is often several sprites: a body, a head, a sword. On its own, each sprite sorts against the world separately, so a tree could come between the body and the sword. Add Component ▸ Sorting Group on the character's top entity draws the entity and everything under it as one, sorted among the rest by the group's own layer and order, at the group entity's place along the Sort Axis. Inside the group, its sprites sort among themselves as usual.

FieldWhat it does
Sorting LayerThe layer the whole group is drawn on.
Order in LayerThe group's order on that layer.
Sort At RootLeaves out the groups above it, so this group sorts among everything at the top as if it had no parent.

Groups nest: a group inside a group is sorted within it. A Sorting Group with a lower order is a handy way to keep a whole background, made of many sprites, behind the level.

Unlit 2D

When a 2D light is in the scene, a 2D camera draws everything lit by it, so what no light reaches is dark (see 2D lights). Add Component ▸ Unlit 2D keeps what its entity draws out of the lighting: it is drawn as it is, as bright as its art, by every camera. Use it for a sky or background far behind the level, a glowing sign, or a character's eyes in the dark.

It has no fields, and it works on a sprite, a Tilemap, a 2D mesh and a particle emitter drawn flat. It applies to its own entity only, not to the entities under it, so put it on each one that should stay unlit. An Unlit 2D sprite with a Shadow Caster 2D still casts shadows.

Sprites from code

A sprite's image can be changed from code that runs between frames, such as a flow (see C# in a game). World.SetSpriteImage takes the image and, for a sprite sheet, the name of the slice the Sprite Editor gave it:

// coin: the sprite's entity.ImageId coins = flow.Assets.LoadImage(Addresses.Sprites.Coins);await flow.Loaded(coins);flow.World.SetSpriteImage(coin, coins, "coins_3");   // a slice by its nameflow.World.SetSpriteImage(coin, coins);              // or the whole image

World.SpriteImage(entity) says which image a sprite draws, and World.SpriteSize(entity) the size its image gives it in world units. To play frames, load an .anim clip with context.Assets.LoadClip(Addresses.Sprites.Walk) once it is addressable, and play it with the sprite's Animator.

A sprite's Sorting Layer and Order in Layer are the engine's SortingOrder component, which every sprite carries, as its layer and order fields. Find a layer's identity by its name with World.SortingLayerNamed, and write it as any engine component's field (see How C# sees a Rust component):

// In a plugin's Build: every entity with a Ghost component is drawn on the Foreground layer.World world = schedule.World;uint front = world.SortingLayerNamed("Foreground") ?? SortingLayers.Default;ComponentLayout sorting = world.LayoutOf("SortingOrder");ComponentField layer = sorting["layer"];ComponentType<Ghost> ghost = world.Component<Ghost>();
schedule.Add("Ghosts in front", [sorting.Write(), ghost.Read()], context =>{    foreach (Chunk chunk in context.Chunks)    {        FieldView<uint> layers = chunk.GetFieldView<uint>(0, layer);        for (int row = 0; row < layers.Length; row++)        {            layers[row] = front;        }    }});

In the Scripting API