bevy-platform-desktop

用途

本技能用于配置 Bevy 引擎的桌面窗口，包括设置主窗口尺寸、呈现模式（present mode）、全屏模式以及关闭行为。当需要配置桌面窗口、窗口模式或关闭行为时加载本技能。Web 和移动端的约束由各自的技能处理。

主要能力

通过 WindowPlugin 配置主窗口，WindowPlugin 是 DefaultPlugins 的一部分。
使用 Window 组件定义窗口实体，PrimaryWindow 标记主窗口。
使用 WindowMode、PresentMode、WindowResolution、WindowPosition 等枚举或结构体控制窗口行为。
后端特性：bevy_winit 是 winit 窗口与输入后端，x11 和 wayland 是可选特性。
关闭行为：exit_on_primary_closed 和 exit_on_all_closed 是具名函数，WindowCloseRequested 是事件。

使用方式

在 Cargo.toml 中声明依赖：

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

[dependencies]
bevy = "0.20"

以下示例将主窗口设为 1280×720、垂直同步，并在该窗口关闭时退出应用：

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);
}

适用场景

配置 Bevy 桌面应用的主窗口尺寸、标题与呈现模式。
实现窗口化与无边框全屏之间的运行时切换。
设置窗口关闭时的应用退出条件。
从 Godot 迁移到 Bevy 时，将窗口相关概念映射到 Bevy ECS 惯用法。

限制与约束

目标版本为 Bevy 0.20+。
不要在文档 URL 中固定 /0.20.0/，链接应保持指向最新版本。
不要从两个无序系统可变查询同一组件；调度器默认并行运行系统，除非用 .chain() 排序。
不要在本技能中引入物理、导航、网络或 XR 相关 crate。
不要使用 Godot 的 DisplayServer 或窗口项目设置名称，也不要使用 Godot 类型。
不要编造 API 或使用未命名的第三方 crate 作为解决方案。
本技能仅命名有文档记录的 Bevy crate 和模块。

技能介绍

用途

主要能力

使用方式

适用场景

限制与约束

相关技能