#camera #bevy #camera-control #orbit #gamedev

bevy_third_person_camera

A third person camera written for Bevy

15 releases

0.1.14 Oct 5, 2024
0.1.11 Jul 9, 2024
0.1.10 Feb 25, 2024
0.1.7 Nov 11, 2023
0.1.1 Jul 30, 2023

#91 in Game dev

Download history 35/week @ 2024-08-05 55/week @ 2024-08-12 30/week @ 2024-08-19 15/week @ 2024-08-26 46/week @ 2024-09-02 279/week @ 2024-09-09 34/week @ 2024-09-16 121/week @ 2024-09-23 181/week @ 2024-09-30 88/week @ 2024-10-07 53/week @ 2024-10-14 29/week @ 2024-10-21 90/week @ 2024-10-28 131/week @ 2024-11-04 6/week @ 2024-11-11 15/week @ 2024-11-18

246 downloads per month
Used in sjqmmo

MIT/Apache

42KB
512 lines

Bevy Third Person Camera

  • Aim
  • Zoom in/out
  • Orbit
  • Custom Offset
  • Cursor Lock
  • Custom Sensitivity
  • Full Gamepad Support!

camera demo

Getting Started

Add the bevy_third_person_camera crate:

cargo add bevy_third_person_camera

Import the bevy_third_person_camera crate:

use bevy_third_person_camera::*;

Add the ThirdPersonPlugin:

.add_plugins(ThirdPersonCameraPlugin)

Add the ThirdPersonCamera component to the camera entity:

commands.spawn((
    ThirdPersonCamera::default(),
    Camera3dBundle::default()
));

Add the ThirdPersonCameraTarget component to your player:

// Player
commands.spawn((
    PbrBundle {
        mesh: meshes.add(Mesh::from(shape::Cube::new(1.0))),
        material: materials.add(Color::BLUE.into()),
        transform: Transform::from_xyz(0.0, 0.5, 0.0),
        ..default()
    },
    ThirdPersonCameraTarget,
    Player,
));

That's it!

Examples

  • default
  • custom
  • physics
cargo run --example <example name>

Features

Offset

The offset will 'offset' the x and y values of the camera respectively. Offset is disabled by default. Turn on with offset_enabled: true

offset_enabled: true,
offset: Offset::new(0.5, 0.25),
offset_toggle_key: Some(KeyCode::T),
offset_toggle_speed: 5.0 // default

offset demo

Aim

Aiming is calculated using the aim_zoom & the zoom.min values. Please note that the actual zoom level will vary if you change the zoom.min value, even if the aim_zoom value stays the same. Aiming is disabled by default. Turn on with aim_enabled: true

aim_enabled: true, // default
aim_speed: 3.0, // default
aim_zoom: 0.7, // default
aim_button: Some(MouseButton::Right), // default
zoom: Zoom::new(1.5, 3.0)

aim demo

Cursor Lock

The cursor lock feature allows the mouse cursor to toggle between a locked, hidden state, to an unlocked, visible state. When unlocked, the orbiting feature is disabled, thus allowing the cursor to move freely within the window without disrupting the camera's transform. This feature can be fully disabled by setting the enable_cursor_lock_toggle value to false and will keep the cursor locked and hidden.

cursor_lock_toggle_enabled: true,
cursor_lock_active: true,
cursor_lock_key: KeyCode::Space,

cursor lock demo

Orbit

Orbiting is enabled by default. However, you can set the mouse_orbit_button_enabled setting to true and the orbiting will only be active while the mouse_orbit_button is pressed.

Custom Settings

Most settings can be overridden:

let gamepad = Gamepad::new(0);
commands.spawn((
    // These are the default settings
    ThirdPersonCamera {
        aim_enabled: false,
        aim_button: Some(MouseButton::Right),
        aim_speed: 3.0,
        aim_zoom: 0.7,
        cursor_lock_toggle_enabled: true,
        cursor_lock_active: true,sa
        cursor_lock_key: KeyCode::Space,
        sensitivity: Vec2::new(1.0, 1.0),
        mouse_orbit_button_enabled: false,
        mouse_orbit_button: MouseButton::Middle,
        offset_enabled: false,
        offset: Offset::new(0.5, 0.4),
        offset_toggle_speed: 5.0,
        offset_toggle_key: Some(KeyCode::T), // default is None
        zoom: Zoom::new(1.5, 3.0),
        zoom_sensitivity: 1.0,
        gamepad_settings: CameraGamepadSettings {
            aim_button: Some(GamepadButton::new(gamepad, GamepadButtonType::LeftTrigger2)),
            mouse_orbit_button: GamepadButton::new(gamepad, GamepadButtonType::LeftTrigger),
            sensitivity: Vec2::new(7.0, 4.0),
            offset_toggle_button: Some(GamepadButton::new(gamepad, GamepadButtonType::DPadRight)), // default is None
            zoom_in_button: GamepadButton::new(gamepad, GamepadButtonType::DPadUp),
            zoom_out_button: GamepadButton::new(gamepad, GamepadButtonType::DPadDown),
        },
        ..default()
    },
    Camera3dBundle::default(),
));

Physics Support

When using third party physics engines such as bevy rapier 3d or avian 3d, you should force the 'sync_player_camera' system to run after the physics systems. Failing to do this will cause a jittering effect to occur when applying forces/impulses to an object that has a camera entity attached. Simply add the following to your App::new() method (also see examples/physics.rs for complete example):

.configure_sets(PostUpdate, CameraSyncSet.after(PhysicsSet::StepSimulation)) // Bevy Rapier 3d
.configure_sets(PostUpdate, CameraSyncSet.after(PhysicsSet::Sync)) // Avian 3d

Default Controls

Action Mouse/Keyboard Gamepad Enabled by Default
Zoom In Scroll Up D Pad Up Yes
Zoom Out Scroll Down D Pad Down Yes
Aim Right Mouse Button Left Trigger No
Toggle Offset E D Pad Right No
Cursor Lock/Unlock Space n/a Yes
Orbit Button Middle Mouse Button Left Bumper No

Bevy Version Compatibility

bevy bevy_third_person_camera
0.14 0.1.11 - 0.1.14
0.13 0.1.9 - 0.1.10
0.12 0.1.7 - 0.1.8
0.11 0.1.1 - 0.1.6

Refer to the Changelog to view breaking changes and updates.

Migration Guides

License

Dependencies

~24MB
~452K SLoC