1. 项目概述与核心价值

在开发基于 Bevy 游戏引擎的交互式应用时，无论是 2D 游戏、3D 编辑器还是数据可视化工具，一个高频且基础的需求就是： 精确地知道鼠标光标在游戏世界中的位置 。这听起来简单，但当你真正动手实现时，会发现它涉及窗口坐标、视口变换、相机投影矩阵、视锥体裁剪等一系列底层计算。新手开发者往往会在这里卡壳，要么写出的代码只在特定相机设置下有效，要么性能不佳，要么无法优雅地处理多窗口、多相机切换的场景。

bevy_cursor 这个插件就是为了解决这个痛点而生的。它本质上是一个 光标信息追踪与坐标转换的辅助工具 ，帮你把窗口像素坐标到世界坐标（对于 2D）或世界空间射线（对于 3D）的复杂计算过程封装起来，提供一个干净、统一、高性能的 API。你不用再关心 Camera 的投影类型是正交还是透视，也不用手动去写射线与近平面相交的数学公式，更不用担心多相机并存时该用哪个。你只需要关心：“我的光标现在指着的那个点，在世界里是哪里？” 或者 “从相机出发，穿过光标的那条射线是什么？”，然后直接从 CursorLocation 资源里读取答案。

它的核心价值在于 “开箱即用” 和 “场景无感” 。你添加插件，它就开始工作；你切换相机，它自动更新计算结果；你创建新窗口，它也能分别追踪。这极大地简化了交互逻辑的开发，让你能更专注于游戏玩法或应用逻辑本身，而不是底层输入处理的细枝末节。

2. 插件核心设计与思路拆解

2.1 设计哲学：事件驱动与资源抽象

bevy_cursor 的设计遵循了 Bevy ECS（实体-组件-系统）架构的核心思想。它没有采用传统的、每帧轮询输入设备的方式，而是巧妙地利用了 Bevy 的事件系统 ( EventReader ) 和资源 ( Res ) 机制。

  1. 事件监听 ：插件内部会监听 CursorMoved 、 WindowResized 、 WindowCreated 、 WindowClosed 等与光标和窗口相关的事件。任何导致光标位置或窗口状态变化的操作，都会触发插件内部的更新逻辑。
  2. 资源封装 ：它将计算得到的光标世界位置、所在窗口、关联相机等信息，封装进一个名为 CursorLocation 的资源中。这个资源对用户是只读的 ( Res<CursorLocation> )，你可以在任何需要的地方通过系统参数访问它，就像访问 Time 或 Assets 资源一样自然。
  3. 按需计算 ：插件并非每帧都进行所有计算。它内部维护了状态，只有当相关事件（如光标移动、窗口缩放、相机变换更新）发生时，才会重新计算光标对应的世界信息。这种惰性更新策略对性能非常友好。

这种设计的好处是 解耦 和 高效 。你的业务系统不需要知道光标信息是如何来的，只需要声明依赖 CursorLocation 资源。Bevy 的调度器会确保 bevy_cursor 的更新系统在依赖它的系统之前运行，保证了数据的时效性。

2.2 核心数据结构解析

理解插件提供的几个核心数据结构，是正确使用它的关键。

CursorLocation (资源) 这是你主要交互的对象。它提供了几个核心方法：

  • position() -> Option<Vec2> : 获取光标在 世界坐标系 中的 2D 位置。这是最常用的功能。返回 None 表示光标不在任何由该插件追踪的窗口内，或者没有找到有效的相机。
  • window() -> Option<Entity> : 获取光标当前所在的窗口实体。这在多窗口应用中非常有用，你可以通过这个实体获取窗口的详细属性。
  • camera() -> Option<Entity> : 获取用于计算世界位置的相机实体。插件会自动选择“最合适”的相机（通常是与光标所在窗口关联、且启用的主相机）。

TrackCursorPlugin (插件) 这是插件的主体。通过 app.add_plugins(TrackCursorPlugin) 来启用。它会向你的 App 中注册必要的系统和资源。

