Camera

Games and the Studio share one camera system, the neo_camera crate. A director decides what each rendering camera shows, blends smoothly from one camera source to another, and layers modifiers such as shake on top. The Studio's own viewport camera is just another source, which is why the Studio can fly away from the game camera and back without the game noticing.

This page is for creators who write Rust game code.

The pieces#

Set up a camera#

Spawn a rendering camera with CameraOutput, spawn sources, and tell the director which one to show:

use bevy::prelude::*;
use neo_camera::*;

fn setup(mut commands: Commands, mut view: MessageWriter<SetViewTarget>) {
    // the rendering camera
    commands.spawn((Camera3d::default(), CameraOutput::default()));
    // two sources
    let editor = commands
        .spawn(EditorCameraController::looking_at(Vec3::new(6.0, 4.0, 8.0), Vec3::ZERO))
        .id();
    let cinematic = commands
        .spawn((
            NeoCameraSource::with_priority(10),
            CameraLens::perspective(40f32.to_radians()),
            Transform::from_xyz(0.0, 2.0, 12.0).looking_at(Vec3::ZERO, Vec3::Y),
        ))
        .id();
    // show the first one now; later, blend to the other over 0.6 s:
    // view.write(SetViewTarget::new(cinematic, CameraBlend::ease_in_out(0.6)));
    view.write(SetViewTarget::new(editor, CameraBlend::CUT));
}

Without an explicit view target, an output shows the enabled source with the highest priority (ties go to the most recently spawned source). A disabled source is never picked by priority, but an explicit view target still shows it.

A source is any entity with a transform and a lens: your game's third-person rig, a cutscene camera, a camera on a moving vehicle. Your systems move sources as usual. The director samples them after transforms are propagated each frame, so a camera parented to a moving character is followed with no frame of lag, and the pose it writes is the one that's rendered.

Blends#

Each output keeps a stack of transitions. A new view target blends in over the live result of everything under it, not a frozen picture:

• Interrupting a blend starts from exactly what is on screen, and the interrupted transition keeps running underneath, so the motion stays smooth, speed included.
• When a transition reaches full weight, everything under it is dropped.
• lock_outgoing (CameraBlend::ease_in_out(0.6).locking_outgoing()) freezes the outgoing view at its last pose. Use it when the source you're leaving is about to teleport, such as a game reset.
• A source that is despawned keeps its last pose until a transition covers it.

How poses blend:

Game cameras#

A game's own camera works with the director without any changes to game code. By default, every GameCamera becomes both an output and a source of itself:

• The director reads the game's own Transform as that source's pose and writes the rendered pose only to the camera's global transform and projection. The game never sees another camera's pose in its Transform.
• When the game camera is the only thing shown and no modifier is active, it passes straight through unchanged.
• The game's look (exposure, bloom, post-processing), the camera its UI draws to and the render target all stay on that one camera, so other sources render the world exactly as the game does.

This is how the Studio works: Play shows the game camera, eject (F8) blends to the Studio's viewport camera at the game camera's pose while the game keeps running, and F8 again goes back.

You can also use a dedicated output camera with separate, non-rendering source entities. The director supports both.

Modifiers#

Modifiers are components on the output entity, applied after the blend in a fixed order. Each is weighted by ModifierSettings.weight, and can be scoped to one source with source: Some(entity), in which case it fades in and out with that source's share of the blend. The game camera's collision, for example, fades out as another camera blends in.

To write your own, add a system in NeoCameraSystems::Modify, ordered with ModifierStage (Geometry, then Lens, then Noise), that edits CameraOutput::working_pose_mut().

The Studio's viewport camera#

EditorCameraController is the source the Studio's viewport uses. It only takes input while it's the active source of an output, while the host allows it (CameraInputScope), and when a drag starts inside the viewport. Movement is smoothed, and jumps (framing, bookmarks, view changes) ease over a short time.

Switching between perspective and orthographic views keeps the framing.

Commands#

Next steps#

• Gameplay kit
• Play in the Studio
• Scene and objects
• Engine reference