用途
本技能用于配置 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 路由)。