CursorRay (组件，3D 特性) 当启用 3d 特性时，插件会为每个被追踪的相机实体附加一个 CursorRay 组件。这个组件包含一个 Ray3d 结构，描述了从相机原点出发、穿过光标屏幕位置的一条无限射线。你可以通过查询 ( Query<&CursorRay, With<Camera>> ) 来获取特定相机对应的光标射线，用于 3D 场景中的物体拾取、地形高度检测等。

2.3 特性（Features）选型背后的考量

插件通过 Cargo features 来区分 2D 和 3D 功能，这背后有充分的工程考量：

  • 2d 特性 ：专注于计算一个精确的 Vec2 世界坐标。这对于 UI 点击判断、2D 精灵拖拽、瓦片地图选择等场景是完美契合的。实现上，它需要处理相机的正交投影变换和可能的缩放、平移。
  • 3d 特性 ：在 3D 空间中，光标对应的是一个方向，而非一个确定的点。因此它提供一条射线 ( Ray3d )。这条射线与场景中物体的交点，才是你需要的“世界位置”。这用于实现 3D 物体拾取、第一人称射击的准星、3D 场景中的拖拽等。实现上，它涉及将屏幕坐标反投影到相机视锥体的近平面和远平面，从而构造射线。

为什么分开？

  1. 编译优化 ：如果你的项目只是 2D 游戏，启用 3d 特性会引入不必要的数学计算（如射线构造、矩阵求逆等），增加编译后的二进制大小和运行时开销。分开特性允许你只编译你需要的部分。
  2. 概念清晰 ：2D 坐标和 3D 射线是不同的概念，分开特性迫使开发者明确自己项目的需求，选择正确的工具，避免误用。
  3. 依赖最小化 ：保持核心插件轻量，让用户按需添加功能，符合 Rust 和 Bevy 社区的“最小依赖”哲学。

在实际项目中，你可以根据需要在 Cargo.toml 中这样启用：

[dependencies.bevy_cursor]
version = "0.7"
features = ["2d", "3d"] # 如果你同时需要 2D 和 3D 功能
# 或者只启用一个
# features = ["2d"]
# features = ["3d"]

3. 核心细节解析与实操要点

3.1 坐标系统的转换链

要理解 bevy_cursor 在做什么，必须厘清坐标转换的完整链条。这是很多问题的根源。

  1. 物理像素坐标 (Physical Pixel Coordinates) ：这是光标的原始位置，来自操作系统。例如 (640, 480) 。它的原点 (0, 0) 通常在屏幕的左上角。
  2. 窗口逻辑坐标 (Window Logical Coordinates) ：Bevy 的 CursorMoved 事件提供的是这个坐标。它考虑了窗口的缩放因子 ( Window::scale_factor )。在高DPI屏幕上，一个逻辑点可能对应多个物理像素。这是插件处理的起点。
  3. 标准化设备坐标 (Normalized Device Coordinates, NDC) ：范围在 [-1, 1] 之间， (-1, -1) 是视口的左下角， (1, 1) 是右上角。这是图形API（如wgpu）使用的坐标系。插件需要将窗口逻辑坐标转换到 NDC。
  4. 世界坐标 (World Coordinates) ：这是我们最终想要的结果。通过相机的视图投影矩阵的逆矩阵，将 NDC 坐标转换到游戏世界空间。

bevy_cursor 的 2d 特性，其核心就是稳健地完成从 步骤2到步骤4 的转换。它内部会处理相机是 Camera2d 还是 OrthographicProjection ，以及相机的缩放 ( ScalingMode )、偏移 ( Transform ) 等问题。

注意 ：一个常见的误解是认为 CursorLocation::position() 返回的是屏幕像素坐标。 它不是 。它返回的是 世界坐标 。如果你需要像素坐标，应该直接监听 CursorMoved 事件。

3.2 多相机与相机选择策略

当场景中存在多个相机时（比如一个主游戏相机，一个 UI 相机，或者一个画中画小地图相机）， bevy_cursor 如何决定使用哪个相机来进行计算？

