2021-04-27 18:29:33 +00:00
|
|
|
#[doc(hidden)]
|
2020-04-12 21:47:41 +00:00
|
|
|
pub use crate::{
|
2022-03-15 01:54:05 +00:00
|
|
|
app::prelude::*, asset::prelude::*, core::prelude::*, ecs::prelude::*, hierarchy::prelude::*,
|
|
|
|
|
input::prelude::*, log::prelude::*, math::prelude::*, reflect::prelude::*, scene::prelude::*,
|
2022-03-01 20:52:09 +00:00
|
|
|
transform::prelude::*, utils::prelude::*, window::prelude::*, DefaultPlugins, MinimalPlugins,
|
2020-04-12 21:47:41 +00:00
|
|
|
};
|
2020-07-31 19:26:36 +00:00
|
|
|
|
bevy_derive: Add derives for `Deref` and `DerefMut` (#4328)
# Objective
A common pattern in Rust is the [newtype](https://doc.rust-lang.org/rust-by-example/generics/new_types.html). This is an especially useful pattern in Bevy as it allows us to give common/foreign types different semantics (such as allowing it to implement `Component` or `FromWorld`) or to simply treat them as a "new type" (clever). For example, it allows us to wrap a common `Vec<String>` and do things like:
```rust
#[derive(Component)]
struct Items(Vec<String>);
fn give_sword(query: Query<&mut Items>) {
query.single_mut().0.push(String::from("Flaming Poisoning Raging Sword of Doom"));
}
```
> We could then define another struct that wraps `Vec<String>` without anything clashing in the query.
However, one of the worst parts of this pattern is the ugly `.0` we have to write in order to access the type we actually care about. This is why people often implement `Deref` and `DerefMut` in order to get around this.
Since it's such a common pattern, especially for Bevy, it makes sense to add a derive macro to automatically add those implementations.
## Solution
Added a derive macro for `Deref` and another for `DerefMut` (both exported into the prelude). This works on all structs (including tuple structs) as long as they only contain a single field:
```rust
#[derive(Deref)]
struct Foo(String);
#[derive(Deref, DerefMut)]
struct Bar {
name: String,
}
```
This allows us to then remove that pesky `.0`:
```rust
#[derive(Component, Deref, DerefMut)]
struct Items(Vec<String>);
fn give_sword(query: Query<&mut Items>) {
query.single_mut().push(String::from("Flaming Poisoning Raging Sword of Doom"));
}
```
### Alternatives
There are other alternatives to this such as by using the [`derive_more`](https://crates.io/crates/derive_more) crate. However, it doesn't seem like we need an entire crate just yet since we only need `Deref` and `DerefMut` (for now).
### Considerations
One thing to consider is that the Rust std library recommends _not_ using `Deref` and `DerefMut` for things like this: "`Deref` should only be implemented for smart pointers to avoid confusion" ([reference](https://doc.rust-lang.org/std/ops/trait.Deref.html)). Personally, I believe it makes sense to use it in the way described above, but others may disagree.
### Additional Context
Discord: https://discord.com/channels/691052431525675048/692572690833473578/956648422163746827 (controversiality discussed [here](https://discord.com/channels/691052431525675048/692572690833473578/956711911481835630))
---
## Changelog
- Add `Deref` derive macro (exported to prelude)
- Add `DerefMut` derive macro (exported to prelude)
- Updated most newtypes in examples to use one or both derives
Co-authored-by: MrGVSV <49806985+MrGVSV@users.noreply.github.com>
2022-03-29 02:10:06 +00:00
|
|
|
pub use bevy_derive::{bevy_main, Deref, DerefMut};
|
2020-11-12 21:26:48 +00:00
|
|
|
|
2021-04-27 18:29:33 +00:00
|
|
|
#[doc(hidden)]
|
2020-07-31 19:26:36 +00:00
|
|
|
#[cfg(feature = "bevy_audio")]
|
|
|
|
|
pub use crate::audio::prelude::*;
|
2020-09-15 19:20:20 +00:00
|
|
|
|
2021-12-14 03:58:23 +00:00
|
|
|
#[doc(hidden)]
|
|
|
|
|
#[cfg(feature = "bevy_core_pipeline")]
|
|
|
|
|
pub use crate::core_pipeline::prelude::*;
|
|
|
|
|
|
2021-04-27 18:29:33 +00:00
|
|
|
#[doc(hidden)]
|
2020-09-15 19:20:20 +00:00
|
|
|
#[cfg(feature = "bevy_pbr")]
|
|
|
|
|
pub use crate::pbr::prelude::*;
|
|
|
|
|
|
2021-04-27 18:29:33 +00:00
|
|
|
#[doc(hidden)]
|
2020-09-15 19:20:20 +00:00
|
|
|
#[cfg(feature = "bevy_render")]
|
|
|
|
|
pub use crate::render::prelude::*;
|
|
|
|
|
|
2021-04-27 18:29:33 +00:00
|
|
|
#[doc(hidden)]
|
2020-09-15 19:20:20 +00:00
|
|
|
#[cfg(feature = "bevy_sprite")]
|
|
|
|
|
pub use crate::sprite::prelude::*;
|
|
|
|
|
|
2021-04-27 18:29:33 +00:00
|
|
|
#[doc(hidden)]
|
2020-09-15 19:20:20 +00:00
|
|
|
#[cfg(feature = "bevy_text")]
|
|
|
|
|
pub use crate::text::prelude::*;
|
|
|
|
|
|
2021-04-27 18:29:33 +00:00
|
|
|
#[doc(hidden)]
|
2020-09-15 19:20:20 +00:00
|
|
|
#[cfg(feature = "bevy_ui")]
|
|
|
|
|
pub use crate::ui::prelude::*;
|
2020-10-01 20:04:06 +00:00
|
|
|
|
2021-04-27 18:29:33 +00:00
|
|
|
#[doc(hidden)]
|
2020-10-01 20:04:06 +00:00
|
|
|
#[cfg(feature = "bevy_dynamic_plugin")]
|
|
|
|
|
pub use crate::dynamic_plugin::*;
|
2021-01-03 19:36:42 +00:00
|
|
|
|
2021-04-27 18:29:33 +00:00
|
|
|
#[doc(hidden)]
|
2021-01-03 19:36:42 +00:00
|
|
|
#[cfg(feature = "bevy_gilrs")]
|
|
|
|
|
pub use crate::gilrs::*;
|
