SuperAPI AI 工具集

bevy-adapt-desktop-to-mobile

编程与开发

查看项目

更新于 10-16 11:39

技能介绍

用途

当一款桌面窗口游戏需要接受触摸输入、并改用更小布局时,可加载此技能。平台相关特性(例如打包)由 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。