Manual

Manual

Cameras

A camera is an entity that draws the scene from where it is. This page covers making one, the Inspector's Camera section and its projection, several cameras at once, the sky and fog a camera draws, bloom, depth of field and the other effects drawn after the scene, and what your code changes on a camera as the game plays, a shake included.

Make a camera

Entity ▸ Camera makes one of these, picked in the Hierarchy:

ItemWhat it makes
CameraA 3D camera, in perspective, looking along its −Z
Camera 2DA 2D camera, orthographic, seeing ten units from its bottom to its top whatever the window's size
Camera Bounds 2DNot a camera: a box a following 2D camera keeps inside. See 2D cameras.

A scene made from the Basic template of File ▸ New Scene..., or with Scene in the Project panel's Create menu, has a Main Camera already: a unit up and ten back along +Z, looking at the origin, so what you make at the origin is in view. The 2D template's Main Camera is a 2D camera at the origin. Either carries an Audio Listener, so sound is heard from it (see Audio sources).

A camera is an ordinary entity: move and turn it with its Transform like anything else, and keep it in a prefab if you like. The Game panel shows the game through the cameras of its scene, and says No cameras rendering when none draws. The Scene panel looks through the editor's own camera instead, and shows each of yours as a camera icon. Click the icon to pick it. A picked camera shows what it sees, out to its far plane, with a dot at the middle of each side: drag one to change its field of view, or its size if it is orthographic. Each drag is one Ctrl+Z.

Camera

The Inspector shows a camera as one Camera section. A 2D camera's header says 2D after it. From the top:

FieldWhat it does
ProjectionPerspective, where what is farther is smaller, or Orthographic, where everything keeps its size whatever its distance.
Field of ViewA perspective camera's: how much it sees from top to bottom, in degrees, from almost nothing up to 179. A new camera starts at 45.
SizeAn orthographic camera's: half the height it sees, in world units. A camera made orthographic starts at 5, ten units from top to bottom.
Clipping PlanesNear and Far: how far from the camera drawing starts, and where it stops, in world units. They stay as they are when you switch the projection.
ExposureHow the camera's picture is exposed, as a photographer's EV100: higher is darker. It starts at 9.7.
Culling MaskThe layers it draws, ticked from a list with Nothing and Everything at its top. Every layer, until you untick some. See Layers.
OrderWhich camera draws on top when several draw into the same window: a higher order draws later.
Is ActiveWhether it draws at all.
Clear ColorWhat it fills the picture with before drawing: Default, the game's clear color; Custom, a color of its own; or None, nothing, so it draws over what a camera before it drew.
MSAAMultisample anti-aliasing, which smooths the edges of what it draws: Off, Sample 2, Sample 4 (the default) or Sample 8.
TonemappingHow the light it sees is mapped to the colors a screen shows. Tony Mc Mapface to start, or None, Reinhard, Reinhard Luminance, ACES Fitted, Ag X, Somewhat Boring Display Transform, Blender Filmic or Khronos Pbr Neutral.
Deband DitherEnabled adds a faint noise that hides the bands a smooth gradient would show.
Color GradingA 3D camera's own heading: the picture's exposure, temperature, tint, hue and saturation over all of it, and its saturation, contrast, gamma, gain and lift in its shadows, midtones and highlights.

The rest of the section is the rest of Bevy's camera, field by field. Values Bevy works out for itself, such as the aspect ratio and the camera's matrices, are grayed: they follow the window or the panel the camera draws into, and a scene does not save them (see What a scene saves).

To make a camera from Add Component, pick Camera or Camera 2D. An entity can be one camera only, so neither is offered on an entity that is a camera already. For what a 2D camera adds, such as following a character and pixel art drawn at its own size, see 2D cameras.

Several cameras

Each camera of the scene draws, in the order of its Order, the lowest first. To draw one camera over another, as for a minimap or a view model, give it a higher Order and set its Clear Color to None, so it draws over the picture under it rather than clearing it. Its Culling Mask picks the layers it draws, and Is Active switches it off without removing it. A light lights every layer, whichever cameras draw it (see Lights).

The projection from code

World.SetProjection sets a camera's projection as the game plays, and ProjectionOf reads it. A field of view of zero makes it orthographic, showing Across world units along the view's shorter side.

world.SetProjection(camera, SceneProjection.Perspective(70f, near: 0.05f, far: 1000f));float degrees = world.ProjectionOf(camera).FieldOfViewDegrees;
world.SetProjection(camera, new SceneProjection(FieldOfView: 0f, Near: -100f, Far: 100f, Across: 20f));

A field of view outside 0 to 180 degrees, a perspective near plane at or behind the camera, and a far plane no farther than the near one are refused with an AbyssException, and the camera is left as it was. Where camera comes from is shown in Cameras from code.

Sky

Add Component ▸ Sky on a camera draws a sky behind everything it sees, where its clear color would show: one color straight up, one at the horizon and one straight down, blended by how high each pixel looks, and a glow toward the sun. It starts as a clear day's, with no glow.

