Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ickshonpe/conditional_commands
Conditional component, bundle, and child insertion without the need for an intermediate EntityCommands binding
https://github.com/ickshonpe/conditional_commands
bevy ecs extensions rust
Last synced: 24 days ago
JSON representation
Conditional component, bundle, and child insertion without the need for an intermediate EntityCommands binding
- Host: GitHub
- URL: https://github.com/ickshonpe/conditional_commands
- Owner: ickshonpe
- License: mit
- Created: 2022-05-30T09:55:04.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2022-11-15T14:05:12.000Z (about 2 years ago)
- Last Synced: 2024-04-24T15:27:12.133Z (8 months ago)
- Topics: bevy, ecs, extensions, rust
- Language: Rust
- Homepage:
- Size: 20.5 KB
- Stars: 4
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Conditional Commands
This crate implements three extension traits that allow for conditional component, bundle and child insertion without the need for an intermediate ```EntityCommands``` or ```EntityMut``` binding.
* ```ConditionalInsertBundleExt``` for ```EntityCommands``` and ```EntityMut```\
Methods:
- ```insert_if```
- ```insert_if_else```
- ```insert_some```
- ```insert_some_or```
* ```ConditionalChildBuilderExt``` for ```EntityCommands```\
Methods:
- ```with_children_if```
* ```ConditionalWorldChildBuilderExt``` for ```EntityMut```\
Methods:
- ```with_children_if```
Supports Bevy 0.9
#
## Usage
To add to a project either use:
```
cargo add conditional_commands
```
or manually add to your Cargo.toml:
```toml
[dependencies]
conditional_commands = "0.9.0"
```
## A Motivating But Contrived ECS Fizz-Buzz Example
```rust
use bevy::prelude::*;
use conditional_commands::*;
#[derive(Component)]
struct FizzBuzzer;
#[derive(Component)]
struct Number(usize);
#[derive(Component)]
struct Fizz;
#[derive(Component)]
struct Buzz;
fn fizz_buzz(
mut commands: Commands
) {
for n in 1 ..= N {
let mut entity_commands = commands.spawn(FizzBuzzer);
match (n % 3, n % 5) {
(0, 0) => { entity_commands.insert((Fizz, Buzz)); },
(0, _) => { entity_commands.insert(Fizz); },
(_, 0) => { entity_commands.insert(Buzz); },
_ => { entity_commands.insert(Number(n)); }
}
}
}
```
With Conditional Commands the intermediate EntityCommands binding in no longer required.
```rust
fn fizz_buzz(
mut commands: Commands
) {
for n in 1 ..= N {
commands
.spawn(FizzBuzzer)
.insert_if(0 < n % 3 && 0 < n % 5, || Number(n))
.insert_if(n % 3 == 0, || Fizz)
.insert_if(n % 5 == 0, || Buzz);
}
}
```
`ConditionalInsertBundleExt` is also implemented for `EntityMut`:
```rust
#[derive(Component)]
struct Even;
#[derive(Component)]
struct Odd;
fn exclusive_system(world: &mut World) {
for n in 0..10 {
world.spawn_empty().insert_if_else(n % 2 == 0, || Even, || Odd);
}
}
```
Bundles passed to the `_else`/`_or` methods don't need to be the same type,
as seen in the above example with the `Even` and `Odd` components.
Use `insert_some` to insert the inner value of an optional bundle, if present.
```rust
commands.spawn(MyBundle)
.insert_some(Some(OtherBundle::default()))
.insert_some_or(None::, AlternativeThing::default);
```
## Examples
```
cargo run --example exclusive
cargo run --example fizz_buzz
cargo run --example insert_if
cargo run --example insert_if_2
cargo run --example with_children_if
```
#
## Notes
* I haven't done any benchmarking. For performance critical systems it should be better to spawn entire bundles at once.
* Earlier versions of this crate have both eager and lazy versions of each insertion method. I'm not sure the eager versions had any advantages (beyond no `||`), so they are gone.
* I wasn't able to quite finesse the lifetimes to get a single generic child builder trait for both ```EntityCommands``` and ```EntityMut```.