seldom-se / seldom_pixel

Bevy plugin for limited color palette pixel art games

seldom_pixel

seldom_pixel is a Bevy plugin for limited color palette pixel art games. It handles:

• Sprites
• Filters (defined through images; apply to layers or individual entities)
• Simple UI (text, buttons, and sprites locked to the camera)
• Tilemaps
• Animations (for sprites, filters, tilesets, and text; supports dithering!)
• Custom layers
• Particles (with pre-simulation! Enable particle feature)
• Palette changing
• Typefaces
• An in-game cursor
• Camera
• Lines (enable line feature)
• And more to come!

It also features optional integration with:

• seldom_state (for animation state machines; state feature)
• seldom_map_nav (makes SubPxPosition implement Position2; nav feature)

See the examples directory for examples. If you need help, feel free to ping me on the Bevy Discord server (@Seldom)! If any of the docs need improvement, feel free to submit an issue or pr!

Philosophies

• Assets are created through images

All assets, including filters, are loaded from images. seldom_pixel's scope is limited to rendered things, so this doesn't apply to things like levels and sounds. I recommend finding an art program you're comfortable with. Personally, I use GIMP, but it can be difficult to figure out. I hear good things about Aseprite, which you can use for free if you can compile it. I've only used this plugin on .png files, so I recommend using that format, but feel free to try it on other lossless formats.

• It is what it looks like

This crate's position component, PxPosition, uses an IVec2 (2-dimensional i32 vector) to store positions. This means that entities are located at exact pixel positions. So, if it looks like the player is up against a wall, or a projectile hit an enemy, then the game will respond like that's true. There is also a SubPxPosition component, which uses a Vec2, for features like movement and velocity. It automatically updates the PxPosition component, which I recommend using when possible. I also recommend resetting the SubPxPosition to PxPosition's value when it stops moving, so moving objects feel consistent to the player. This is less of a concern for games with smaller pixels.

• Sacrifice versatility for productivity

If you are already interested in making a limited color palette pixel art game, this is an easy win for you. Filters in seldom_pixel are just maps from each color in the palette to another color in the palette. Filters like this would be difficult to create for each of the 16,777,216 RGB colors, but seldom_pixel only allows up to 255 colors in your palette (and you will likely want to use fewer), so it's easy to create effects. This also applies on the library-development end too. The limitations of seldom_pixel mean I only need to make its features work for 2D games that use bytes for pixels, so it's easier to develop and maintain. Anyway, limitations can incite creativity.

Future Work

• Advanced UI, good enough to build a UI library on
• More advanced particle system
• More shape primitives
• Spatial filters that can filter defined areas, and apply their animations over space instead of time. For effects like lighting and bloom.
• Make the rendering happen in the render world

Usage

Add to your Cargo.toml

# Replace * with your desired version
[dependencies]
seldom_pixel = "*"

Then add PxPlugin to your app. Check out the examples for further usage.

Compatibility

Bevy	seldom_state	seldom_map_nav	seldom_interop	bevy_ecs_tilemap	seldom_pixel
0.14	0.11	0.7			0.7
0.13	0.10	0.6			0.6
0.12	0.9		0.5	0.12	0.5
0.11	0.7		0.4	0.11	0.4
0.10	0.6		0.3	0.10	0.3
0.10	0.5		0.3	0.10	0.2
0.8	0.2		0.1	0.7	0.1

License

seldom_pixel is dual-licensed under MIT and Apache 2.0 at your option.

Contributing

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Demo Video

seldom_pixel's Issues

Panic when trying to spawn text as a child of a node bundle

Hi, while attempting to incorporate bitmap fonts into my code I came across this plugin. Unfortunately, creating a pixel perfect UI in bevy is a hassle, right now I'm simply trying to add the PxTextBundle as a child to NodeBundle. Here's the code:

use bevy::prelude::*;
use seldom_pixel::prelude::*;

use crate::ui::{
    menu_handler::MenuHandlerPlugin, seldom_ui::SeldomUiPlugin,
    ui_pixel_perfect::UiPixelPerfectPlugin,
};

