SuperAPI AI 工具集

bevy-platform-web

编程与开发

查看项目

更新于 10-16 10:37

技能介绍

用途

当同一套应用需要在浏览器中运行时使用本技能。资料未说明打包流水线(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。

相关技能

前置

补充

下游 / 消费者

  • 暂无。

主技能