SuperAPI AI 工具集

bevy-platform-desktop

编程与开发

查看项目

更新于 10-16 10:37

技能介绍

用途

本技能用于配置 Bevy 引擎的桌面窗口,包括设置主窗口尺寸、呈现模式、全屏模式以及关闭行为。当需要调整桌面窗口、窗口模式或关闭逻辑时加载本技能;Web 与移动端的约束由各自技能负责。

主要能力

  • 窗口接口:bevy::window 是与平台无关的窗口接口,WindowPlugin 属于 DefaultPlugins 的一部分。
  • 组件:Window 是窗口实体的定义组件,PrimaryWindow 标记主窗口。
  • 模式相关类型:WindowMode、PresentMode、WindowResolution、WindowPosition 为枚举或结构体。
  • 后端特性:bevy_winit 是 winit 窗口与输入后端,x11 和 wayland 是特性(feature)。
  • 关闭行为:exit_on_primary_closed 与 exit_on_all_closed 是具名函数,WindowCloseRequested 是事件。

使用方式

在应用运行前通过 WindowPlugin 配置主窗口。以下示例创建一个 1280x720、垂直同步、主窗口关闭即退出应用的主窗口:

[package]
name = "desktop"
version = "0.1.0"
edition = "2021"

[dependencies]
bevy = "0.20"
use bevy::window::ExitCondition;
use bevy::window::PresentMode;
use bevy::window::WindowMode;
use bevy::window::WindowResolution;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins.set(WindowPlugin {
            primary_window: Some(Window {
                title: "Desktop".into(),
                resolution: WindowResolution::new(1280, 720),
                present_mode: PresentMode::AutoVsync,
                mode: WindowMode::Windowed,
                ..default()
            }),
            exit_condition: ExitCondition::OnPrimaryClosed,
            close_when_requested: true,
            ..default()
        }))
        .run();
}

F11 可在当前显示器上于窗口化与无边框全屏之间切换主窗口:

use bevy::window::MonitorSelection;
use bevy::window::PrimaryWindow;
use bevy::window::WindowMode;

fn toggle_fullscreen(
    keys: Res<ButtonInput<KeyCode>>,
    mut windows: Query<&mut Window, With<PrimaryWindow>>,
) {
    if !keys.just_pressed(KeyCode::F11) {
        return;
    }
    let Ok(mut window) = windows.single_mut() else {
        return;
    };
    window.mode = if window.mode == WindowMode::Windowed {
        WindowMode::BorderlessFullscreen(MonitorSelection::Current)
    } else {
        WindowMode::Windowed
    };
}

另一个系统读取实时分辨率。它不写入 Window,因此可与切换系统并行运行,无需 .chain():

use bevy::window::PrimaryWindow;

fn log_resolution(windows: Query<&Window, With<PrimaryWindow>>) {
    let Ok(window) = windows.single() else {
        return;
    };
    let width = window.resolution.width();
    let height = window.resolution.height();
    let _ = (width, height);
}

从 Godot 迁移对照

Godot 概念 Bevy 惯用法
窗口尺寸 主 Window 上的 WindowResolution
全屏 WindowMode::BorderlessFullscreen
关闭即退出 WindowPlugin 上的 ExitCondition::OnPrimaryClosed

适用范围

x11 和 wayland 是 bevy 的特性。主窗口在应用运行前于 WindowPlugin 上配置。运行时模式变更写入标记为 PrimaryWindow 的 Window 组件。

专家知识要点

目标版本为 Bevy 0.20+。核心 ECS 类型包括 Component、Resource、Query、Commands、Startup、Update、Fixed / FixedMain(bevy::time)、.chain()、Plugin、DefaultPlugins、MinimalPlugins。消息与观察者属于独立归属槽位,其 API 参见 bevy-events-messaging。除非用 .chain() 对冲突系统排序,否则系统并行运行。

状态归属:单个实体的数据由 Component 承载,通过 Query 由单个系统修改,运行于 Update 或 FixedMain;全应用单一值由 Resource 承载,Startup 插入后由读取它的调度使用;生成由 Commands 在生成系统中完成;必须避免竞态的顺序用 .chain() 限定;插件边界由 Plugin 的 build 注册系统与资源。借用规则:两个系统若都可变查询同一组件,必须排序(.chain())或拆分使只有一个写入;无关系统保持并行。

决策表:需要逐实体数据用 Component + Query,不要用 Godot 节点脚本;需要应用级配置或时钟用 Resource,不要把值复制到每个实体;需要稳定模拟步长用 FixedMain 与 Fixed 时钟,不要把模拟绑定到原始帧 Update;启动生成用 Startup 中的 Commands,不要从渲染系统生成;需要非共享状态的跨系统通知使用 bevy-events-messaging 中的消息或观察者槽位,不要在本文件中新造事件类型;需要文档集之外的 API 时先查官方文档,不要使用虚构的 crate 或 API。

禁止事项

  • 不要在文档 URL 中固定 /0.20.0/,链接应保持在 latest,0.20 目标只在正文中说明一次。
  • 不要从两个无序系统可变查询同一组件,因为除非用 .chain() 排序,调度会并行运行系统。
  • 不要在此虚构物理、导航、网络或 XR crate,本技能只命名有文档的 Bevy crate 与模块。
  • 不要使用 Godot 的 DisplayServer 或窗口项目设置名称,Bevy 代码应保持惯用 ECS 并只使用有文档的 Bevy API。
  • 不要在 Bevy 代码中使用 Godot 类型。
  • 不要使用虚构 API 或未具名第三方 crate 作为选定方案。

参考资料

官方文档:bevy crate(API 参考与 Cargo 特性列表);Assets(官方资源目录,未选择第三方 crate);Examples(latest 分支上的示例树);ECS(Component、系统、Query、Startup、Update 与 .chain());Plugins(Plugin、DefaultPlugins、MinimalPlugins 与 add_plugins);bevy::window(Window、WindowPlugin、PrimaryWindow、WindowMode)。

相关技能:前置技能为 bevy-master(枢纽与调度)与 bevy-ecs-composition(组件与系统);互补技能为 bevy-platform-web(Wasm 限制)、bevy-input-handling(指针与键盘)、godot-platform-desktop(对应的 Godot 技能);下游消费者暂无;主技能为 bevy-master(Bevy 路由)。