{"id":15137967,"url":"https://github.com/blackphlox/bevy_dolly","last_synced_at":"2025-04-08T09:06:00.380Z","repository":{"id":38398179,"uuid":"392849423","full_name":"BlackPhlox/bevy_dolly","owner":"BlackPhlox","description":"h3r2tic's dolly abstraction layer for the bevy game framework","archived":false,"fork":false,"pushed_at":"2024-12-21T19:20:00.000Z","size":10239,"stargazers_count":158,"open_issues_count":6,"forks_count":27,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-08T09:05:53.708Z","etag":null,"topics":["bevy","camera","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BlackPhlox.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-04T23:32:40.000Z","updated_at":"2025-04-06T12:47:53.000Z","dependencies_parsed_at":"2023-11-24T01:29:55.956Z","dependency_job_id":"83a97ba5-abb2-4e3e-91e4-7877f23984d8","html_url":"https://github.com/BlackPhlox/bevy_dolly","commit_stats":{"total_commits":275,"total_committers":10,"mean_commits":27.5,"dds":0.3781818181818182,"last_synced_commit":"d86a08ee6e0803a73bfcd67bdec38db9d26cfdda"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlackPhlox%2Fbevy_dolly","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlackPhlox%2Fbevy_dolly/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlackPhlox%2Fbevy_dolly/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlackPhlox%2Fbevy_dolly/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BlackPhlox","download_url":"https://codeload.github.com/BlackPhlox/bevy_dolly/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247809963,"owners_count":20999816,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bevy","camera","rust"],"created_at":"2024-09-26T07:03:55.202Z","updated_at":"2025-04-08T09:06:00.348Z","avatar_url":"https://github.com/BlackPhlox.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1\u003ebevy_dolly\u003c/h1\u003e\n\u003cdiv align=\"center\"\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003cth\u003eStatic\u003c/th\u003e\n    \u003cth\u003ePinned\u003c/th\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"https://github.com/BlackPhlox/bevy_dolly\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/BlackPhlox/BlackPhlox/master/bevy_dolly_1.svg\" alt=\"bevy dolly static\"\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"https://github.com/BlackPhlox/bevy_dolly\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/BlackPhlox/BlackPhlox/master/bevy_dolly_dev_0.svg\" alt=\"bevy dolly pinned\"\u003e\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n  \u003cdiv align=\"center\"\u003e\n\u003ca href=\"https://crates.io/crates/bevy_dolly\"\u003e\u003cimg src=\"https://img.shields.io/crates/v/bevy_dolly\" alt=\"link to crates.io\"\u003e\u003c/a\u003e\n\u003ca href=\"https://docs.rs/bevy_dolly\"\u003e\u003cimg src=\"https://docs.rs/bevy_dolly/badge.svg\" alt=\"link to docs.rs\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/BlackPhlox/bevy_dolly/blob/main/LICENSE-MIT\"\u003e\u003cimg src=\"https://img.shields.io/crates/l/bevy_dolly\" alt=\"link to license\"\u003e\u003c/a\u003e\n\u003ca href=\"https://crates.io/crates/bevy_dolly\"\u003e\u003cimg src=\"https://img.shields.io/crates/d/bevy_dolly\" alt=\"downloads/link to crates.io\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/BlackPhlox/bevy_dolly\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/BlackPhlox/bevy_dolly\" alt=\"stars/github repo\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/BlackPhlox/bevy_dolly/actions/workflows/main.yml\"\u003e\u003cimg src=\"https://github.com/BlackPhlox/bevy_dolly/actions/workflows/main.yml/badge.svg\" alt=\"github actions\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/bevyengine/bevy/blob/main/docs/plugins_guidelines.md#main-branch-tracking\"\u003e\u003cimg src=\"https://img.shields.io/badge/Bevy%20tracking-released%20version-lightblue\" alt=\"tracking bevy release branch\"\u003e\u003c/a\u003e\n\u003c/div\u003e\n\u003c/div\u003e\n\u003c/br\u003e\n\n## Overview\n\n`bevy_dolly` is a prototype plugin built for the [Bevy](https://github.com/bevyengine/bevy) game engine. It leverages the powerful [`dolly`](https://github.com/h3r2tic/dolly) crate, developed by [h3r2tic](https://github.com/h3r2tic), to control camera movement within a Bevy application.\n\n\u003e [!WARNING]  \n\u003e Be aware that `bevy_dolly`'s API is still undergoing revisions. Feedback on its ergonomics and developer experience (DX) is highly appreciated.\n\n## Dolly and Camera Movement\n\nIt's important to know that `dolly` is all about controlling how the camera moves and not changing the camera itself. This means you can use it for other things, like making a turret and its cannon move around.\n\nDolly operates in two essential steps:\n\n1. **Creating a Rig**: Define a `Rig` with drivers that the dolly can utilize. These drivers, which can control both translation, rotation, constraints and custom behavior as abstractions. These rigs serve as tools to shape the camera's behavior and provide additional functionality.\n\n2. **Marker Component**: Register a marker component on both the Camera and the Rig (rig component tag). This allows you to easily switch the behavior of a camera entity by changing the associated rig component tag. To understand the process better, refer to the [examples](#example-showcase).\n\n## Understanding Drivers\n\nDrivers are mechanisms that influence the behavior of the camera. They can represent constraints or provide additional functionality. To explore the available drivers, refer to the [examples](#example-showcase).\n\nIn your `Cargo.toml`:\n\n```toml\n[dependencies]\n# Your bevy dependency here ... \n# bevy = \"0.15\"\nbevy_dolly = { version = \"0.0.5\" }\n```\n\nIn your Bevy App:\n\n```rust\n// The component tag used to parent to a Dolly Rig\n#[derive(Component)]\nstruct MainCamera;\n\nfn main() {\n  App::new()\n    .add_plugins(DefaultPlugins)\n    //..\n    .add_systems(Startup, setup)\n    .add_systems(Update, Dolly::\u003cMainCamera\u003e::update_active)\n    .add_systems(Update, update_input)\n    //..\n    .run();\n}\n```\n\nIn the setup system:\n\n```rust\n// In your setup system\nfn setup(\n  mut commands: Commands,\n) {\n  commands.spawn((\n    MainCamera, // The rig component tag \n    Rig::builder() // The rig itself\n      .with(Position::new(Vec3::ZERO)) // Start position\n      // Adds a driver with the method rotate_yaw_pitch\n      .with(YawPitch::new().yaw_degrees(45.0).pitch_degrees(-30.0)) \n      // Interpolation when the translation is updated, also known as smoothing\n      .with(Smooth::new_position(0.3)) \n      // Interpolation when the rotation is updated (updated via the YawPitch driver)\n      .with(Smooth::new_rotation(0.3)) \n      // Moves the camera point out in the Z direction and uses the position as the pivot\n      .with(Arm::new(Vec3::Z * 4.0)) \n      .build(),\n    Camera3dBundle::default(), // The camera which is related via the rig tag \n  ));\n}\n```\n\nAnd your runtime to update the rig:\n\n```rust\nfn update_input(\n  mut commands: Commands,\n  keys: Res\u003cInput\u003cKeyCode\u003e\u003e,\n  mut rig_q: Query\u003c\u0026mut Rig\u003e,\n) {\n  let mut rig = rig_q.single_mut();\n  if let Some(yaw_pitch) = rig.try_driver_mut::\u003cYawPitch\u003e() {\n      if keys.just_pressed(KeyCode::Z) {\n          yaw_pitch.rotate_yaw_pitch(-90.0, 0.0);\n      }\n  }\n}\n```\n\n## Helper Plugins\n\n`bevy_dolly` provides some helper plugins by default, which can be removed if not needed when setting up `bevy_dolly` as a dependency:\n\n```toml\n[dependencies]\nbevy_dolly = { version = \"0.0.5\", default-features = false }\n```\n\nTo include the drivers back, add `features = [\"drivers\"],` to the dependency.\n\n## Example Showcase\n\nExplore practical examples in the [examples repository](/examples/README.md).\n\n### Running Examples\n\nIf you've cloned the project and want to test, execute the following command to run the `orbit` example:\n\n```bash\ncargo run --release --example orbit\n```\n\n## Compatibility and Support\n\n|bevy|bevy_dolly|\n|---|---|\n|0.15|0.0.5|\n|0.14|0.0.4|\n|0.13|0.0.3|\n|0.12|0.0.2|\n|0.11|0.0.1|\n\n## Alternatives\n\nExplore other Bevy camera controllers that might suit your needs:\n\n- [bevy_fps_controller](https://github.com/qhdwight/bevy_fps_controller) - A Fps controller with crouching, sprinting, flymode and more\n- [smooth-bevy-cameras](https://github.com/bonsairobo/smooth-bevy-cameras) - 3 Smooth Camera controllers: Fps, Orbit or Unreal\n- [bevy_spectator](https://github.com/JonahPlusPlus/bevy_spectator) - A spectator camera controller\n- [bevy_flycam](https://github.com/sburris0/bevy_flycam) - A simple fly camera\n- [bevy_fly_camera](https://github.com/mcpar-land/bevy_fly_camera) - A advanced fly camera\n- [bevy_pancam](https://github.com/johanhelsing/bevy_pancam) - 2D Click and Drag - Style camera movement\n- [bevy_config_cam](https://github.com/BlackPhlox/bevy_config_cam) - Plugin that enables to use collection of different camera controllers at runtime, uses bevy_dolly as the backend\n\n## Licensing\n\nThe project is under a dual license: MIT and Apache 2.0. Feel free to contribute within the bounds of these licenses.\n\n## Contributing\n\nYes this project is still a WIP, so PRs are very welcome.\n\n\u003e [!NOTE]  \n\u003e Note that the `dolly` dependency used is a slightly patched submodule to allow for native bevy transform types. To build the crate locally, run:\n\u003e\n\u003e ```bash\n\u003e git submodule update --init --recursive\n\u003e ```\n\u003e\n\u003e Followed by:\n\u003e\n\u003e ```bash\n\u003e cd dolly\n\u003e git checkout bevy_0.15\n\u003e ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackphlox%2Fbevy_dolly","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblackphlox%2Fbevy_dolly","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackphlox%2Fbevy_dolly/lists"}