FieldWhat it does
TopThe color straight up.
HorizonThe color at the horizon. Give the camera's fog this color, and the far world fades into the sky.
BottomThe color straight down, under the horizon.
Horizon ReachHow far above and below the horizon its color reaches, from 1 to 90 degrees, blending into the top's and the bottom's.
Sun ColorThe glow looking toward a directional light, its alpha how strong it is. Give the fog the same glow and the two glow alike.
Sun ExponentHow tight the glow is: higher is smaller.

The glow is toward each of the first four directional lights the camera sees, times the light's color and strength. The sky's colors are drawn as given, and mapped by the camera's Tonemapping as its materials are, so the sky and a fog of the horizon's color meet exactly whatever the camera's Tonemapping. An orthographic camera's sky is what a perspective camera of 90 degrees would see.

From code, World.SetSky gives a camera a sky and SkyOf reads it back; null takes it away. The colors are sRGB:

world.SetSky(camera, CameraSky.Gradient(    top: new Vector3(0.25f, 0.47f, 0.86f),    horizon: new Vector3(0.68f, 0.81f, 0.95f),    bottom: new Vector3(0.32f, 0.34f, 0.38f)));

CameraSky.Gradient makes one with no glow; the full CameraSky adds SunColor and SunExponent. A reach outside 1 to 90 degrees and an exponent below 1 are refused.

Distance Fog

Add Component ▸ Distance Fog fades what the camera draws toward one color with distance: to hide where a world stops being drawn, for haze, or under water.

FieldWhat it does
ColorWhat it fades to. Its alpha is how much fog there is at its thickest.
Directional Light ColorA glow looking toward a directional light, such as the sun through haze; clear for none.
Directional Light ExponentHow tight that glow is: higher is smaller.
FalloffHow it thickens: Linear, from Start to whole at End, in meters from the camera; Exponential, by a Density, for haze; Exponential Squared, clear near and then thick, for mist and water; or Atmospheric, by Bevy's extinction and inscattering colors.

From code, World.SetFog and FogOf; null clears the fog. Its colors are sRGB, as SetClearColor's are, so a sky and a fog given the same numbers match:

var haze = new Vector4(0.68f, 0.81f, 0.95f, 1f);var water = new Vector4(0.1f, 0.3f, 0.5f, 1f);
world.SetFog(camera, CameraFog.Linear(haze, start: 75f, end: 124f));world.SetFog(camera, CameraFog.Exponential(water, density: 0.15f, squared: true));   // under waterworld.SetFog(camera, null);                                                          // no fog

The full CameraFog also takes SunColor and SunExponent, the glow. A linear fog whose end is not past its start or that starts behind the camera, and a density of zero or less, are refused.

Materials are fogged; the clear color behind them is not. A camera that is not in HDR tone-maps the fog but not its clear color, so a fog of the clear color's comes out darker than the background behind it. Give the camera a Sky of that color instead, which is mapped as the fog is, or set its Tonemapping to None.

The window's clear color, which a camera whose Clear Color is Default fills its picture with, is set with world.SetClearColor(r, g, b), in sRGB from 0 to 1.

Effects after the scene

A camera can carry Bevy's post-processing effects, each a component on the camera that Add Component offers by name. They draw on the camera that carries them, so the Game panel and your built game show them.

HDR

HDR has no fields: it makes the camera draw in high dynamic range, where a pixel can be brighter than white. Bloom and Auto Exposure need it and bring it as you add them. Removing them leaves it, so remove HDR too if you want the camera back as it was. A camera in HDR maps its clear color with the rest of its picture.

Bloom

What is bright spreads a glow round it, as light does in an eye or a lens. With HDR, what is brighter than white glows, and with a threshold of 1 only that does: a sun drawn four times white, a torch's flame.

FieldWhat it does
IntensityHow much of the glow is put on: 0.15 to start.
Low Frequency Boost and Low Frequency Boost CurvatureHow much more of the widest spread is put on, and how quickly that falls off toward the narrowest.
High Pass FrequencyHow much of the narrowest spread is kept, from 0 to 1.
PrefilterThreshold, how bright a pixel must be to glow (0 for every pixel), and Threshold Softness, how softly a pixel near it starts to glow.
Composite ModeEnergy Conserving, mixed in so the picture gives up what the glow adds, or Additive, added on top.
Max Mip DimensionThe largest picture the glow is spread over, in pixels: larger is finer and costs more.
ScaleHow far it spreads across and up: wider across makes a lens's streak.

From code, World.SetBloom and BloomOf. CameraBloom has Bevy's presets: Natural (the default), OldSchool, Anamorphic and ScreenBlur, a blur of the whole picture behind a menu. Giving a camera a bloom puts it in HDR, and null takes the bloom away.

world.SetBloom(camera, CameraBloom.Natural with { Threshold = 1f, ThresholdSoftness = 0.2f, Intensity = 0.3f });

Depth Of Field