use self::{common::InGameCamera, seldom_ui::Layer};

mod bounty;
mod common;
mod inventory;
mod menu_handler;
mod seldom_ui;
mod ui_pixel_perfect;

#[derive(Component)]
///Struct for main menu component
pub struct MainMenuComponent;

/// Struct to define the UI plugin
pub struct UiPlugin;

impl Plugin for UiPlugin {
    fn build(&self, app: &mut App) {
        info!("Building UI plugin...");
        app.add_systems(Startup, init_ui);
        app.add_plugins(SeldomUiPlugin);
        //app.add_plugins(MenuHandlerPlugin);
    }
}

fn init_ui(
    mut commands: Commands,
    query: Query<Entity, With<InGameCamera>>,
    mut typefaces: PxAssets<PxTypeface>,
) {
    let camera_entity = query.get_single().expect("No InGameCamera");

    commands
        .spawn((
            NodeBundle {
                style: Style {
                    flex_direction: FlexDirection::Column,
                    justify_content: JustifyContent::SpaceBetween,
                    align_items: AlignItems::Stretch,
                    width: Val::Percent(100.),
                    height: Val::Percent(100.),
                    padding: UiRect {
                        left: Val::Px(10.),
                        right: Val::Px(10.),
                        top: Val::Px(10.),
                        bottom: Val::Px(10.),
                    },
                    ..Default::default()
                },
                background_color: Color::BISQUE.into(),
                ..Default::default()
            },
            MainMenuComponent,
            TargetCamera(camera_entity),
        ))
        .with_children(|builder| {
            builder.spawn(PxTextBundle::<Layer> {
                text: "Testing".into(),
                typeface: typefaces.load(
                    "typefaces/3x5spaceremoved.png",
                    &"!\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~".chars().rev().collect::<String>(),
                    [(' ', 3)]),
                rect: IRect::new(0, 0, 64, 64).into(),
                ..default()
            });
        });
}

The SeldomUI Plugin i made

use bevy::prelude::*;
use seldom_pixel::prelude::*;

use super::common::InGameCamera;

pub struct SeldomUiPlugin;

impl Plugin for SeldomUiPlugin {
    fn build(&self, app: &mut App) {
        info!("Building Seldom UI plugin...");
        app.add_plugins(PxPlugin::<Layer>::new(
            UVec2::new(480, 270),
            "palettes/palette_1.png".into(),
        ));
        app.insert_resource(ClearColor(Color::BLACK));
        app.add_systems(PreStartup, init);
    }
}

fn init(mut commands: Commands) {
    commands.spawn((Camera2dBundle::default(), InGameCamera));
}

#[px_layer]
pub struct Layer;

Here's the panic:

thread '<unnamed>' panicked at dreambound_lib/src/ui/mod.rs:39:44:
No InGameCamera: NoEntities("bevy_ecs::query::state::QueryState<bevy_ecs::entity::Entity, bevy_ecs::query::filter::With<dreambound_lib::ui::common::InGameCamera>>")
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
Encountered a panic in system `dreambound_lib::ui::init_ui`!
Encountered a panic in system `bevy_app::main_schedule::Main::run_main`!
thread 'main' panicked at /Users/brandonwand/.cargo/registry/src/index.crates.io-6f17d22bba15001f/winit-0.29.10/src/platform_impl/macos/app_state.rs:387:33:
called `Result::unwrap()` on an `Err` value: PoisonError { .. }

Finish Bevy 0.12 updates

• Update to new bevy_ecs_tilemap release, when that's available
• Fix particle feature
• Fix state example

WASM Compatibility

I've been trying to compile this crate in a new bevy project to WASM using trunk the provided text example, but am running into issues. The main error I'm seeing in the browser console is as follows:

panicked at 'Resource requested by seldom_pixel::screen::update_screen_palette does not exist: seldom_pixel::palette::Palette', C:\Users\jakej\.cargo\registry\src\github.com-1ecc6299db9ec823\bevy_ecs-0.10.1\src\system\system_param.rs:460:17

Any chance there is a way to resolve this issue? Or is WASM not a supported target?