Crate bevy_aspect_ratio_mask 

A Bevy plugin that enforces a fixed virtual resolution with dynamic letterboxing and UI scaling.

Add AspectRatioPlugin to your app, and use the injected Hud resource to spawn your UI. Requires a Camera2dBundle with ScalingMode::AutoMin.

---

Example

use bevy::prelude::*;
use bevy_aspect_ratio_mask::{AspectRatioPlugin, Hud};

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(AspectRatioPlugin::default())
        .add_systems(Startup, setup)
        .run();
}

fn setup(mut commands: Commands, hud: Res<Hud>) {
    commands.entity(hud.0).with_children(|parent| {
        parent
            .spawn((
                Node {
                    width: Val::Percent(100.0),
                    top: Val::Percent(10.0),
                    position_type: PositionType::Absolute,
                    justify_content: JustifyContent::Center,
                    ..default()
                },
            ))
            .with_children(|p| {
                p.spawn(Text::new("Hello"));
            });
    });
}

Structs

AspectRatioMask

Represents the background color used for the letterboxing “mask” regions that appear outside the target virtual resolution.

AspectRatioPlugin

A Bevy plugin that enforces a fixed virtual resolution with black bar masking and UI scaling.

Hud

Resource pointing to the root Entity of the aspect-ratio-scaled HUD.

Resolution

The virtual resolution used to maintain a consistent aspect ratio.