Agapanthus / bevy_panorbit_camera

A simple pan and orbit camera for the Bevy game engine

Bevy Pan/Orbit Camera

Summary

Bevy Pan/Orbit Camera provides orbit camera controls for Bevy Engine, designed with simplicity and flexibility in mind. Use it to quickly prototype, experiment, for model viewers, and more!

Features:

• Smoothed orbiting, panning, and zooming
• Works with orthographic camera projection in addition to perspective
• Customisable controls, sensitivity, and more
• Touch support
• Works with multiple viewports and/or windows
• Easy to control manually, e.g. for keyboard control or animation
• Can control cameras that render to a texture

Controls

Default mouse controls:

• Left Mouse - Orbit
• Right Mouse - Pan
• Scroll Wheel - Zoom

Default touch controls:

• One finger - Orbit
• Two fingers - Pan
• Pinch - Zoom

Quick Start

Add the plugin:

.add_plugins(PanOrbitCameraPlugin)

Add PanOrbitCamera to a camera:

commands.spawn((
    Camera3dBundle {
        transform: Transform::from_translation(Vec3::new(0.0, 1.5, 5.0)),
        ..default()
    },
    PanOrbitCamera::default(),
));

This will set up a camera with good defaults.

Check out the advanced example to see all the possible configuration options.

What are alpha and beta?

Typically you don't need to worry about the inner workings of this plugin - the defaults work well and are suitable for most use cases. However, if you want to customise the behaviour, for example restricting the camera movement or adjusting sensitivity, you probably want to know what the alpha and beta values represent.

While not strictly accurate, you can think of alpha as yaw and beta as tilt. More accurately, alpha represents the angle around the global Y axis, and beta represents the angle around the local X axis (i.e. the X axis after Y axis rotation has been applied). When both alpha and beta are 0.0, the camera is pointing directly forward (-Z). Thus, increasing alpha orbits around to the right (counter clockwise if looking from above), and increasing beta orbits up and over (e.g. a beta value of 90 degrees (PI / 2.0) results in the camera looking straight down).

Cargo Features

• bevy_egui (optional): Makes PanOrbitCamera ignore any input that egui uses, thus preventing moving the camera when interacting with egui windows

Version Compatibility

bevy	bevy_panorbit_camera
0.13	0.14-0.15
0.12	0.9-0.13
0.11	0.6-0.8
0.10	0.1-0.5

Credits

• Bevy Cheat Book: For providing an example that I started from
• babylon.js: I referenced their arc rotate camera for some of this
• bevy_pancam: For the egui feature idea

License

All code in this repository is dual-licensed under either:

• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

at your option. This means you can select the license you prefer! This dual-licensing approach is the de-facto standard in the Rust ecosystem and there are very good reasons to include both.