What is at the focal distance is sharp, and nearer and farther blurs, as through a lens: the lower its f-number, the less is sharp. It works on a perspective camera, and is not drawn in a browser playing a web build's WebGL2 version (see Build for the web).

FieldWhat it does
ModeGaussian, a plain blur, the default, or Bokeh, a lens's blur where each bright point is a disc of light, finer and dearer.
Focal DistanceHow far away what is sharp is, in meters.
Sensor HeightThe height of the camera's sensor in meters, which with the field of view gives its focal length. It starts as a film camera's.
Aperture F StopsThe lens's f-number.
Max Circle Of Confusion DiameterThe widest a blur can be, in pixels.
Max DepthThe farthest anything counts as, in meters, where the sky is. It starts as infinity.

From code, World.SetDepthOfField and DepthOfFieldOf. CameraDepthOfField.Focused makes one sharp at a distance; told every frame, it can follow what the player looks at:

world.SetDepthOfField(camera, CameraDepthOfField.Focused(distance: 6f, fStops: 0.5f, mode: DepthOfFieldMode.Bokeh));

Motion Blur

Blurs what moves across the picture, as a film camera's shutter does: Shutter Angle, the share of a frame the shutter is open, 0.5 to start, where less is less blur, and Samples, how many steps the blur is made of.

Chromatic Aberration

Splits the colors apart toward the picture's edges, as a cheap lens does: Intensity and Max Samples.

Vignette

Darkens the picture toward its edges: Intensity, Radius, Smoothness, Roundness, Center, Edge Compensation and Color.

Auto Exposure

Brightens and darkens the picture as the eye adjusts, by how bright what the camera sees is: in a dark cave the world brightens, and stepping into daylight it darkens again. Speed Brighten and Speed Darken say how fast. It needs HDR and brings it. It counts the picture with a compute shader, which WebGL2 lacks, so a web build's WebGL2 version has no auto exposure.

Bevy's Lens Distortion is drawn too, but is not offered by Add Component, since it has no value to start from. Your game's Rust can put it on a camera.

Each setter writes nothing where the camera already has what it is told, so a game can set its effects every frame. Numbers an effect cannot take, such as a negative intensity, are refused with an AbyssException, and the effect is left as it was.

Cameras from code

Your C# reaches a camera by its entity. A system that reads Bevy's Camera3d, or Camera2d for a 2D game, finds it. Setting a camera's sky, fog or effects can add a component to it, so make those calls from a flow, which runs between frames (see Code that is not a system):

public sealed class WeatherPlugin : IPlugin{    private ulong _camera;
    public void Build(Schedule schedule)    {        World world = schedule.World;        ComponentLayout cameras = world.LayoutOf("Camera3d");
        // Finds the scene's camera: a system that only reads it.        schedule.Add("Find the camera", [cameras.Read()], context =>        {            foreach (Chunk chunk in context.Chunks)            {                if (chunk.Entities.Length > 0)                {                    _camera = chunk.Entities[0];                }            }        });
        // Changes it between frames.        schedule.AddFlow("Weather", async flow =>        {            var haze = new Vector4(0.68f, 0.81f, 0.95f, 1f);            while (true)            {                await flow.NextFrame();                if (_camera != 0)                {                    world.SetFog(_camera, CameraFog.Linear(haze, start: 60f, end: 120f));                    world.SetBloom(_camera, CameraBloom.Natural);                }            }        });    }}

Moving and turning a camera is writing its Transform, as for any entity.

Shake a camera

world.Cameras.Shake shakes a camera about where it is, for a hit or a boss's slam, as far as strength world units as it starts and less as it fades over seconds, 0.4 unless you say:

world.Cameras.Shake(camera, strength: 0.3f, seconds: 0.3f);

The camera moves across and up in the world, along X and Y, so a shake suits a 2D camera, or a 3D one looking along Z. A stronger shake takes over from one going on, and a weaker one does nothing. A camera follows its Camera Follow 2D through a shake, and a Pixel Perfect Camera shakes by whole art pixels (see 2D cameras). It moves the camera only while the game plays: in the editor, the Scene panel shows the camera where you placed it.

What is under the pointer

world.ScreenRay(camera, point) gives the ray the camera sees along through a point of the screen, in logical pixels from the top left of where it draws, as context.Input.Pointer measures the pointer: a Ray3D, where it starts and the way it goes. What is under the pointer is what the ray meets first, so cast it into the world's colliders, here with Physics 3D:

if (context.Input.Pointer is Vector2 pointer    && world.ScreenRay(camera, pointer) is { } ray    && world.Services.Get<Physics3D>().Raycast(ray.Origin, ray.Direction, 100f) is { } hit){    // hit.Entity is the body under the pointer}

It is null where the camera sees nothing through the point, or has not drawn yet. world.WorldToScreen(camera, point) goes the other way, from a point of the world to where it is drawn, for a label that follows something about (see 2D cameras for both of a 2D camera).

In the Scripting API