这是插件的一个智能之处。它内部有一个相机选择策略，通常遵循以下优先级：

  1. 与光标所在窗口关联的相机 ：光标在哪个窗口，就优先使用渲染到那个窗口的相机。
  2. 启用的、且包含光标位置的相机 ：相机组件 ( Camera ) 必须启用 ( is_active: true )，并且光标位置必须在该相机的视口 ( viewport ) 范围内。
  3. 渲染顺序 ：对于渲染到同一窗口的多个相机，可能会参考 Camera::order 。order 值更高的相机通常渲染在上层，因此可能被优先选中用于光标计算（这对于 UI 相机覆盖游戏相机的场景很关键）。

实操要点 ：

  • 明确主相机 ：对于大多数单相机应用，确保你的主相机拥有 Camera2d 或 Camera3d 组件，并且被正确标记为启用状态。
  • 处理 UI 相机 ：如果你的 UI 使用了一个独立的、order 值更高的相机（例如用于渲染到特定的 RenderTarget），并且你希望 UI 元素能阻挡后面的游戏对象交互，那么 bevy_cursor 自动选择 UI 相机进行计算是符合预期的。如果你需要穿透 UI 与游戏世界交互，你可能需要更精细的控制，这时可以考虑禁用 UI 相机的光标追踪（可能需要修改插件逻辑或使用自定义系统）。
  • 调试相机选择 ：如果不确定当前生效的是哪个相机，可以打印 CursorLocation::camera() 返回的实体 ID，然后在系统中查询该实体的 Name 组件或自定义标记来确认。

3.3 2D 与 3D 模式下的使用差异

2D 模式 ( features = ["2d"] ) 这是最直接的模式。 CursorLocation::position() 返回的 Vec2 可以直接用于与具有 Transform （包含 translation 的 Vec3 ，但 z 轴通常为 0）的 2D 精灵进行碰撞或距离检测。

fn check_click_on_sprite(
    cursor: Res<CursorLocation>,
    sprites: Query<(&Transform, &Sprite, &Interaction)>, // Interaction 可能是自定义组件
) {
    if let Some(cursor_pos) = cursor.position() {
        for (transform, _sprite, mut interaction) in &mut sprites {
            // 简单的矩形区域检测（假设精灵是轴对齐的）
            let sprite_size = Vec2::new(100.0, 100.0); // 精灵大小
            let half_size = sprite_size / 2.0;
            let sprite_center = transform.translation.truncate(); // 取 xy

            if cursor_pos.x > sprite_center.x - half_size.x
                && cursor_pos.x < sprite_center.x + half_size.x
                && cursor_pos.y > sprite_center.y - half_size.y
                && cursor_pos.y < sprite_center.y + half_size.y
            {
                *interaction = Interaction::Hovered;
                // 处理点击逻辑...
            }
        }
    }
}

3D 模式 ( features = ["3d"] ) 在 3D 中，你得到的是射线，需要额外的步骤来获取“点”。

fn cast_ray_for_picking(
    // 查询附加在相机上的 CursorRay 组件
    camera_query: Query<(&GlobalTransform, &CursorRay), With<Camera3d>>,
    // 查询场景中可被拾取的物体，需要有碰撞体或包围盒
    pickable_query: Query<(Entity, &GlobalTransform, &Mesh)>,
) {
    for (cam_transform, cursor_ray) in &camera_query {
        // cursor_ray.ray 包含了起点(origin)和方向(direction)
        let ray = &cursor_ray.ray;

        // 现在你需要进行射线与物体的相交测试。
        // Bevy 本身没有内置的复杂物理碰撞检测，你需要借助其他 crate，例如：
        // - `bevy_rapier3d`：功能完整的物理引擎，支持射线投射。
        // - `bevy_prototype_lyon`：2D 形状，不适用于此。
        // - 手动实现简单的 AABB（轴对齐包围盒）检测。

        // 示例：简单的 AABB 检测（假设物体有一个 Aabb 组件）
        // for (entity, transform, _mesh) in &pickable_query {
        //     let aabb = compute_aabb(...); // 你需要计算或存储物体的 AABB
        //     if let Some(intersection) = ray.intersects_aabb(aabb) {
        //         println!("Picked entity: {:?} at distance {}", entity, intersection);
        //     }
        // }
    }
}

