bevy-platform-mobile

用途

本技能用于在 Bevy 引擎中开发面向触屏设备的移动端应用。当目标平台为触摸设备时加载本技能。商店上架信息和操作系统权限对话框不属于本 crate 的范畴，XR 是另一个独立主题。

主要能力

输入

Touches：保存当前活跃的触点。
PinchGesture：用于 iOS 和 macOS 上双指捏合手势的消息。

Android

启用 android-game-activity 特性。
android-native-activity 是旧版 activity。

电源管理

WinitSettings::mobile()：聚焦时等待输入，失焦时降为每秒一次的等待。移动端更新模式会在窗口进入后台时让循环休眠。

iOS 边缘

Window::preferred_screen_edges_deferring_system_gestures 接收一个 ScreenEdge。

纹理

ASTC 在资源加载后，会以 TextureFormat::Astc 出现在 Image 描述符上。

使用方式

依赖配置

[dependencies]
bevy = { version = "0.20", features = ["android-game-activity"] }

移动端更新模式

use bevy::winit::WinitSettings;

fn main() {
    App::new()
        .insert_resource(WinitSettings::mobile())
        .add_plugins(DefaultPlugins)
        .run();
}

摇杆区域

摇杆区域把第一个触点转换为单位轴。键盘和鼠标仍由 bevy-input-handling 处理。

#[derive(Component, Default)]
struct MoveIntent {
    axis: Vec2,
}

#[derive(Resource)]
struct StickZone {
    center: Vec2,
    radius: f32,
}

fn read_stick(touches: Res<Touches>, zone: Res<StickZone>, mut intents: Query<&mut MoveIntent>) {
    let Some(touch) = touches.iter().next() else {
        return;
    };
    let offset = touch.position() - zone.center;
    let length = offset.length();
    let axis = if length <= zone.radius && length > 0.0 {
        offset / zone.radius
    } else if length > zone.radius {
        offset / length
    } else {
        Vec2::ZERO
    };
    for mut intent in &mut intents {
        intent.axis = axis;
    }
}

捏合手势

捏合消息调整缩放资源。注册消息是引擎对内置手势类型的职责。

use bevy::input::gestures::PinchGesture;

#[derive(Resource)]
struct CameraZoom(f32);

fn apply_pinch(mut pinches: MessageReader<PinchGesture>, mut zoom: ResMut<CameraZoom>) {
    for pinch in pinches.read() {
        zoom.0 = (zoom.0 + pinch.0).clamp(0.25, 4.0);
    }
}

延迟系统手势与统计 ASTC

在所有屏幕边缘延迟系统手势，并统计资源库中已有的 ASTC 图像。

use bevy::render::render_resource::TextureFormat;
use bevy::window::PrimaryWindow;
use bevy::window::ScreenEdge;

fn defer_system_gestures(mut windows: Query<&mut Window, With<PrimaryWindow>>) {
    let Ok(mut window) = windows.single_mut() else {
        return;
    };
    window.preferred_screen_edges_deferring_system_gestures = ScreenEdge::All;
}

#[derive(Resource, Default)]
struct AstcCount(usize);

fn count_astc(images: Res<Assets<Image>>, mut count: ResMut<AstcCount>) {
    count.0 = images
        .iter()
        .filter(|(_, image)| matches!(image.texture_descriptor.format, TextureFormat::Astc { .. }))
        .count();
}

设计到 Bevy 惯用法的对应

设计	Bevy 惯用法
触摸	Update 中的 Touches
Android activity	android-game-activity Cargo 特性
安全区域	主 Window 上的 ScreenEdge，加上来自 bevy-adapt-desktop-to-mobile 的 UI 内边距
后台帧率	WinitSettings::mobile()

适用范围

打包、签名和商店权限提示不在本技能范围内。本技能涵盖的系统为：触摸、捏合、屏幕边缘、ASTC 检测以及移动端更新模式。

专家知识要点

目标：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()），或拆分使只有一个写入。不相关的系统保持并行。这是 ECS 页面规则，不是对系统集 API 的猜测。

决策

如果你需要	这样做	不要
每实体数据	Component + Query	挂在实体上的场景树脚本
应用级配置或时钟	Resource	把值复制到每个实体
稳定的模拟步长	FixedMain 和 Fixed 时钟	把模拟绑定到原始帧 Update
启动生成	Startup 中的 Commands	从渲染系统生成
非共享状态的跨系统通知	bevy-events-messaging 中的消息或观察者槽位	在本文件中发明新事件类型
文档集之外的 API	先查官方文档	编造的 crate 或 API

加载 references/ecs-ownership.md 查看归属表。

禁止事项

不要在文档 URL 中固定 /0.20.0/。原因：链接保持在最新版；0.20 目标只在正文中说明一次。
不要从两个无序系统可变查询同一组件。原因：除非 .chain() 排序，调度会并行运行系统。
不要在此发明物理、导航、网络或 XR crate。原因：本技能只命名有文档的 Bevy crate 和模块。
不要使用 Godot 触屏或安全边距项目设置。原因：Bevy 代码保持惯用 ECS，只使用有文档的 Bevy API。
不要在 Bevy 代码中使用 Godot 类型。原因：Bevy 代码保持惯用 ECS，只使用有文档的 Bevy API。
不要发明 API 或把未命名的第三方 crate 作为选定求解器。原因：Bevy 代码保持惯用 ECS，只使用有文档的 Bevy API。

参考

官方页面保持在无版本号的 bevy.org URL 上。bevy-master 上的库固定为 0.20.0。ScreenEdge 是 Window 上的字段。触点保存在 Touches 上；它们不是单独的事件结构体。

官方文档

Assets - 官方资源目录。未选择第三方 crate。
Examples - 最新分支上的示例树。
ECS - Component、系统、Query、Startup、Update 和 .chain()。
Plugins - Plugin、DefaultPlugins、MinimalPlugins 和 add_plugins。

技能介绍

用途