用途
当一款桌面窗口游戏需要接受触摸输入、并改用更小布局时,可加载此技能。平台相关特性(例如打包)由 bevy-platform-mobile 负责,本技能聚焦布局、触摸与 DPI。
主要能力(ECS 层面)
- 输入:
Touches列出当前活动触点。动作映射由 bevy-input-handling 处理。 - UI:放大
Node命中区域,并通过安全内边距Resource给根节点加内边距。WindowResolution设置逻辑尺寸,并可选择覆盖缩放因子。WindowScaleFactorChanged报告实时的 DPI 变化。 - 纹理:ASTC 是面向移动 GPU 的压缩纹理格式;上传仍通过
Assets<Image>完成。
代码示例
配置窗口:
fn configure_window(mut windows: Query<&mut Window>) {
let Ok(mut window) = windows.single_mut() else {
return;
};
window.resolution.set(720.0, 1280.0);
window.resolution.set_scale_factor_override(Some(2.0));
}
跟踪触摸:
#[derive(Resource, Default)]
struct LastTouch(Option<Vec2>);
fn track_touch(touches: Res<Touches>, mut last: ResMut<LastTouch>) {
last.0 = touches.iter().next().map(|touch| touch.position());
}
放大触控目标与填充 HUD:
#[derive(Component)]
struct TouchTarget;
#[derive(Component)]
struct HudRoot;
#[derive(Resource)]
struct SafeInsets {
top: f32,
bottom: f32,
}
fn enlarge_targets(mut nodes: Query<&mut Node, With<TouchTarget>>) {
for mut node in &mut nodes {
node.min_width = Val::Px(88.0);
node.min_height = Val::Px(88.0);
}
}
fn pad_hud(insets: Res<SafeInsets>, mut roots: Query<&mut Node, With<HudRoot>>) {
for mut node in &mut roots {
node.padding = UiRect {
top: Val::Px(insets.top),
bottom: Val::Px(insets.bottom),
left: Val::Px(12.0),
right: Val::Px(12.0),
};
}
}
跟随 DPI:
use bevy::window::WindowScaleFactorChanged;
fn follow_dpi(
mut scale_events: MessageReader<WindowScaleFactorChanged>,
mut ui_scale: ResMut<UiScale>,
) {
for event in scale_events.read() {
ui_scale.0 = event.scale_factor as f32;
}
}
依赖声明:
[dependencies]
bevy = "0.20"
适配选择
| 需求 | Bevy 做法 |
|---|---|
| 指针 | Touches 处理触点。桌面窗口上的指针位置是 Window::cursor_position。 |
| 仅悬停菜单 | 依赖悬停状态的交互,还需要一条按下或点击的路径。 |
| 安全边距 | SafeInsets 资源,作为 Node 的 padding 应用。 |
范围与限制
- 商店列表与操作系统权限对话框不在本技能范围内。布局、触摸与 DPI 由上述系统承担。
- 平台打包保留在 bevy-platform-mobile。
- 不要在文档 URL 中固定
/0.20.0/:链接保持指向latest,0.20 目标只在正文中说明一次。 - 不要从两个无序系统可变查询同一组件:调度默认并行运行系统,除非用
.chain()排序。 - 不要在此发明物理、导航、网络或 XR crate:本技能只使用有文档的 Bevy crate 与模块。
- Bevy 代码中不要出现导出预设或触摸模拟的名称:
Touches、Window与UiScale才是有文档的 Bevy 部件。 - 不要发明 API,也不要把未具名的第三方 crate 当作方案:Bevy 代码保持惯用 ECS,只使用有文档的 Bevy API。
适用范围(版本)
目标为 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 |
生成系统 | 初始世界用 Startup;运行时生成用后续调度 |
| 不能竞争的顺序 | .chain() |
仅被链式的系统 | 同一调度 |
| 插件边界 | Plugin |
build 注册系统与资源 |
应用运行之前 |
借用规则:两个都对同一组件做可变查询的系统必须排序(.chain())或拆分,使只有一个写入;不相关的系统保持并行。
决策表
| 如果你需要 | 这样做 | 不要 |
|---|---|---|
| 按实体数据 | Component + Query |
把脚本字段拷贝到实体上 |
| 应用级配置或时钟 | Resource |
把值拷贝到每个实体 |
| 稳定的模拟步进 | FixedMain 与 Fixed 时钟 |
把模拟绑到原始帧 Update |
| 启动生成 | Startup 中的 Commands |
从渲染系统生成 |
| 非共享状态的跨系统通知 | bevy-events-messaging 中的消息或观察者 | 在本文件里新造事件类型 |
| 文档集合之外的 API | 先查官方文档 | 编造的 crate 或 API |
更多归属信息见 references/ecs-ownership.md。