Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Coherent virtual trackball controller/camera plugin for Bevy

Build Downloads Version Rust License


Run simple and advanced examples in your browser using WebAssembly and WebGL.

Coherence Features

This is an alternative trackball technique using exponential map and parallel transport to preserve distances and angles for inducing coherent and intuitive trackball rotations. For instance, displacements on straight radial lines through the screen’s center are carried to arcs of the same length on great circles of the trackball (e.g., dragging the mouse along an eights of the trackball's circumference rolls the camera by 360/8=45 degrees, dragging the mouse from the screen's center to its further edge linearly rotates the camera by 1 radian, where the trackball's diameter is the maximum of the screen's width and height). This is in contrast to state-of-the-art techniques using orthogonal projection which distorts radial distances further away from the screen’s center (e.g., the rotation accelerates towards the edge).

  • Coherent and intuitive orbiting via the exponential map, see the underlying trackball crate which follows the recipe given in the paper of Stantchev, G.. “Virtual Trackball Modeling and the Exponential Map.”. S2CID 44199608. See the exponential_map example.
  • Coherent first person view aka free look or mouse look with the world trackball centered at eye instead of target.
  • Coherent scaling by translating mouse wheel device units, see TrackballWheelUnit. Scales eye distance from current cursor position or centroid of finger positions projected onto focus plane.
  • Coherent linear/angular TrackballVelocity for sliding/orbiting or free look by time-based input (e.g., pressed key). By default, the linear velocity is deduced from the angular velocity (where target and eye positions define the world radius) which in turn is defined in units of vertical field of view per seconds and hence independent of the world unit scale.

Additional Features

  • Time-free multi-touch gesture recognition for orbit, scale, slide, and focus (i.e., slide to cursor/finger position) operations.
  • Smoothing of movement implemented as fps-agnostic exponential easy-out.
  • Gimbal lock-free using quaternion instead of Euler angles.
  • Gliding clamp (experimental): The movement of a camera can be restricted to user-defined boundary conditions (e.g., to not orbit below the ground plane). When the movement is not orthogonal to a boundary plane, it is changed such that the camera glides along the boundary plane. Currently, only implemented for orbit and slide operations, see the gliding_clamp example.
  • Camera constellation: A camera is decoupled from its input controller and instead multiple cameras can be sensitive to zero or multiple selected controllers (e.g., a minimap controlled by the same controller of the main viewport).
  • Constellation clamp: Cameras sensitive to the same controller are referred to as a group and can be configured to clamp the movement for the whole group whenever a group member crosses a boundary condition (e.g., rigid and loose constellation clamp), see the constellation_clamp example.
  • Viewport stealing: This allows UI system (e.g., egui behind bevy_egui feature gate) to steal the viewport and hence capture the input instead, see the egui example.
  • Scale-preserving transitioning between orthographic and perspective projection mode.
  • Converting between scaling modes (i.e., fixed vertical or horizontal field of view or fixed unit per pixels). This defines whether the scene scales or the corresponding vertical or horizontal field of view adjusts whenever the height or width of the viewport is resized, see the scaling_modes example.
  • Object inspection mode scaling clip plane distances by measuring from target instead of eye. This benefits the precision of the depth map. Applicable, whenever the extend of the object to inspect is known and hence the near clip plane can safely be placed just in front of it.
  • f64-ready for large worlds (e.g., solar system scale) whenever Bevy is, see issue #1680.

See the release history to keep track of the development.

Input Mappings

Following mappings are the defaults which can be customized, see TrackballInput.

Mouse (Buttons) Touch (Fingers) Keyboard Operation
Left Press + Drag One + Drag ijkl Orbits around target.
↳ at trackball's border Two + Roll uo Rolls about view direction.
Middle Press + Drag Any + Drag + Left Shift ↑←↓→ First person view.
Right Press + Drag Two + Drag esdf Slides trackball on focus plane.
    gv Slides trackball in/out.
Scroll In/Out Two + Pinch Out/In hn Scales distance zooming in/out.
Left Press + Release Any + Release   Slides to cursor/finger position.
    p Toggle orthographic/perspective.
    Return Reset camera transform.


Add the TrackballPlugin followed by spawning a TrackballController together with a TrackballCamera and a Camera3dBundle or see simple and advanced examples.

use bevy::prelude::*;
use bevy_trackball::prelude::*;

// Add the trackball plugin.
fn main() {
		.add_systems(Startup, setup)

// Add a trackball controller and trackball camera to a camera 3D bundle.
fn setup(mut commands: Commands) {
	let [target, eye, up] = [Vec3::ZERO, Vec3::Z * 10.0, Vec3::Y];
		TrackballCamera::look_at(target, eye, up),

	// Set up your scene...


Copyright © 2023 Rouven Spreckels

This project is licensed under either of

at your option.


Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.