Manual

Manual

2D cameras

A 2D game's camera does more than look at the level. This page covers the components that make a 2D camera draw pixel art at its own size, follow the player through a level room by room and shake, and draw backgrounds that move slower than the level as the camera goes by.

Every one of them goes on, or works with, a 2D camera: Bevy's Camera2d, which Entity ▸ Camera ▸ Camera 2D makes and the 2D scene template starts with. Sprites explains the 2D camera itself, and Cameras every camera's settings.

Pixel Perfect Camera

Pixel art looks right only when every pixel of the art is the same size on the screen and nothing sits half a pixel off. Add Component ▸ Pixel Perfect Camera on the 2D camera does that: the camera draws the level into a small picture, one pixel of the picture to each pixel of the art, and shows that picture enlarged to fill the window.

FieldWhat it does
Pixels Per UnitHow many of the art's pixels make a unit. Set it to the Pixels Per Unit your images are imported with; 100 to begin with.
Reference ResolutionHow many of the art's pixels the camera shows, across and up. 640 by 360 to begin with, which goes a whole number of times into 720p, 1080p, 1440p and 4K.
FitHow the picture fits a window it does not go into a whole number of times. Bars, the default, enlarges it by the largest whole number that fits and leaves a dark border round it. More Of The Level enlarges it as much, and shows more of the level in the room left. Stretch makes it as large as fits at any size, its shape kept; its pixels then come out uneven.
GlideOn, the default, the camera moves smoothly while everything it shows stays on the art's grid. Off, it moves a whole art pixel at a time.

At 640 by 360 and 32 pixels per unit, the camera shows 20 units across and 11.25 up, wherever it is. The camera's own Size no longer decides what it shows; the Reference Resolution and the Pixels Per Unit do. A window smaller than the Reference Resolution shrinks the picture to fit.

Everything the camera draws is on the art's grid: a sprite turned by a few degrees is turned in art pixels, and 2D lights and their shadows step from art pixel to art pixel too. The camera draws with one sample, whatever its MSAA says, since smoothing would soften the edges of what is turned. The game's interface is drawn over the picture at the screen's own pixels, so text stays sharp.

In the Scene panel, a picked Pixel Perfect Camera's frame shows what it shows. The Game panel shows what a player sees, at the size you pick in its row.

The engine works out how many screen pixels each art pixel is drawn as at every frame. The Inspector shows it as Scale in its Debug view.

Points on the screen

World.ScreenToWorld(camera, point) gives the point of the world's XY plane under a point of the screen, in logical pixels from the top left of where the camera draws, as world.Input.Pointer measures the pointer. World.WorldToScreen(camera, point) goes the other way. Both go through a Pixel Perfect Camera's enlargement, and work for any camera:

// In a flow: what is under the pointer. camera: the camera's entity.Vector2? under = flow.World.Input.Pointer is Vector2 pointer ? flow.World.ScreenToWorld(camera, pointer) : null;

Camera Follow 2D

Add Component ▸ Camera Follow 2D on a camera makes it follow an entity through the level while the game plays. It needs no code of the game's.

FieldWhat it does
TargetThe entity the camera follows. Drag it here from the Hierarchy.
Dead ZoneA box about the middle of the view, in units across and up, that the target moves in without moving the camera. Two across and three up to begin with; 0 keeps the camera on the target.
SmoothingHow long the camera takes to catch up, in seconds: it gets most of the way there in that time. A fifth of a second to begin with; 0 is at once.
Look AheadHow far the camera leads the way the target last went across, in units, so the player sees more of what is ahead. The lead turns round smoothly when the target turns, and stays when it stops.
OffsetWhere the camera aims from the target, in units: up to show more above it.
VerticalHow the camera follows up and down. Settle On Landing, the default, moves it to a new height only once the target stands still up and down for a moment, landed or walking along, or when the target leaves the dead zone; a jump leaves the camera still, and a fall takes it down. Follow follows up and down as it does across.

While the game is edited, the camera stays where you placed it, so the Scene panel shows it there. As the game starts, it is put where it aims at once, and while the game is paused it holds still. The camera is moved as code would move it, by its Transform, after everything else has moved that frame, so a Parallax 2D background and a Pixel Perfect Camera's picture follow it in the same frame.

Camera Bounds 2D

