Struct bevy_ecs::change_detection::Mut
source · pub struct Mut<'w, T: ?Sized> { /* private fields */ }
Expand description
Unique mutable borrow of an entity’s component or of a resource.
This can be used in queries to opt into change detection on both their mutable and immutable forms, as opposed to
&mut T
, which only provides access to change detection while in its mutable form:
#[derive(Component, Clone)]
struct Name(String);
#[derive(Component, Clone, Copy)]
struct Health(f32);
#[derive(Component, Clone, Copy)]
struct Position {
x: f32,
y: f32,
};
#[derive(Component, Clone, Copy)]
struct Player {
id: usize,
};
#[derive(QueryData)]
#[query_data(mutable)]
struct PlayerQuery {
id: &'static Player,
// Reacting to `PlayerName` changes is expensive, so we need to enable change detection when reading it.
name: Mut<'static, Name>,
health: &'static mut Health,
position: &'static mut Position,
}
fn update_player_avatars(players_query: Query<PlayerQuery>) {
// The item returned by the iterator is of type `PlayerQueryReadOnlyItem`.
for player in players_query.iter() {
if player.name.is_changed() {
// Update the player's name. This clones a String, and so is more expensive.
update_player_name(player.id, player.name.clone());
}
// Update the health bar.
update_player_health(player.id, *player.health);
// Update the player's position.
update_player_position(player.id, *player.position);
}
}
Implementations§
source§impl<'w, T: ?Sized> Mut<'w, T>
impl<'w, T: ?Sized> Mut<'w, T>
sourcepub fn new(
value: &'w mut T,
added: &'w mut Tick,
last_changed: &'w mut Tick,
last_run: Tick,
this_run: Tick
) -> Self
pub fn new( value: &'w mut T, added: &'w mut Tick, last_changed: &'w mut Tick, last_run: Tick, this_run: Tick ) -> Self
Creates a new change-detection enabled smart pointer.
In almost all cases you do not need to call this method manually,
as instances of Mut
will be created by engine-internal code.
Many use-cases of this method would be better served by Mut::map_unchanged
or Mut::reborrow
.
value
- The value wrapped by this smart pointer.added
- ATick
that stores the tick when the wrapped value was created.last_changed
- ATick
that stores the last time the wrapped value was changed. This will be updated to the value ofchange_tick
if the returned smart pointer is modified.last_run
- ATick
, occurring beforethis_run
, which is used as a reference to determine whether the wrapped value is newly added or changed.this_run
- ATick
corresponding to the current point in time – “now”.
source§impl<'w, T: ?Sized> Mut<'w, T>
impl<'w, T: ?Sized> Mut<'w, T>
sourcepub fn into_inner(self) -> &'w mut T
pub fn into_inner(self) -> &'w mut T
Consume self
and return a mutable reference to the
contained value while marking self
as “changed”.
sourcepub fn reborrow(&mut self) -> Mut<'_, T>
pub fn reborrow(&mut self) -> Mut<'_, T>
Returns a Mut<>
with a smaller lifetime.
This is useful if you have &mut Mut <T>
, but you need a Mut<T>
.
sourcepub fn map_unchanged<U: ?Sized>(
self,
f: impl FnOnce(&mut T) -> &mut U
) -> Mut<'w, U>
pub fn map_unchanged<U: ?Sized>( self, f: impl FnOnce(&mut T) -> &mut U ) -> Mut<'w, U>
Maps to an inner value by applying a function to the contained reference, without flagging a change.
You should never modify the argument passed to the closure – if you want to modify the data
without flagging a change, consider using DetectChangesMut::bypass_change_detection
to make your intent explicit.
// When run, zeroes the translation of every entity.
fn reset_positions(mut transforms: Query<&mut Transform>) {
for transform in &mut transforms {
// We pinky promise not to modify `t` within the closure.
// Breaking this promise will result in logic errors, but will never cause undefined behavior.
let mut translation = transform.map_unchanged(|t| &mut t.translation);
// Only reset the translation if it isn't already zero;
translation.set_if_neq(Vec2::ZERO);
}
}
Trait Implementations§
source§impl<'w, T: ?Sized> DetectChanges for Mut<'w, T>
impl<'w, T: ?Sized> DetectChanges for Mut<'w, T>
source§fn is_changed(&self) -> bool
fn is_changed(&self) -> bool
true
if this value was added or mutably dereferenced
either since the last time the system ran or, if the system never ran,
since the beginning of the program. Read moresource§fn last_changed(&self) -> Tick
fn last_changed(&self) -> Tick
source§impl<'w, T: ?Sized> DetectChangesMut for Mut<'w, T>
impl<'w, T: ?Sized> DetectChangesMut for Mut<'w, T>
source§fn set_changed(&mut self)
fn set_changed(&mut self)
source§fn set_last_changed(&mut self, last_changed: Tick)
fn set_last_changed(&mut self, last_changed: Tick)
source§fn bypass_change_detection(&mut self) -> &mut Self::Inner
fn bypass_change_detection(&mut self) -> &mut Self::Inner
source§impl<'w, T> From<Mut<'w, T>> for MutUntyped<'w>
impl<'w, T> From<Mut<'w, T>> for MutUntyped<'w>
source§impl<'w, T: 'static> From<NonSendMut<'w, T>> for Mut<'w, T>
impl<'w, T: 'static> From<NonSendMut<'w, T>> for Mut<'w, T>
source§fn from(other: NonSendMut<'w, T>) -> Mut<'w, T>
fn from(other: NonSendMut<'w, T>) -> Mut<'w, T>
Convert this NonSendMut
into a Mut
. This allows keeping the change-detection feature of Mut
while losing the specificity of NonSendMut
.
source§impl<'w, 'a, T> IntoIterator for &'a Mut<'w, T>where
&'a T: IntoIterator,
impl<'w, 'a, T> IntoIterator for &'a Mut<'w, T>where
&'a T: IntoIterator,
source§impl<'w, 'a, T> IntoIterator for &'a mut Mut<'w, T>where
&'a mut T: IntoIterator,
impl<'w, 'a, T> IntoIterator for &'a mut Mut<'w, T>where
&'a mut T: IntoIterator,
source§impl<'__w, T: Component> QueryData for Mut<'__w, T>
impl<'__w, T: Component> QueryData for Mut<'__w, T>
§type ReadOnly = Ref<'__w, T>
type ReadOnly = Ref<'__w, T>
QueryData
, which satisfies the ReadOnlyQueryData
trait.source§impl<'__w, T: Component> WorldQuery for Mut<'__w, T>
impl<'__w, T: Component> WorldQuery for Mut<'__w, T>
When Mut<T>
is used in a query, it will be converted to Ref<T>
when transformed into its read-only form, providing access to change detection methods.
By contrast &mut T
will result in a Mut<T>
item in mutable form to record mutations, but result in a bare &T
in read-only form.
SAFETY:
fetch
accesses a single component mutably.
This is sound because update_component_access
and update_archetype_component_access
add write access for that component and panic when appropriate.
update_component_access
adds a With
filter for a component.
This is sound because matches_component_set
returns whether the set contains that component.
§type Item<'w> = Mut<'w, T>
type Item<'w> = Mut<'w, T>
WorldQuery
For QueryData
this will be the item returned by the query.
For QueryFilter
this will be either ()
, or a bool
indicating whether the entity should be included
or a tuple of such things.§type Fetch<'w> = WriteFetch<'w, T>
type Fetch<'w> = WriteFetch<'w, T>
WorldQuery
to fetch Self::Item
§type State = ComponentId
type State = ComponentId
Self::Fetch
. This will be cached inside QueryState
,
so it is best to move as much data / computation here as possible to reduce the cost of
constructing Self::Fetch
.source§fn shrink<'wlong: 'wshort, 'wshort>(item: Mut<'wlong, T>) -> Mut<'wshort, T>
fn shrink<'wlong: 'wshort, 'wshort>(item: Mut<'wlong, T>) -> Mut<'wshort, T>
source§unsafe fn init_fetch<'w>(
world: UnsafeWorldCell<'w>,
state: &ComponentId,
last_run: Tick,
this_run: Tick
) -> WriteFetch<'w, T>
unsafe fn init_fetch<'w>( world: UnsafeWorldCell<'w>, state: &ComponentId, last_run: Tick, this_run: Tick ) -> WriteFetch<'w, T>
source§const IS_DENSE: bool = <&mut T as WorldQuery>::IS_DENSE
const IS_DENSE: bool = <&mut T as WorldQuery>::IS_DENSE
WorldQuery::set_table
must be used before
WorldQuery::fetch
can be called for iterators. If this returns false,
WorldQuery::set_archetype
must be used before WorldQuery::fetch
can be called for
iterators.source§unsafe fn set_archetype<'w>(
fetch: &mut WriteFetch<'w, T>,
state: &ComponentId,
archetype: &'w Archetype,
table: &'w Table
)
unsafe fn set_archetype<'w>( fetch: &mut WriteFetch<'w, T>, state: &ComponentId, archetype: &'w Archetype, table: &'w Table )
Archetype
. This will always be called on
archetypes that match this WorldQuery
. Read moresource§unsafe fn set_table<'w>(
fetch: &mut WriteFetch<'w, T>,
state: &ComponentId,
table: &'w Table
)
unsafe fn set_table<'w>( fetch: &mut WriteFetch<'w, T>, state: &ComponentId, table: &'w Table )
Table
. This will always be called on tables
that match this WorldQuery
. Read moresource§unsafe fn fetch<'w>(
fetch: &mut Self::Fetch<'w>,
entity: Entity,
table_row: TableRow
) -> Mut<'w, T>
unsafe fn fetch<'w>( fetch: &mut Self::Fetch<'w>, entity: Entity, table_row: TableRow ) -> Mut<'w, T>
Self::Item
for either the given entity
in the current Table
,
or for the given entity
in the current Archetype
. This must always be called after
WorldQuery::set_table
with a table_row
in the range of the current Table
or after
WorldQuery::set_archetype
with a entity
in the current archetype. Read moresource§fn update_component_access(
component_id: &ComponentId,
access: &mut FilteredAccess<ComponentId>
)
fn update_component_access( component_id: &ComponentId, access: &mut FilteredAccess<ComponentId> )
source§fn init_state(world: &mut World) -> ComponentId
fn init_state(world: &mut World) -> ComponentId
State
for this WorldQuery
type.source§fn get_state(components: &Components) -> Option<ComponentId>
fn get_state(components: &Components) -> Option<ComponentId>
source§fn matches_component_set(
state: &ComponentId,
set_contains_id: &impl Fn(ComponentId) -> bool
) -> bool
fn matches_component_set( state: &ComponentId, set_contains_id: &impl Fn(ComponentId) -> bool ) -> bool
source§fn set_access(_state: &mut Self::State, _access: &FilteredAccess<ComponentId>)
fn set_access(_state: &mut Self::State, _access: &FilteredAccess<ComponentId>)
FilteredEntityRef
or FilteredEntityMut
. Read moreAuto Trait Implementations§
impl<'w, T> Freeze for Mut<'w, T>where
T: ?Sized,
impl<'w, T> RefUnwindSafe for Mut<'w, T>where
T: RefUnwindSafe + ?Sized,
impl<'w, T> Send for Mut<'w, T>
impl<'w, T> Sync for Mut<'w, T>
impl<'w, T> Unpin for Mut<'w, T>where
T: ?Sized,
impl<'w, T> !UnwindSafe for Mut<'w, T>
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
source§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
Box<dyn Trait>
(where Trait: Downcast
) to Box<dyn Any>
. Box<dyn Any>
can
then be further downcast
into Box<ConcreteType>
where ConcreteType
implements Trait
.source§fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
Rc<Trait>
(where Trait: Downcast
) to Rc<Any>
. Rc<Any>
can then be
further downcast
into Rc<ConcreteType>
where ConcreteType
implements Trait
.source§fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
&Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &Any
’s vtable from &Trait
’s.source§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &mut Any
’s vtable from &mut Trait
’s.