bevy_scroller

Crates.iobevy_scroller
lib.rsbevy_scroller
version0.3.0
sourcesrc
created_at2023-10-30 21:32:07.03036
updated_at2024-05-08 23:23:01.524652
descriptionScroller plugin for Bevy
homepage
repositoryhttps://github.com/SET001/bevy_scroller
max_upload_size
id1019051
size160,033
Kostiantyn Kostiuk (SET001)

documentation

README

bevy_scroller

A small Bevy plugin to scroll things and create parallaxes.

crates.io crates.io docs.rs Bevy tracking

parallax

About

The idea is simple - you define an area for the scroller and select an item generator that will be responsible for generating items. Scroller will fill the area with items from this generator, update its position, track which items moved out of the area and need to be destroyed, and track when new items need to be generated. This plugin makes no assumptions as to what actually will be a scroller item. There are few predefined generators that implements common strategies to gerenerate sprites as scroller items. You can also implement your own generators to scroll whatever you want (tilemaps, animations, complex entity hierarchies, etc.).

By creating mutliple scrollers with different z-index, sprite and speed, you can easily create parallaxes (example).

Features

  1. Scroll directions
  2. Different scroll item sizes in same scroller
  3. Render to texture
  4. Pre-build generators for sprite items:
    1. Single - repeat single image
    2. Sequence - repeat sequence of images
    3. Random Sequence - scroller will consist of random images from sequence
  5. Custom generators - define how exactly items should be generated and spawned

Todo

  • make it work with spritesheets
  • scroller run conditions (when player moved, for instance)
  • change scroll direction on the go
  • some cases might be optimised with using shaders.

Usage

spawn a scroller-entity with:

  1. ScrollerSize component
  2. Scroller component
  3. If you want any of pre-build generators, attach ScrollerGenerator component
  commands.spawn((
    ScrollerGenerator::SpriteSingle("scroller_image.png".into()),
    ScrollerSize {
      size: Vec2::new(500., 300.),
    },
    ScrollerBundle {
      scroller: Scroller {
        speed: 1.,
        direction: ScrollerDirection::Forward,
        ..default()
      },
      ..default()
    },
  ));

Custom Generators

Generating scroller item devied in 2 parts. First you describe how item will be generated. Second you describe how item should be spawned in the world. You will need 2 structs (item and generator component) and 2 funtions (generator and spawner).

Define struct that will desribe generated item. This struct should implement GeneratedItem trait with fn size(&self) -> Vec2 method so that item size is known. This struct will be passed to the spawner function so it has to contain all the information suffusion to spawn the item.

#[derive(Clone, Reflect, Debug)]
pub struct MyScrollerItem {
  pub size: Vec2,
}

impl GeneratedItem for MyScrollerItem {
  fn size(&self) -> Vec2 { self.size }
}

Define generator component. It will mark your generator and contain generator configuration.

#[derive(Component, Clone, Default)]
pub struct MyGenerator {}

Implement ScrollerGenerator trait for this struct. This includes implementing gen_item function which should contain item generation logic and return that item.


impl ScrollerGenerator for MySpriteGenerator {
  type I = MyScrollerItem;

  fn gen_item(&mut self) -> Self::I {
    Self::I {}
  }
}

Finally write spawner function that will spawn previously generated item. This should be regular bevy system that will additionally receive In<Vec<(Entity, Scroller, Box<MyScrollerItem>)>> so that you can know what actully to spawn.

Then add this generator with spawner to your app:

app.add_scroller_generator::<SingleSpriteGenerator, _, _>(sprite_spawner)

Also see existing generators (sprite, poisson) for example of how you can implement your own.

Examples

Run examples with

cargo run --example <example> --features=bevy/default --release
cargo run --example poisson --features=bevy/default,poisson --release

You can also add dev feature to add wireframes and bevy_editor_pls to examples.

example preview description
single shows a basic usage
sequence shows a usage of sequence generator. It also shows how to wait while all assets are loaded and retrieve sprite size
random_sequence shows random sequence generator
multiple example of muptiple scrollers
mirrors parallax example of how you can render scroller to texture and then use that texture to show this same scroller in other parts of applications
parallax parallax showing how you can set up a parallax with this plugin
poisson parallax use of poisson generator to fill space with sprites and scroll them all. Set up radius to ensure that no entity generated closer than that radius. Run this example with additionall poisson feature
tilemaps tilemap Show how to use scrollers with tilemaps. It uses custom generator to generate scroller items with tilemaps based on bevy_ecs_tilemap

Bevy Compatibility

bevy bevy_scroller
0.13.0 0.3.*
0.12.0 0.2.*
0.11.0 0.1.*

Credits


License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Commit count: 135

cargo fmt