重要提示 ： bevy_cursor 的 3d 特性 只负责生成射线 ，不负责射线与场景物体的相交检测。相交检测是一个更复杂的主题，通常需要物理引擎或自定义的几何计算。你需要将 CursorRay 提供给像 bevy_rapier3d 这样的物理引擎的射线投射接口。

4. 完整集成与进阶使用指南

4.1 基础集成步骤

将 bevy_cursor 集成到你的项目是一个标准流程：

  1. 添加依赖 ：在 Cargo.toml 的 [dependencies] 部分添加。

    [dependencies]
bevy = "0.17" # 请根据插件兼容表选择版本
bevy_cursor = { version = "0.7", features = ["2d"] }

  2. 导入与添加插件 ：在你的 main.rs 或主模块中，导入插件并添加到 App 中。

    use bevy::prelude::*;
use bevy_cursor::prelude::*; // 导入常用项

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(TrackCursorPlugin) // 添加光标追踪插件
        // ... 添加你的其他插件和系统
        .run();
}

  3. 在系统中使用 ：在任何需要光标位置的系统中，通过 Res<CursorLocation> 参数来访问。

    fn my_system(cursor: Res<CursorLocation>) {
    match cursor.position() {
        Some(pos) => {
            // 使用世界坐标 pos (Vec2) 做你想做的事
            // 例如，移动一个物体到光标位置（忽略z轴）
            // commands.entity(my_entity).insert(Transform::from_xyz(pos.x, pos.y, 0.0));
        }
        None => {
            // 光标不在窗口内，进行相应处理（如隐藏提示）
        }
    }
}

4.2 处理多窗口场景

bevy_cursor 天生支持多窗口。 CursorLocation 资源会追踪光标当前位于哪个窗口。你可以通过 cursor.window() 获取窗口实体。

一个常见的多窗口用例是编辑器：一个主视图窗口，一个资源浏览器窗口。你可能希望只在主视图窗口中进行 3D 物体的拖拽。

fn drag_object_in_main_window(
    cursor: Res<CursorLocation>,
    windows: Query<(Entity, &Window)>,
    mut selected_object: Query<&mut Transform, With<Selected>>,
) {
    let main_window_entity = // ... 你之前存储的主窗口实体；

    // 只有当光标在主窗口内，才执行拖拽逻辑
    if let Some(current_window) = cursor.window() {
        if current_window == main_window_entity {
            if let Some(cursor_world_pos) = cursor.position() {
                for mut transform in &mut selected_object {
                    transform.translation.x = cursor_world_pos.x;
                    transform.translation.y = cursor_world_pos.y;
                }
            }
        }
    }
}

4.3 与 Bevy 官方交互系统协同工作

Bevy 0.11 之后引入了官方的 bevy::ui 和 Interaction 组件来处理 UI 的点击、悬停状态。 bevy_cursor 与它们是互补关系，而非替代。

  • bevy::ui 和 Interaction ：用于处理 UI节点 （按钮、面板等）的交互。它基于节点的层级、样式和变换自动计算点击区域，并更新 Interaction 组件（ Clicked , Hovered , None ）。这适用于定义良好的 UI 系统。
  • bevy_cursor ：用于处理 游戏世界 中的交互。例如，点击一个 3D 模型、在 2D 地图上选择单位、在画布上自由绘制。它提供的是原始的世界坐标或射线，你需要自己实现碰撞检测逻辑。

它们可以同时使用 ：你的 UI 按钮通过 Interaction 工作，而背景游戏世界的点击通过 bevy_cursor 计算的世界坐标来检测。Bevy 的事件和调度系统会妥善处理两者的更新顺序。

4.4 性能考量与最佳实践

bevy_cursor 本身非常轻量，其计算成本主要在于矩阵求逆（从屏幕坐标反算世界坐标）。在绝大多数应用中，这都不是性能瓶颈。但遵循一些最佳实践总是好的：

  1. 按需查询 ：只在真正需要光标位置的系统中添加 Res<CursorLocation> 参数。Bevy 的调度器会优化系统执行。
  2. 避免每帧频繁创建临时对象 ：例如，如果你在使用 CursorRay 进行物理射线检测，尽量将射线检测的逻辑放在一个集中的系统里，而不是每个需要检测的物体都单独跑一遍。
  3. 对于静态 UI ：如果你的 UI 位置固定，且交互逻辑简单，使用 Bevy 官方的 Interaction 系统可能比用 bevy_cursor 手动计算碰撞更高效、更简单。
  4. 调试性能 ：如果你怀疑光标相关系统有性能问题，可以使用 Bevy 的 LogPlugin 或第三方性能分析工具来查看系统耗时。

