Add Hidden to CursorIcon and CursorSource enums

crates/bevy_render/src/view/window/cursor.rs

@@ -12,7 +12,7 @@ use bevy_ecs::{
 };
 use bevy_reflect::{std_traits::ReflectDefault, Reflect};
 use bevy_utils::{tracing::warn, HashSet};
-use bevy_window::{SystemCursorIcon, Window};
+use bevy_window::{SystemCursorIcon, Window, WindowCreated};
 use bevy_winit::{
     convert_system_cursor_icon, CursorSource, CustomCursorCache, CustomCursorCacheKey,
     PendingCursor,
@@ -27,7 +27,8 @@ impl Plugin for CursorPlugin {
     fn build(&self, app: &mut App) {
         app.register_type::<CursorIcon>()
             .init_resource::<CustomCursorCache>()
-            .add_systems(Last, update_cursors);
+            .add_systems(Last, update_cursors)
+            .observe(add_cursor_to_windows);
 
         app.observe(on_remove_cursor_icon);
     }
@@ -37,6 +38,28 @@ impl Plugin for CursorPlugin {
 #[derive(Component, Debug, Clone, Reflect, PartialEq, Eq)]
 #[reflect(Component, Debug, Default, PartialEq)]
 pub enum CursorIcon {
+    /// Makes the cursor hidden
+    ///
+    /// ## Platform-specific
+    ///
+    /// - **`Windows`**, **`X11`**, and **`Wayland`**: The cursor is hidden only when inside the window.
+    ///     To stop the cursor from leaving the window, change the [`bevy_window::Window`]
+    ///     entity's
+    ///     [`bevy_window::CursorOptions`] [`bevy_window::CursorGrabMode`] to
+    ///     [`bevy_window::CursorGrabMode::Locked`] or
+    ///     [`bevy_window::CursorGrabMode::Confined`]
+    /// - **`macOS`**: The cursor is hidden only when the window is focused.
+    /// - **`iOS`** and **`Android`** do not have cursors
+    ///
+    /// # Note for developers
+    ///
+    /// This was originally part of the [`bevy_window::CursorOptions`] component
+    /// as the `visible` field but it was moved out after adding Custom cursors. Before,
+    /// since we only had system cursors provided by the OS, this was heavily tied into
+    /// the implementation provided by [`bevy_winit`]. Now, you can think of this as part
+    /// of the `bevy_render` level, hence the drift from the original [`bevy_winit`]
+    /// coupled API.
+    Hidden,
     /// Custom cursor image.
     Custom(CustomCursor),
     /// System provided cursor icon.
@@ -98,6 +121,7 @@ pub fn update_cursors(
         }
 
         let cursor_source = match cursor.as_ref() {
+            CursorIcon::Hidden => CursorSource::Hidden,
             CursorIcon::Custom(CustomCursor::Image { handle, hotspot }) => {
                 let cache_key = match handle.id() {
                     AssetId::Index { index, .. } => {
@@ -196,3 +220,13 @@ fn image_to_rgba_pixels(image: &Image) -> Option<Vec<u8>> {
         _ => None,
     }
 }
+
+/// We need to add this here because we can't do it inside of [`bevy_winit`] due to issues
+/// with circular dependencies. Before we had custom cursors, these cursor related options
+/// would just be created automatically with the [`Window`] component, now however, this
+/// has to be made with the creation of the window so that users can set the visibility
+/// of it after the window is created.
+fn add_cursor_to_windows(ev_window_created: Trigger<WindowCreated>, mut commands: Commands) {
+    let WindowCreated { window: entity } = ev_window_created.event();
+    commands.entity(*entity).insert(CursorIcon::default());
+}

crates/bevy_window/src/window.rs

@@ -126,8 +126,7 @@ impl NormalizedWindowRef {
 )]
 #[reflect(Component, Default, Debug)]
 pub struct Window {
-    /// The cursor options of this window. Cursor icons are set with the `Cursor` component on the
-    /// window entity.
+    /// The cursor options of this window. See `bevy_render` on how to change the cursor to a custom or system one.
     pub cursor_options: CursorOptions,
     /// What presentation mode to give the window.
     pub present_mode: PresentMode,
@@ -549,16 +548,6 @@ impl WindowResizeConstraints {
 )]
 #[reflect(Debug, Default)]
 pub struct CursorOptions {
-    /// Whether the cursor is visible or not.
-    ///
-    /// ## Platform-specific
-    ///
-    /// - **`Windows`**, **`X11`**, and **`Wayland`**: The cursor is hidden only when inside the window.
-    ///     To stop the cursor from leaving the window, change [`CursorOptions::grab_mode`] to [`CursorGrabMode::Locked`] or [`CursorGrabMode::Confined`]
-    /// - **`macOS`**: The cursor is hidden only when the window is focused.
-    /// - **`iOS`** and **`Android`** do not have cursors
-    pub visible: bool,
-
     /// Whether or not the cursor is locked by or confined within the window.
     ///
     /// ## Platform-specific
@@ -581,7 +570,6 @@ pub struct CursorOptions {
 impl Default for CursorOptions {
     fn default() -> Self {
         CursorOptions {
-            visible: true,
             grab_mode: CursorGrabMode::None,
             hit_test: true,
         }

crates/bevy_winit/src/state.rs

@@ -154,6 +154,8 @@ pub struct CustomCursorCache(pub HashMap<CustomCursorCacheKey, winit::window::Cu
 /// A source for a cursor. Is created in `bevy_render` and consumed by the winit event loop.
 #[derive(Debug)]
 pub enum CursorSource {
+    /// A hidden cursor, used to hide the cursor in `winit_window`
+    Hidden,
     /// A custom cursor was identified to be cached, no reason to recreate it.
     CustomCached(CustomCursorCacheKey),
     /// A custom cursor was not cached, so it needs to be created by the winit event loop.
@@ -800,22 +802,28 @@ impl<T: Event> WinitAppRunnerState<T> {
                 continue;
             };
 
-            let final_cursor: winit::window::Cursor = match pending_cursor {
+            let final_cursor: Option<winit::window::Cursor> = match pending_cursor {
+                CursorSource::Hidden => None,
                 CursorSource::CustomCached(cache_key) => {
                     let Some(cached_cursor) = cursor_cache.0.get(&cache_key) else {
                         error!("Cursor should have been cached, but was not found");
                         continue;
                     };
-                    cached_cursor.clone().into()
+                    Some(cached_cursor.clone().into())
                 }
                 CursorSource::Custom((cache_key, cursor)) => {
                     let custom_cursor = event_loop.create_custom_cursor(cursor);
                     cursor_cache.0.insert(cache_key, custom_cursor.clone());
-                    custom_cursor.into()
+                    Some(custom_cursor.into())
                 }
-                CursorSource::System(system_cursor) => system_cursor.into(),
+                CursorSource::System(system_cursor) => Some(system_cursor.into()),
             };
-            winit_window.set_cursor(final_cursor);
+            if let Some(final_cursor) = final_cursor {
+                winit_window.set_cursor_visible(true);
+                winit_window.set_cursor(final_cursor);
+            } else {
+                winit_window.set_cursor_visible(false);
+            }
         }
     }
 }

crates/bevy_winit/src/system.rs

@@ -119,6 +119,7 @@ pub fn create_windows<F: QueryFilter + 'static>(
         }
 
         window_created_events.send(WindowCreated { window: entity });
+        commands.trigger(WindowCreated { window: entity });
     }
 }
 
@@ -367,10 +368,6 @@ pub(crate) fn changed_windows(
             crate::winit_windows::attempt_grab(winit_window, window.cursor_options.grab_mode);
         }
 
-        if window.cursor_options.visible != cache.window.cursor_options.visible {
-            winit_window.set_cursor_visible(window.cursor_options.visible);
-        }
-
         if window.cursor_options.hit_test != cache.window.cursor_options.hit_test {
             if let Err(err) = winit_window.set_cursor_hittest(window.cursor_options.hit_test) {
                 window.cursor_options.hit_test = cache.window.cursor_options.hit_test;

crates/bevy_winit/src/winit_windows.rs

@@ -262,8 +262,6 @@ impl WinitWindows {
             attempt_grab(&winit_window, window.cursor_options.grab_mode);
         }
 
-        winit_window.set_cursor_visible(window.cursor_options.visible);
-
         // Do not set the cursor hittest on window creation if it's false, as it will always fail on
         // some platforms and log an unfixable warning.
         if !window.cursor_options.hit_test {

examples/helpers/camera_controller.rs

@@ -3,11 +3,10 @@
 //! - Copy the code for the [`CameraControllerPlugin`] and add the plugin to your App.
 //! - Attach the [`CameraController`] component to an entity with a [`Camera3dBundle`].
 
-use bevy::{
-    input::mouse::{AccumulatedMouseMotion, AccumulatedMouseScroll, MouseScrollUnit},
-    prelude::*,
-    window::CursorGrabMode,
-};
+use bevy::input::mouse::{AccumulatedMouseMotion, AccumulatedMouseScroll, MouseScrollUnit};
+use bevy::prelude::*;
+use bevy::render::view::cursor::CursorIcon;
+use bevy::window::CursorGrabMode;
 use std::{f32::consts::*, fmt};
 
 pub struct CameraControllerPlugin;
@@ -102,7 +101,7 @@ Freecam Controls:
 #[allow(clippy::too_many_arguments)]
 fn run_camera_controller(
     time: Res<Time>,
-    mut windows: Query<&mut Window>,
+    mut windows_and_cursors: Query<(&mut Window, &mut CursorIcon)>,
     accumulated_mouse_motion: Res<AccumulatedMouseMotion>,
     accumulated_mouse_scroll: Res<AccumulatedMouseScroll>,
     mouse_button_input: Res<ButtonInput<MouseButton>>,
@@ -195,18 +194,18 @@ fn run_camera_controller(
         // Handle cursor grab
         if cursor_grab_change {
             if cursor_grab {
-                for mut window in &mut windows {
+                for (mut window, mut cursor_icon) in &mut windows_and_cursors {
                     if !window.focused {
                         continue;
                     }
 
                     window.cursor_options.grab_mode = CursorGrabMode::Locked;
-                    window.cursor_options.visible = false;
+                    *cursor_icon = CursorIcon::Hidden;
                 }
             } else {
-                for mut window in &mut windows {
+                for (mut window, mut cursor_icon) in &mut windows_and_cursors {
                     window.cursor_options.grab_mode = CursorGrabMode::None;
-                    window.cursor_options.visible = true;
+                    *cursor_icon = CursorIcon::default();
                 }
             }
         }

examples/input/mouse_grab.rs

@@ -1,6 +1,6 @@
 //! Demonstrates how to grab and hide the mouse cursor.
 
-use bevy::{prelude::*, window::CursorGrabMode};
+use bevy::{prelude::*, render::view::cursor::CursorIcon, window::CursorGrabMode};
 
 fn main() {
     App::new()
@@ -12,19 +12,22 @@ fn main() {
 // This system grabs the mouse when the left mouse button is pressed
 // and releases it when the escape key is pressed
 fn grab_mouse(
-    mut windows: Query<&mut Window>,
+    mut windows_and_cursors: Query<(&mut Window, &mut CursorIcon)>,
     mouse: Res<ButtonInput<MouseButton>>,
     key: Res<ButtonInput<KeyCode>>,
 ) {
-    let mut window = windows.single_mut();
+    // There are cases where we can have multiple windows and cursors,
+    // but not in this example. Keeping the naming convention since it
+    // exists in other examples
+    let (mut window, mut cursor) = windows_and_cursors.single_mut();
 
     if mouse.just_pressed(MouseButton::Left) {
-        window.cursor_options.visible = false;
+        *cursor = CursorIcon::Hidden;
         window.cursor_options.grab_mode = CursorGrabMode::Locked;
     }
 
     if key.just_pressed(KeyCode::Escape) {
-        window.cursor_options.visible = true;
+        *cursor = CursorIcon::default();
         window.cursor_options.grab_mode = CursorGrabMode::None;
     }
 }

examples/window/window_settings.rs

@@ -135,11 +135,21 @@ fn change_title(mut windows: Query<&mut Window>, time: Res<Time>) {
     );
 }
 
-fn toggle_cursor(mut windows: Query<&mut Window>, input: Res<ButtonInput<KeyCode>>) {
+fn toggle_cursor(
+    mut windows: Query<(&mut Window, &mut CursorIcon)>,
+    input: Res<ButtonInput<KeyCode>>,
+) {
     if input.just_pressed(KeyCode::Space) {
-        let mut window = windows.single_mut();
-
-        window.cursor_options.visible = !window.cursor_options.visible;
+        let (mut window, mut cursor_icon) = windows.single_mut();
+
+        // Usually cursors will get read from some sort of resource or a map
+        // right now  we just want to toggle the cursor, causing us to have to
+        // recreate the `CursorIcon` enum for the entity, see below in
+        // `cycle_cursor_icon` for an example on how to do this.
+        *cursor_icon = match *cursor_icon {
+            CursorIcon::Hidden => CursorIcon::default(),
+            _ => CursorIcon::Hidden,
+        };
         window.cursor_options.grab_mode = match window.cursor_options.grab_mode {
             CursorGrabMode::None => CursorGrabMode::Locked,
             CursorGrabMode::Locked | CursorGrabMode::Confined => CursorGrabMode::None,
@@ -166,6 +176,7 @@ struct CursorIcons(Vec<CursorIcon>);
 
 fn init_cursor_icons(mut commands: Commands, asset_server: Res<AssetServer>) {
     commands.insert_resource(CursorIcons(vec![
+        CursorIcon::Hidden,
         SystemCursorIcon::Default.into(),
         SystemCursorIcon::Pointer.into(),
         SystemCursorIcon::Wait.into(),