NEOLearn

Cameras

Spawn a 3D camera, choose a perspective or orthographic projection, split the screen, render to a texture and convert between screen and world positions.

Updated October 20, 2026

On this page

A camera decides what part of the world is drawn and where the picture goes. Nothing is rendered until at least one camera exists. Most games have one 3D camera that renders to the window; you add more for split screen, mirrors, minimaps or a UI overlay.

Spawn a camera#

Camera3d turns an entity into a 3D camera. It brings Camera, Projection, Transform and the visibility components with it, so a transform is all you usually add:

Rust
use neo::prelude::*;

fn setup(mut commands: Commands) {
    commands.spawn((
        Camera3d::default(),
        Transform::from_xyz(-2.0, 2.5, 5.0).looking_at(Vec3::ZERO, Vec3::Y),
    ));
}

The camera looks along its local −Z axis, with +Y up. Transform::looking_at points it at a target.

For 2D, use Camera2d; see 2D cameras.

The Camera component#

Camera holds the settings shared by every kind of camera:

FieldWhat it does
orderCameras that render to the same target draw in increasing order. Default 0. Two active cameras on one target with the same order log a warning.
is_activefalse stops the camera rendering without despawning it.
viewportSome(Viewport { .. }) draws into a rectangle of the target instead of all of it.
clear_colorClearColorConfig::Default (the ClearColor resource), Custom(Color) or None (draw over what's already there).
sub_camera_viewRenders one part of a larger image, for tiled or multi-monitor output.

The world-wide background colour is the ClearColor resource:

Rust
app.insert_resource(ClearColor(Color::srgb(0.1, 0.1, 0.12)));

Projections#

Projection is a component with three variants:

VariantUse it for
Projection::Perspective(PerspectiveProjection)The default. fov is the vertical field of view in radians; near and far are the clip planes.
Projection::Orthographic(OrthographicProjection)No perspective: isometric views, CAD-style views, strategy maps. Size it with scaling_mode and scale.
Projection::Custom(..)Your own projection matrix. Example: cargo run --example custom_projection.
Rust
use neo::camera::ScalingMode;

// a wider field of view
commands.spawn((
    Camera3d::default(),
    Projection::from(PerspectiveProjection {
        fov: 70.0_f32.to_radians(),
        ..default()
    }),
));

// an isometric-style view, 6 world units tall whatever the window size
commands.spawn((
    Camera3d::default(),
    Projection::from(OrthographicProjection {
        scaling_mode: ScalingMode::FixedVertical { viewport_height: 6.0 },
        ..OrthographicProjection::default_3d()
    }),
    Transform::from_xyz(5.0, 5.0, 5.0).looking_at(Vec3::ZERO, Vec3::Y),
));

ScalingMode also has WindowSize, Fixed, AutoMin, AutoMax and FixedHorizontal. To zoom, change fov (perspective) or scale (orthographic). Example: cargo run --example projection_zoom.

More than one camera#

Split screen#

Give each camera a viewport and a different order:

Rust
use neo::camera::Viewport;

fn set_viewports(window: Single<&Window>, mut cameras: Query<(&mut Camera, &PlayerCamera)>) {
    let size = window.physical_size();
    let half = UVec2::new(size.x / 2, size.y);
    for (mut camera, player) in &mut cameras {
        camera.viewport = Some(Viewport {
            physical_position: UVec2::new(player.0 * half.x, 0),
            physical_size: half,
            ..default()
        });
    }
}

#[derive(Component)]
struct PlayerCamera(u32); // 0 = left, 1 = right

Update the viewports when the window is resized. Example: cargo run --example split_screen.

Layering cameras#

A camera with a higher order and clear_color: ClearColorConfig::None draws on top of the one before it. Combined with render layers, this is how a first-person game draws the player's arms with their own field of view over the world. Example: cargo run --example first_person_view_model.

Render to a texture#

RenderTarget is a component next to Camera. The default is the primary window; point it at an image to render into a texture, then use that texture in a material or UI:

Rust
use neo::camera::RenderTarget;
use neo::render::render_resource::TextureFormat;

fn setup(mut commands: Commands, mut images: ResMut<Assets<Image>>) {
    let image = images.add(Image::new_target_texture(
        512,
        512,
        TextureFormat::Rgba8Unorm,
        Some(TextureFormat::Rgba8UnormSrgb),
    ));
    commands.spawn((
        Camera3d::default(),
        Camera { order: -1, ..default() }, // render before the main camera
        RenderTarget::Image(image.clone().into()),
        Transform::from_xyz(0.0, 0.0, 15.0).looking_at(Vec3::ZERO, Vec3::Y),
    ));
    // use `image` as a StandardMaterial's base_color_texture, an ImageNode, ...
}

RenderTarget::Window(WindowRef::Entity(e)) renders to another window. Examples: render_to_texture, mirror (needs the neo_feathers feature), render_depth_to_texture.

Screen and world positions#

Camera converts between viewport pixels and the world. Pair it with the camera's GlobalTransform:

MethodReturns
viewport_to_world(transform, pos)A Ray3d from the camera through a viewport position, such as the cursor.
viewport_to_world_2d(transform, pos)The world position under a viewport position, for 2D cameras.
world_to_viewport(transform, point)Where a world point appears on screen.
world_to_ndc(transform, point)Normalized device coordinates.
logical_viewport_size()The viewport's size in logical pixels.
Rust
fn cursor_on_ground(
    camera: Single<(&Camera, &GlobalTransform)>,
    window: Single<&Window>,
    mut gizmos: Gizmos,
) {
    let (camera, transform) = *camera;
    if let Some(cursor) = window.cursor_position()
        && let Ok(ray) = camera.viewport_to_world(transform, cursor)
        && let Some(point) = ray.plane_intersection_point(Vec3::ZERO, InfinitePlane3d::new(Vec3::Y))
    {
        gizmos.sphere(point, 0.2, Color::WHITE);
    }
}

These return an error until the camera has rendered its first frame. Example: cargo run --example 3d_viewport_to_world. To find which entity is under the cursor, use picking.

Render at a lower resolution#

Two NEO components trade sharpness for speed:

ComponentWhat it does
RenderResolution(UVec2)Renders the camera's world at that size in physical pixels and upscales it once to the target. UI the camera draws stays at the target's full resolution. Ignored for cameras with a viewport.
MainPassResolution(UVec2)With RenderResolution, draws the main passes into only that top-left part of the textures. Change it every frame for dynamic resolution without reallocating textures.

Both are in neo::camera. NEO's phone builds use RenderResolution to cap the 3D view at 720 lines while the UI stays sharp.

Cameras in NEO games#

Games built on the gameplay kit don't move their camera by hand. NEO's camera director picks which camera source each rendering camera shows, blends between them and adds shake and collision; the Studio's viewport camera is one of its sources. See Camera.

Next steps#