5. 常见问题、排查技巧与实战心得

5.1 问题排查速查表

问题现象 可能原因 解决方案
cursor.position() 始终返回 None 1. 没有添加 TrackCursorPlugin 。
2. 场景中没有 启用 的、且渲染到光标所在窗口的相机。
3. 光标确实不在应用程序窗口内。		 1. 检查 App 构建器是否添加了插件。
2. 确保至少有一个 Camera2d 或 Camera3d 实体，且其 Camera 组件的 is_active 为 true 。
3. 打印 cursor.window() 检查窗口实体是否存在。
返回的世界坐标不正确（偏移、缩放不对） 1. 相机的投影设置（如 OrthographicProjection 的 scale 、 near/far ）或 Transform 异常。
2. 窗口的缩放因子 ( scale_factor ) 影响。
3. 相机视口 ( viewport ) 设置导致坐标映射错误。		 1. 检查相机的 Projection 组件和 GlobalTransform 。对于 2D，确保 Camera2d 的缩放符合预期。
2. 确认你理解“窗口逻辑坐标”和“物理像素坐标”的区别。 bevy_cursor 使用逻辑坐标。
3. 如果自定义了视口，确保计算时考虑了视口偏移和大小。
在 3D 模式下， CursorRay 方向奇怪或起点不对 1. 相机是 2D 相机，但启用了 3d 特性。
2. 相机的近平面 ( near ) 值设置得过大或过小。
3. 相机的变换矩阵包含非常规的旋转或缩放。		 1. 确保为 3D 场景使用 Camera3d 组件和 PerspectiveProjection 或 OrthographicProjection 。
2. 近平面值不宜为 0 或负数，一个典型值是 0.1 。
3. 检查相机的 GlobalTransform ，确保其符合 3D 相机惯例（通常看向 -Z 方向）。
多相机时，光标计算似乎用了“错误”的相机 1. 多个相机渲染到同一窗口，且都启用。
2. 相机的渲染顺序 ( order ) 或视口 ( viewport ) 影响了选择。		 1. 这是设计行为。插件会选择它认为“最合适”的相机（通常是 order 最高、且包含光标的）。
2. 如果这不是你想要的，可以考虑：禁用不需要追踪的相机的光标计算（可能需要修改插件或使用自定义逻辑），或者使用 cursor.camera() 判断当前是哪个相机，并据此调整你的交互逻辑。
集成物理引擎（如 Rapier）时，射线检测不命中 1. CursorRay 的坐标系与物理引擎期望的坐标系不一致。
2. 物理碰撞体没有正确附加到实体上，或者形状/大小不匹配。
3. 射线检测的过滤设置（如碰撞组、查询过滤器）排除了目标物体。		 1. 这是最常见的坑！ 确保 CursorRay 的起点和方向是在 世界空间 。物理引擎的射线检测接口通常也要求世界空间的射线。直接使用 cursor_ray.ray.origin 和 cursor_ray.ray.direction 即可，它们已经是世界空间的了。
2. 调试时，可以可视化物理碰撞体，确保其与渲染网格匹配。
3. 检查物理引擎射线检测函数的参数，确保你设置了正确的查询过滤器。

5.2 实战心得与技巧

  1. “光标不在窗口内”的处理 ： cursor.position() 返回 None 不一定是个错误。当用户把鼠标移到窗口外时，这是正常行为。你的 UI 应该优雅地处理这种情况，比如隐藏跟随光标的工具提示、取消拖拽操作等。一个好的模式是，在光标离开窗口时，将一个 CursorOutsideWindow 事件发送到你的业务系统。

  2. 坐标转换的“最后一公里” ： bevy_cursor 给了你世界坐标，但你的游戏逻辑可能需要的是其他坐标。例如：

    • 瓦片地图坐标 ：你需要将世界坐标除以瓦片大小，再取整。
    let tile_size = Vec2::new(32.0, 32.0);
