用途
当同一套应用需要在浏览器中运行时使用本技能。资料未说明打包流水线(packaging pipelines)的具体内容。
主要能力
- Cargo 特性:
web(浏览器 API,仅 wasm32)、webgl2(为让 Wasm 使用 WebGL2 而设的限制)、webgpu(覆盖 webgl2;仅 Wasm 配合 WebGPU)。 - 资源说明:
http与https特性启用远程资源下载,并会就安全性发出警告。web_asset_cache会缓存下载内容,且当前从不失效(never invalidates entries)。 - 剪贴板:
clipboard_image声明在 WASM 上不受支持。 - 窗口: 同一个
Window组件用于描述 canvas。在主窗口上设置canvas、fit_canvas_to_parent和resolution。
特性选择
| 需求 | Bevy 路径 |
|---|---|
| 浏览器构建 | wasm32-unknown-unknown。在 Cargo 中启用 webgl2 或 webgpu;这两个特性互相冲突。 |
| 图形后端 | webgl2 或 webgpu。启用其中一个。 |
| 远程资源 | http 或 https。web_asset_cache 会存储下载内容且不会使其失效。 |
范围
- canvas 就是一个
Window。将canvas指向某个 DOM id,并开启fit_canvas_to_parent,使 canvas 跟随其父元素。 webgl2与webgpu是 Cargo 特性,不是组件。针对 wasm32 目标启用其中之一。clipboard_image在 wasm 上不可用。文本剪贴板仍使用默认特性已包含的窗口 API。
使用方式
在 Cargo 中启用图形后端特性:
[dependencies]
bevy = { version = "0.20", features = ["webgl2"] }
在 canvas 元素上打开主窗口,并使其尺寸跟随该元素的父元素:
use bevy::window::{PrimaryWindow, WindowResolution};
fn main() {
App::new()
.add_plugins(DefaultPlugins.set(WindowPlugin {
primary_window: Some(Window {
title: "Browser".into(),
canvas: Some("#bevy".into()),
fit_canvas_to_parent: true,
prevent_default_event_handling: true,
resolution: WindowResolution::new(1280, 720),
..default()
}),
..default()
}))
.run();
}
运行中的应用仍可重新指定 canvas 与逻辑分辨率:
use bevy::window::PrimaryWindow;
fn bind_canvas(mut windows: Query<&mut Window, With<PrimaryWindow>>) {
let Ok(mut window) = windows.single_mut() else {
return;
};
if window.canvas.is_none() {
window.canvas = Some("#bevy".to_string());
}
window.fit_canvas_to_parent = true;
window.resolution.set(1280.0, 720.0);
}
加载相对资源路径。远程 http URL 需要 http 或 https 特性;此路径保持在打包器所提供服务的资源文件夹内:
fn spawn_sprite(mut commands: Commands, asset_server: Res<AssetServer>) {
let image = asset_server.load("sprites/player.png");
commands.spawn((Camera2d, Sprite::from_image(image)));
}
专家知识要点
目标:Bevy 0.20+。
核心 ECS 类型:Component、Resource、Query、Commands、Startup、Update、Fixed / FixedMain(bevy::time)、.chain()、Plugin、DefaultPlugins、MinimalPlugins。消息与观察者(messages and observers)是一个归属槽位,其 API 参见 bevy-events-messaging。除非用 .chain() 对冲突的系统排序,否则系统并行运行。
状态归属
| 部分 | 归属 | 谁可修改 | 调度 |
|---|---|---|---|
| 单个实体上的数据 | Component |
一个系统通过 Query |
Update 或 FixedMain |
| 整个应用的一个值 | Resource |
一个系统 | Startup 插入,随后由读取它的调度 |
| 生成 | Commands |
执行生成的系统 | 初始世界用 Startup;运行时生成用后续调度 |
| 不可竞态的顺序 | .chain() |
仅被链式连接的系统 | 同一调度 |
| 插件边界 | Plugin |
build 注册系统与资源 |
应用运行之前 |
借用规则:两个都可变查询同一组件的系统必须排序(.chain()),或拆分使只有一个写入。无关系统保持并行。这是 ECS 页面规则,并非对某个系统集 API 的猜测。
决策
| 如果你需要 | 这样做 | 不要 |
|---|---|---|
| 每实体数据 | Component + Query |
存储在世界之外的字段 |
| 应用级配置或时钟 | Resource |
把值复制到每个实体上 |
| 稳定的模拟步长 | FixedMain 与 Fixed 时钟 |
把模拟绑定到原始帧 Update |
| 启动时生成 | 在 Startup 中使用 Commands |
从渲染系统生成 |
| 浏览器 canvas | Window.canvas 与 fit_canvas_to_parent |
只有标题、没有 canvas id 的窗口 |
| 图形后端 | webgl2 或 webgpu 中恰好一个 |
同时启用两个 Cargo 特性 |
| 非共享状态的跨系统通知 | bevy-events-messaging 中的消息或观察者槽位 |
在本文件中新造的事件类型 |
| 文档集合之外的 API | 查阅官方文档 | 编造的 crate 或 API |
归属表见 references/ecs-ownership.md。
禁止事项
- 不要在文档 URL 中固定
/0.20.0/。原因:链接保持在latest;0.20 目标只在正文中说明一次。 - 不要从两个无序系统可变查询同一组件。原因:除非
.chain()排序,调度会并行运行系统。 - 不要在此处编造物理、导航、网络或 XR crate。原因:本技能只列出有文档的 Bevy crate 与模块。
- 不要在 Bevy Cargo 特性中命名其他引擎的 HTML 导出预设。原因:浏览器目标是
wasm32-unknown-unknown加上webgl2或webgpu。 - 不要把其他引擎的节点类型导入 Bevy 系统。原因:那些类型不是组件,不会被调度。
- 不要使用编造的 API 或未命名的第三方 crate 作为选定求解方案。原因:本技能只列出有文档的 Bevy crate 与模块。
参考
官方链接保持在无版本号的 latest 页面。bevy-master 上的库固定为 0.20.0。
官方文档
- Assets - 官方资源目录。未选择第三方 crate。
- Examples -
latest分支上的示例树。 - ECS -
Component、系统、Query、Startup、Update与.chain()。 - Plugins -
Plugin、DefaultPlugins、MinimalPlugins与add_plugins。
相关技能
前置
- bevy-master - 中枢与调度。
- bevy-ecs-composition - 组件与系统。
- bevy-platform-desktop - 与桌面共享的 Window 组件。
补充
- godot-platform-web - 用于浏览器构建的 Godot 包。
下游 / 消费者
- 暂无。
主技能
- bevy-master - Bevy 路由。