A Camera Bounds 2D is a box a following camera keeps inside: a room, or a boss's arena. Entity ▸ Camera ▸ Camera Bounds 2D makes one, or add the component to any entity.

FieldWhat it does
SizeHow big the box is, in units across and up, about its entity, times the entity's scale. 20 across and 12 up to begin with.

While the target is inside a box, the camera shows nothing outside it. Where boxes overlap, the smallest one the target is in wins, so an arena inside a room holds the camera, and a box the size of the view holds it still. When the target is in no box, the camera keeps to the last one it was in. A box narrower or lower than the view holds the camera at its middle that way. Where the camera aims is kept inside too, so moving from one room's box to the next, the camera glides there as it follows.

The camera keeps to the box by what it shows: a Pixel Perfect Camera's area, or an orthographic camera's. A perspective camera follows its target and keeps to no box.

In the Scene panel, a Camera Bounds 2D is marked by a bounding box. Picked, its box is drawn in a camera's gray with a dot at the middle of each side; drag one to change how wide or high the box is.

Shake a camera

world.Cameras.Shake shakes any camera about where it is, or about where it follows, for a hit or a boss's slam:

// camera: the camera's entity. Shakes by up to 0.3 units, fading out over half a second.flow.World.Cameras.Shake(camera, strength: 0.3f, seconds: 0.5f);

The shake moves the camera as far as its strength, in units, at most, less and less as it fades out over its seconds, 0.4 unless you say. A stronger shake than the one going on takes over from it, and a weaker one does nothing. A Pixel Perfect Camera shakes by whole art pixels. A shake moves the camera only while the game plays. Asking it of what is no camera, or for no distance or no time, throws an AbyssException.

A game's Rust system that takes the world calls abyss_ffi::shake(world, camera, strength, seconds).

Parallax 2D

Add Component ▸ Parallax 2D on an entity has it, and everything under it, drawn moved as the game's camera moves: slower than the level for what is far away, such as hills and sky, faster for what passes in front.

FieldWhat it does
SpeedHow it moves with the camera, across and up. 0 stays with the camera, like a sky. 1 moves with the level. Between, it looks farther away; above 1, in front. Half each way to begin with.
RepeatEvery how many units it is drawn again, across and up, so it never ends: its picture's width over its Pixels Per Unit. 0 for not.
DriftHow many units a second it moves on its own while the game plays, across and up: clouds drifting. With Repeat, it comes back round.

Make one entity per layer of the background, each with its own Speed, and put the sprites or Tilemaps of that layer under it. A Parallax 2D layer under another moves with that one alone. Order the layers with their Sorting Layer and Order in Layer, or put them all under a Sorting Group with a low order to keep the background behind the level. A background far behind the level is often Unlit 2D, so the level's darkness does not reach it.

Where a layer is drawn

A layer is drawn shifted by how far the game's camera has moved since the layer was first drawn in play, times one less its Speed, plus how far it has drifted. Only where it is drawn moves: its Transform keeps what you set, so the scene keeps every layer where you placed it, and Stop has nothing to put back. While the game is edited nothing is shifted, so the Scene panel shows each layer as the game sees it when it starts. A paused game holds the drift.

The game's camera is its active 2D camera of the lowest order, or the active camera of the lowest order where it has no 2D one.

Repeated layers

A layer with a Repeat is drawn again that many units apart, as often as it takes to fill the game camera's view and one more each side, up to 32 times each way. Line the pictures up so that one ends where the next begins: for a 426-pixel picture at 32 pixels per unit, a Repeat of 13.3125 across.

The copies are drawn only. They are made of the layer's sprites, Tilemaps and 2D meshes, follow every change to them, and sort as the layer does, but they collide with nothing, cast no shadow, run none of the game's systems and are never saved. A click on a copy in the Scene panel picks the entity it is a copy of.

From code

These components are set from code as any engine component is: from C# through World.LayoutOf and its field views (see How C# sees a Rust component), and from a game's Rust as abyss_ffi::PixelPerfectCamera, abyss_ffi::CameraFollow2D, abyss_ffi::CameraBounds2D and abyss_ffi::Parallax2D, plain components a system sets as any other. In Rust, a Camera Follow 2D's target is a u64 holding the entity's bits, Entity::to_bits(), 0 for none.

In the Scripting API