{"id":15654044,"url":"https://github.com/joseph-gio/bevy-mouse-tracking","last_synced_at":"2025-04-14T21:53:11.900Z","repository":{"id":39578946,"uuid":"329031487","full_name":"joseph-gio/bevy-mouse-tracking","owner":"joseph-gio","description":"A plugin for effortless mouse tracking in the bevy game engine.","archived":false,"fork":false,"pushed_at":"2024-02-24T06:35:51.000Z","size":164,"stargazers_count":29,"open_issues_count":3,"forks_count":11,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-28T02:48:15.588Z","etag":null,"topics":["bevy","bevy-engine","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joseph-gio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-01-12T15:35:34.000Z","updated_at":"2024-11-11T07:39:18.000Z","dependencies_parsed_at":"2024-10-23T07:32:24.154Z","dependency_job_id":null,"html_url":"https://github.com/joseph-gio/bevy-mouse-tracking","commit_stats":{"total_commits":47,"total_committers":8,"mean_commits":5.875,"dds":"0.44680851063829785","last_synced_commit":"fd118a6faa247523f65f9b08814dd5135b3654be"},"previous_names":["joseph-gio/bevy-mouse-tracking","jojojet/bevy-mouse-tracking"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joseph-gio%2Fbevy-mouse-tracking","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joseph-gio%2Fbevy-mouse-tracking/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joseph-gio%2Fbevy-mouse-tracking/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joseph-gio%2Fbevy-mouse-tracking/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joseph-gio","download_url":"https://codeload.github.com/joseph-gio/bevy-mouse-tracking/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248968754,"owners_count":21191158,"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","bevy-engine","rust"],"created_at":"2024-10-03T12:49:14.227Z","updated_at":"2025-04-14T21:53:11.881Z","avatar_url":"https://github.com/joseph-gio.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bevy_mouse_tracking_plugin\n\n\u003c!-- cargo-rdme start --\u003e\n\n[![CI](https://github.com/JoJoJet/bevy-mouse-tracking/actions/workflows/ci.yml/badge.svg)](https://github.com/JoJoJet/bevy-mouse-tracking/workflows/ci.yml)\n[![bevy_mouse_tracking on crates.io](https://img.shields.io/crates/v/bevy_mouse_tracking_plugin.svg)](https://crates.io/crates/bevy_mouse_tracking_plugin)\n[![bevy_mouse_tracking docs](https://img.shields.io/badge/docs-docs.rs-orange.svg)](https://docs.rs/bevy_mouse_tracking_plugin)\n\n## Versions\n\n| Bevy Version | Crate Version |\n|--------------|---------------|\n| 0.12         | 0.7           |\n| 0.11         | 0.6           |\n| 0.9          | 0.5           |\n| 0.8          | 0.4           |\n| 0.7          | 0.2.1         |\n| 0.6          | 0.2.0         |\n| main branch  | main branch   |\n\nThis crate aims to make mouse tracking both effortless and explicit.\nTracking is opt-in and handled opaquely by this plugin.\n\nThe mouse can be tracked on a per-camera basis by querying for tracking components.\nAdditionally, a global resource is maintained that tracks the main camera, if applicable.\n\n## Basics\n\n```rust\nuse bevy::prelude::*;\nuse bevy_mouse_tracking_plugin::prelude::*;\n\n// First, add the plugin to your `App`.\n\nApp::new()\n    .add_plugins((DefaultPlugins, MousePosPlugin))\n    .add_systems(Startup, setup)\n    .add_systems(Update, dbg_mouse)\n    // ...\n\n\nfn setup(mut commands: Commands) {\n    commands\n        // Spawn a camera bundle\n        .spawn(Camera2dBundle::default())\n        // Opt in to mouse tracking.\n        // `InitMouseTracking` is a command that adds the mouse tracking\n        // component to the camera with a correct initial value.\n        .add(InitMouseTracking);\n}\n\n// Now, we can track the mouse position by querying for it.\n\nuse bevy_mouse_tracking_plugin::MousePos;\n\nfn dbg_mouse(mouse: Query\u003c\u0026MousePos\u003e) {\n    // This will print the screen-space location of the mouse on every frame.\n    eprintln!(\"{}\", *mouse.single());\n    // If we did `mouse.iter()` instead, this will naturally work for multiple cameras.\n}\n```\n\nHaving to call `Query::single` is a bit annoying, and potentially error-prone.\nInstead, we can specify a main camera, which the plugin will treat specially.\n\n```rust\nuse bevy_mouse_tracking_plugin::MainCamera;\n\nfn setup(mut commands: Commands) {\n    commands\n        // Spawn a camera with tracking.\n        .spawn(Camera2dBundle::default())\n        .add(InitMouseTracking)\n        // Add a component to mark it as the main camera.\n        .insert(MainCamera);\n}\n\n// Now that we've specified the main camera, we can get the mouse position using a global resource.\n\nfn dbg_mouse(mouse: Res\u003cMousePos\u003e) {\n    // This will print the screen-space location of the mouse on every frame.\n    eprintln!(\"{}\", *mouse);\n}\n```\n\n## World-space\n\nWe can do better than just screen-space: this crate supports automatic\ntransformation to world-space coordinates via [`MousePosWorld`]\n-- this is can be accessed as either a component or a resource.\n\n```rust\nuse bevy_mouse_tracking_plugin::MousePosWorld;\n\nfn setup(mut commands: Commands) {\n    commands\n        .spawn(Camera2dBundle::default())\n        // Opt in to world-space mouse tracking.\n        // This will automatically opt into screen-space tracking.\n        .add(InitWorldTracking)\n        // ...\n}\n\n// Getting the world-space position using a query.\nfn dbg_world_single(mouse: Query\u003c\u0026MousePosWorld\u003e) {\n    // This will print the world-space position of the mouse on every frame.\n    eprintln!(\"{}\", *mouse.single());\n}\n\n// Getting it using the resource.\nfn dbg_world_res(mouse: Res\u003cMousePosWorld\u003e) {\n    eprintln!(\"{}\", *mouse);\n}\n```\n\nNote that this is only supported for two-dimensional, orthographic cameras,\nbut pull requests for 3D support are welcome!\n\nIf you do not specify a [`MainCamera`], the [`MousePos`] and [`MousePosWorld`]\nresources will still exist, but they will always be zero.\n\n## Mouse motion\n\nThis crate supports a resource that tracks mouse motion, via [`MouseMotionPlugin`].\nThe motion can be accessed from any system in a [`MouseMotion`] resource.\n\n[`Res`]: bevy::ecs::system::Res\n\n\u003c!-- cargo-rdme end --\u003e\n\n## Crate name\n\nAs a final aside: the name of this crate is intentionally verbose,\nsince it is very likely that this crate will eventually be made redundant by future updates to Bevy.  \nI recommend renaming the crate in your `Cargo.toml`:\n\n```toml\n[dependencies]\nmouse_tracking = { package = \"bevy_mouse_tracking_plugin\", version = \"...\" }\n```\n\nLicense: MIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoseph-gio%2Fbevy-mouse-tracking","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoseph-gio%2Fbevy-mouse-tracking","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoseph-gio%2Fbevy-mouse-tracking/lists"}