Crate bevy_lagrange

Expand description

§`bevy_lagrange`

Work in progress. This crate is in active development and not subject to semver stability guarantees. APIs will change without notice between commits. Do not depend on this in production code yet.

A camera controller for Bevy that combines smooth orbit controls with event-driven camera operations — zoom-to-fit, queued animations, and a debug overlay for fit targets.

A screen recording showing camera movement

§Features

Smooth orbit, pan, and zoom with configurable limits
Zoom-to-fit, look-at, and queued camera animations with easing
Event-driven control with full lifecycle events for sequencing
Orthographic and perspective projection, multi-viewport, render-to-texture
Touch, trackpad, and bevy_egui support
Debug overlay for fit targets (optional fit_overlay feature)

§Quick Start

Add the plugin and spawn a camera:

use bevy::prelude::*;
use bevy_lagrange::LagrangePlugin;
use bevy_lagrange::OrbitCam;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(LagrangePlugin)
        .add_systems(Startup, setup)
        .run();
}

fn setup(mut commands: Commands) {
    commands.spawn((
        Transform::from_translation(Vec3::new(0.0, 1.5, 5.0)),
        OrbitCam::default(),
    ));
}

OrbitCam automatically requires Camera3d. Out of the box you get orbit, pan, and zoom with smoothing.

§Controls

Default mouse controls:

Input	Action
Left Mouse	Orbit
Right Mouse	Pan
Scroll Wheel	Zoom

Default touch controls:

Input	Action
One finger	Orbit
Two fingers	Pan
Pinch	Zoom

All controls are configurable via OrbitCam fields — buttons, modifiers, sensitivity, smoothness, and limits.

§Event-Driven Camera Control

Enable the fit_overlay feature:

bevy_lagrange = { version = "...", features = ["fit_overlay"] }

§Zoom-to-fit

Frame a target entity in the camera view:

commands.trigger(
    ZoomToFit::new(camera, target)
        .margin(0.15)
        .duration(Duration::from_millis(800))
        .easing(EaseFunction::CubicOut),
);

§Look at

Rotate the camera in place to face a target:

commands.trigger(
    LookAt::new(camera, target)
        .duration(Duration::from_millis(600)),
);

§Animate to a specific orientation

Animate to a chosen yaw/pitch while framing the target:

commands.trigger(
    AnimateToFit::new(camera, target)
        .yaw(PI / 4.0)
        .pitch(PI / 6.0)
        .duration(Duration::from_millis(1200)),
);

§Queued animations

Chain multiple movements into a sequence:

commands.trigger(PlayAnimation::new(camera, [
    CameraMove::ToOrbit {
        focus: Vec3::ZERO,
        yaw: 0.0,
        pitch: 0.5,
        radius: 5.0,
        duration: Duration::from_millis(800),
        easing: EaseFunction::CubicOut,
    },
]));

All operations support instant (Duration::ZERO) and animated paths with full lifecycle events for sequencing.

§Cargo Features

Feature	Default	Description
`fit_overlay`	no	Zoom-to-fit, camera animations, event-driven control, and debug overlay
`bevy_egui`	no	Prevents camera movement when interacting with egui windows

§Version Compatibility

bevy_lagrange	Bevy
0.0.2	0.18

§Credits

Plonq — bevy_lagrange builds on bevy_panorbit_camera, with permission

§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.

Structs§

ActiveCameraData: Tracks which OrbitCam is active (should handle input events).
AnimateToFit: AnimateToFit — animates the camera to a caller-specified orientation.
AnimationBegin: AnimationBegin — emitted when a CameraMoveList begins processing.
AnimationCancelled: AnimationCancelled — emitted when an animation is cancelled before completion.
AnimationEnd: AnimationEnd — emitted when a CameraMoveList finishes all its queued moves.
AnimationRejected: AnimationRejected — emitted when an incoming animation request is rejected.
CameraMoveBegin: CameraMoveBegin — emitted when an individual CameraMove begins.
CameraMoveEnd: CameraMoveEnd — emitted when an individual CameraMove completes.
CameraMoveList: Component that queues multiple camera movements to execute sequentially.
CurrentFitTarget: Marks the entity that the camera is currently fitted to.
InputControl: Interactive input configuration for OrbitCam.
LagrangePlugin: Bevy plugin that contains the systems for controlling OrbitCam components.
LookAt: LookAt — rotates the camera in place to face a target entity.
LookAtAndZoomToFit: LookAtAndZoomToFit — rotates the camera to face a target entity and frames it.
OrbitCam: Tags an entity as capable of panning and orbiting.
OrbitCamSystemSet: Base system set to allow ordering of OrbitCam
PlayAnimation: PlayAnimation — plays a queued sequence of CameraMove steps.
SetFitTarget: Sets the debug overlay target without triggering a zoom.
TrackpadInput: Trackpad-specific input configuration for OrbitCam.
ZoomBegin: ZoomBegin — emitted when a ZoomToFit operation begins.
ZoomCancelled: ZoomCancelled — emitted when a ZoomToFit animation is cancelled before completion.
ZoomContext: Context for a zoom-to-fit operation.
ZoomEnd: ZoomEnd — emitted when a ZoomToFit operation completes (both animated and instant).
ZoomToFit: ZoomToFit — frames a target entity in the camera view.

Enums§

AnimationConflictPolicy: Controls what happens when a new animation request conflicts with an active one.
AnimationSource: Identifies which event triggered an animation lifecycle.
ButtonZoomAxis: Which axis controls button-based zoom.
CameraInputInterruptBehavior: Controls what happens when user input occurs during an in-flight animation.
CameraMove: Individual camera movement with target position and duration.
FocusBoundsShape: The shape to restrict the camera’s focus inside.
ForceUpdate: Whether to force a transform update this frame regardless of input.
InitializationState: Whether OrbitCam has been initialized from the camera’s current transform.
TimeSource: Which time source drives camera smoothing.
TouchInput: The control scheme to use for touch input. Given that some touch gestures don’t make sense being changed (e.g. pinch to zoom), there is just a set if different schemes rather than full customization.
TrackpadBehavior: Selects how trackpad input is interpreted.
UpsideDownPolicy: Whether the camera is allowed to orbit past the poles into an upside-down orientation.
ZoomDirection: Direction of scroll/zoom input.