if let Some(world_pos) = cursor.position() {
    let tile_x = (world_pos.x / tile_size.x).floor() as i32;
    let tile_y = (world_pos.y / tile_size.y).floor() as i32;
    // 现在你有了瓦片坐标 (tile_x, tile_y)
}
    • 相对于某个实体的局部坐标 ：用世界坐标减去该实体的全局变换位置。
    if let (Some(cursor_pos), Ok(entity_transform)) = (cursor.position(), transforms.get(entity)) {
    let local_pos = cursor_pos - entity_transform.translation.truncate();
}

  3. 自定义光标图标 ： bevy_cursor 只负责计算位置，不负责渲染光标图形。要改变光标图标，你需要使用 Bevy 的 Window 资源。

    fn change_cursor_icon(
    windows: Query<&mut Window>,
    cursor: Res<CursorLocation>,
    asset_server: Res<AssetServer>,
) {
    if cursor.position().is_some() {
        for mut window in &mut windows {
            // 方式1：使用系统光标
            window.cursor.icon = CursorIcon::Crosshair;
            // 方式2：使用自定义纹理（更复杂，需要处理渲染）
            // 这通常需要你创建一个带有 Sprite 的实体，并每帧用 cursor.position() 更新其 Transform。
        }
    }
}

  4. 拖拽操作的实现模式 ：实现一个平滑的拖拽功能，通常需要结合 Input<MouseButton> 和 CursorLocation 。

    fn drag_and_drop(
    mouse_button: Res<Input<MouseButton>>,
    cursor: Res<CursorLocation>,
    mut drag_state: ResMut<DragState>, // 自定义资源，存储拖拽状态
    mut transforms: Query<&mut Transform, With<Draggable>>,
) {
    if mouse_button.just_pressed(MouseButton::Left) {
        // 1. 点击时，检测是否点中了可拖拽物体
        if let Some(pos) = cursor.position() {
            if let Some(hit_entity) = pick_object_at(pos) { // 自定义的拾取函数
                drag_state.start_drag(hit_entity, pos);
            }
        }
    }

    if mouse_button.pressed(MouseButton::Left) && drag_state.is_dragging() {
        // 2. 按住拖动时，更新物体位置
        if let Some(current_pos) = cursor.position() {
            if let Ok(mut transform) = transforms.get_mut(drag_state.dragged_entity) {
                transform.translation.x = current_pos.x;
                transform.translation.y = current_pos.y;
            }
        }
    }

    if mouse_button.just_released(MouseButton::Left) {
        // 3. 释放时，结束拖拽
        drag_state.stop_drag();
    }
}

  5. 插件版本与 Bevy 版本的严格对应 ：务必查看插件仓库中的兼容性表格。Bevy 版本间常有 breaking changes，用错版本会导致编译错误或运行时异常。如果你在升级 Bevy， bevy_cursor 通常也需要同步升级到对应的版本。

bevy_cursor 是一个典型的小而美的工具类插件，它精准地解决了一个具体问题，并且解决得足够好。在我自己的几个 Bevy 项目中，从简单的 2D 原型到稍复杂的 3D 编辑器，它都是输入处理层不可或缺的一环。它的存在让我几乎忘记了还有“将屏幕坐标转换为世界坐标”这回事，而这正是优秀基础设施该有的样子——安静、可靠、让你专注于创造。如果你正在用 Bevy 开发任何需要鼠标交互的东西，我强烈建议你把它加入你的工具箱。

Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

DeepSeek-V4 RAG 分块策略优化：512 vs 1024 token 的实测边界与工程取舍

avatar DeepSeek技术社区
cover

企业知识库问答中的权限迷宫：如何用 DeepSeek 实现文档级 ACL 下沉与安全召回

avatar DeepSeek技术社区
cover

RAG 文档预处理：为什么 90% 的失败案例源于切分策略不当

avatar DeepSeek技术社区