Bevy Platform Mobile Agent Skill

Bevy mobile platform

When to use

Load this when targeting touch devices. Store listings and OS permission dialogs stay outside the crate. XR is a separate topic.

ECS shape

• Input: Touches holds active contacts. PinchGesture is a message for two-finger pinch on iOS and macOS.
• Android: enable the android-game-activity feature. android-native-activity is the legacy activity.
• Power: WinitSettings::mobile() waits on input while focused and drops to a one-second wait when unfocused.
• iOS edges: Window::preferred_screen_edges_deferring_system_gestures takes a ScreenEdge.
• Textures: ASTC shows up as TextureFormat::Astc on an Image descriptor after the asset loads.

Examples

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

Mobile update mode sleeps the loop when the window is backgrounded.

use bevy::winit::WinitSettings;

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

A stick zone turns the first contact into a unit axis. Keyboard and mouse stay on 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;
    }
}

Pinch messages adjust a zoom resource. Registering messages is the engine's job for built-in gesture types.

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);
    }
}

Defer system gestures on every screen edge, and count ASTC images already in the asset store.

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();
}

Same job, Bevy types

| Design | Bevy idiom |

| --- | --- |

| Touch | Touches on Update |

| Android activity | android-game-activity Cargo feature |

| Safe area | ScreenEdge on the primary Window, plus UI padding from bevy-adapt-desktop-to-mobile |

| Background FPS | WinitSettings::mobile() |

Scope

Packaging, signing, and store permission prompts are outside this skill. Touch, pinch, screen edges, ASTC detection, and the mobile update mode are the systems above.

Expert Knowledge Delta

Target: Bevy 0.20+.

Core ECS types: Component, Resource, Query, Commands, Startup, Update, Fixed / FixedMain (bevy::time), .chain(), Plugin, DefaultPlugins, MinimalPlugins. Messages and observers are an ownership slot. See bevy-events-messaging for their APIs. Systems run in parallel unless .chain() orders the ones that conflict.

Who owns state

| Piece | Owner | Who may mutate | Schedule |

| --- | --- | --- | --- |

| Data on one entity | Component | One system via Query | Update or FixedMain |

| One value for the whole app | Resource | One system | Startup to insert, then the schedule that reads it |

| Spawn | Commands | The spawning system | Startup for the initial world; later schedules for runtime spawn |

| Order that must not race | .chain() | The chained systems only | Same schedule |

| Plugin boundary | Plugin | build registers systems and resources | Before the app runs |

Borrow rule: two systems that both mutably query the same component must be ordered (.chain()) or split so only one writes. Unrelated systems stay parallel. That is the ECS page rule, not a guess at a system-set API.

Decision

| If you need | Do this | Do not |

| --- | --- | --- |

| Per-entity data | Component + Query | A scene-tree script hung on the entity |

| App-wide config or clock | Resource | Copy the value onto every entity |

| Stable simulation step | FixedMain and the Fixed clock | Tie simulation to raw frame Update |

| Startup spawn | Commands in Startup | Spawn from a render system |

| Cross-system notice that is not shared state | Message or observer slot in bevy-events-messaging | A new event type invented in this file |

| An API outside the documented set | Check the official docs first | A made-up crate or API |

Load references/ecs-ownership.md for the ownership table.

NEVER

• Do not pin /0.20.0/ in docs URLs. WHY: links stay on latest; the 0.20 target is stated once in prose.
• Do not mutably query the same component from two unordered systems. WHY: the schedule runs systems in parallel unless .chain() orders them.
• Do not invent a physics, navigation, networking, or XR crate here. WHY: this skill only names documented Bevy crates and modules.

• No Godot touch-screen or safe-margin project settings. WHY: Bevy code stays idiomatic ECS and uses only documented Bevy APIs.

• No Godot types in Bevy code. WHY: Bevy code stays idiomatic ECS and uses only documented Bevy APIs.
• No invented APIs or unnamed third-party crates as the chosen solver. WHY: Bevy code stays idiomatic ECS and uses only documented Bevy APIs.

Reference

Official pages stay on unversioned bevy.org URLs. The library pin on bevy-master stays 0.20.0. ScreenEdge is a field on Window. Touch contacts stay on Touches; they are not a separate event struct.

Official Documentation

• Assets - Official asset catalog. No third-party crate was selected.
• Examples - Example tree on the latest branch.
• ECS - Component, systems, Query, Startup, Update, and .chain().
• Plugins - Plugin, DefaultPlugins, MinimalPlugins, and add_plugins.

Related Skills

Prerequisites

• bevy-master - Hub and schedules.
• bevy-ecs-composition - Components and systems.
• bevy-input-handling - Other devices.
• bevy-platform-desktop - Window shell.

Complements

• bevy-adapt-desktop-to-mobile - Layout and input adapt.
• godot-platform-mobile - Equivalent Godot skill.

Downstream / consumers

• None yet.

Master

• bevy-master - Bevy router.