This crate implements an extension trait on Commands
, DespawnAllCommandsExt
which has two methods despawn_all
and despawn_all_recursive
that allow you to despawn all entities that satisfy a given query filter with a single statement.
Adds a new Commands
extension trait RemoveAllCommandsExt
which implements a method
remove_all
that allows you to
remove a component from multiple filtered entities at once.
Usage examples:
*
rust
commands.remove_all::<MyComponent, ()>()
For every entity that has a component of type `MyComponent`, remove `MyComponent`.
We have to use the unit type `()` to signify that we want no filtering of entities (except for selecting those that have a `MyComponent`) because Rust doesn't allow default generic parameters on functions.
*
```rust
commands.remove_all::<
MyComponent,
(Changed
(); ``
For every entity that has a changed
MyComponentcomponent and no
MyPermissioncomponent, removes
MyComponent`.
Version 0.10 has seperate remove_all
and remove_all_filtered
functions. Requiring ()
for unfiltered removals is a bit ugly but I prefer the crate to have a smaller footprint.
Added doc comments for all methods.
Supports Bevy 0.8
Revamped RetainCommandsExt
, now only has two methods
* retain
* retain_recursive
Similar to Vec's retain, but for queries. Example of what is very probably a terrible anti-pattern:
```rust use bevydespawnwith::retain::*;
struct DespawnTimer(f32);
fn updatedespawntimers( mut commands: Commands, time: Res
Feature-gated for all its silliness, to enable retain
use:
toml
bevy_despawn_with = { version = "0.12.1", features = ["retain"] }
Massive API improvements
* despawn_with
and despawn_with_recursive
renamed to despawn_all
and despawn_all_recursive
.
* The methods take a query filter instead of a component tuple. For example:
```rust
commands.despawn_all::<(With<People>, With<Shoes>, Without<Laces>)>();
```
despawns all people wearing shoes without laces.
despawn_with_all
methods any more.No longer uses SystemState. Performance should be much better (assumed, not benchmarked).
Adds Bevy 0.7 support.
#
Marker components are a common pattern in Bevy: ```rust
struct MenuUiMarker;
fn spawnmenu(mut commands: Commands) { commands.spawnbundle(NodeBundle { ..Default::default() }) .insert(MenuUiMarker); // .. and so on. // The developer spawns a bunch of UI entities and then // inserts a MenuUiMarker component for each one. }
fn despawnall
pub struct MenuScreenPlugin;
impl Plugin for MenuScreenPlugin {
fn build(&self, app: &mut App) {
app.addsystemset(
SystemSet::onenter(AppState::MenuScreen)
.withsystem(spawnmenu)
)
.addsystemset(
SystemSet::onexit(AppState::MenuScreen)
.withsystem(despawnall::
DespawnAllCommandsExt
makes this a little more ergonomic:
```rust use bevydespawnwith::*;
fn despawn_system(mut commands: Commands) {
// Despawn all entities with a MenuUiMarker component
commands.despawn_all::<With<MenuUiMarker>>();
// Despawn all entities without a SomeOtherMarker component,
// and despawn those entities descendants.
commands.despawn_all_recursive::<Without<SomeOtherMarker>>();
// Methods can take any query filter.
// The following despawns any entity with a MenuUiMarker
// component, without a SomeOtherMarker component,
// and/or a changed GlobalTransform.
commands.despawn_all::<(Or<
With<MenUiMarker>,
Without<SomeOtherMarker>,
Changed<GlobalTransform>
)>();
}
so if we want we could replace the despawn_all system in the menu screen example with:
rust
app.addsystemset(
SystemSet::onexit(AppState::MenuScreen)
.withsystem(|mut commands: Commands|
commands.despawn_all::
The descendants of entities despawned with despawn_all_recursive
will be despawned regardless of whether they satisfy the query filter or not.
#
Add the following to your project's Cargo.toml [dependencies]
section:
toml
bevy_despawn_with = "0.12.1"
or with the retain feature enabled:
toml
bevy_despawn_with = { version = "0.12.1", features = ["retain"] }
and you are ready to go.
#
cargo run --example despawn_with
cargo run --example despawn_without
cargo run --example retain --features retain
cargo run --example retain_despawn_timer --features retain
cargo run --example remove_all