https://github.com/drakmaniso/bevy_pixel_camera

A simple pixel-perfect camera plugin for Bevy, suitable for pixel-art.
https://github.com/drakmaniso/bevy_pixel_camera

bevy graphics pixel-art

Last synced: 1 day ago
JSON representation

A simple pixel-perfect camera plugin for Bevy, suitable for pixel-art.

• Host: GitHub
• URL: https://github.com/drakmaniso/bevy_pixel_camera
• Owner: drakmaniso
• License: apache-2.0
• Created: 2021-06-17T08:33:59.000Z (over 3 years ago)
• Default Branch: main
• Last Pushed: 2024-07-05T15:58:49.000Z (6 months ago)
• Last Synced: 2024-12-14T16:03:33.409Z (8 days ago)
• Topics: bevy, graphics, pixel-art
• Language: Rust
• Homepage:
• Size: 91.8 KB
• Stars: 147
• Watchers: 7
• Forks: 18
• Open Issues: 5
• Metadata Files:
  • Readme: README.md
  • License: LICENSE-APACHE

Awesome Lists containing this project

README

        
# bevy_pixel_camera

A simple camera plugin for the Bevy game engine, to help with the use of

pixel-art sprites.

This crates provides a plugin to automatically configure Bevy's

`Camera2dBundle`. It works by setting the camera to an integer scaling

factor (using Bevy's `ScalingMode::WindowSize`), and automatically updating

the zoom level so that the specified target resolution fills as much of the

sceen as possible.

The plugin can also automatically set and resize the viewport of the camera

to match the target resolution.

## Comparison with other methods

There is two main methods to render pixel-art games: upscale each sprite

independently, or render everything to an offscreen texture and only upscale

this texture. This crate use the first method. There is advantages and

drawbacks to both approaches.

Advantages of the "upscale each sprite independently" method (i.e. this

crate):

- allows for smoother scrolling and movement of sprites, if you're willing

  to temporarily break the alignment on virtual pixels (this would be even

  more effective with a dedicated upscaling shader);

- easier to mix pixel-art and high resolution graphics (for example for

  text, particles or effects).

Advantages of the "offscreen texture" method:

- always ensure perfect alignment on virtual pixels (authentic "retro"

  look);

- may be more efficient (in most cases, the difference is probably

  negligible on modern computers).

## How to use

Note that Bevy uses linear sampling by default for textures, which is not

what you want for pixel art. The easiest way to change this is to configure

Bevy's default plugins with `ImagePlugin::default_nearest()`.

Also note that if either the width or the height of your sprite is not

divisible by 2, you may need to change the anchor of the sprite (which is at

the center by default), otherwise it won't be aligned with virtual pixels.

```rust

use bevy::prelude::*;

use bevy::sprite::Anchor;

use bevy_pixel_camera::{

    PixelCameraPlugin, PixelZoom, PixelViewport

};

fn main() {

    App::new()

        .add_plugins(DefaultPlugins.set(ImagePlugin::default_nearest()))

        .add_plugins(PixelCameraPlugin)

        .add_systems(Startup, setup)

        .run();

}

fn setup(

    mut commands: Commands,

    asset_server: Res,

) {

    commands.spawn((

        Camera2dBundle::default(),

        PixelZoom::FitSize {

            width: 320,

            height: 180,

        },

        PixelViewport,

    ));

    commands.spawn(SpriteBundle {

        texture: asset_server.load("my-pixel-art-sprite.png"),

        sprite: Sprite {

            anchor: Anchor::BottomLeft,

            ..Default::default()

        },

        ..Default::default()

    });

}

```

A small example is included in the crate. Run it with:

```console

cargo run --example flappin

```

## Bevy versions supported

| bevy | bevy_pixel_camera |

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

| 0.13 | 0.13              |

| 0.12 | 0.12              |

| 0.11 | 0.5.2             |

| 0.10 | 0.4.1             |

| 0.9  | 0.3               |

| 0.8  | 0.2               |

### Migration guide: 0.4 to 0.5 (Bevy 0.10 to 0.11)

The `PixelBorderPlugin` has been deprecated. If you want a border around

your virtual resolution, pass `true` to the `set_viewport` argument when

creating the camera bundle (see example above).

### Migration guide: 0.5 to 0.12 (Bevy 0.11 to 0.12)

The `PixelCameraBundle` has been deprecated. Replace it with a standard

`Camera2dBundle`, to which you add the `PixelZoom` and `PixelViewport`

components.

## License

Licensed under either of

- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or

  )

- MIT license ([LICENSE-MIT](LICENSE-MIT) or

  )

at your option.

License: MIT OR Apache-2.0