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 access change detection from immutable query methods, as opposed
to &mut T
which only provides access to change detection from mutable query methods.
#[derive(Component, Clone, Debug)]
struct Name(String);
#[derive(Component, Clone, Copy, Debug)]
struct Health(f32);
fn my_system(mut query: Query<(Mut<Name>, &mut Health)>) {
// Mutable access provides change detection information for both parameters:
// - `name` has type `Mut<Name>`
// - `health` has type `Mut<Health>`
for (name, health) in query.iter_mut() {
println!("Name: {:?} (last changed {:?})", name, name.last_changed());
println!("Health: {:?} (last changed: {:?})", health, health.last_changed());
}
// Immutable access only provides change detection for `Name`:
// - `name` has type `Ref<Name>`
// - `health` has type `&Health`
for (name, health) in query.iter() {
println!("Name: {:?} (last changed {:?})", name, name.last_changed());
println!("Health: {:?}", health);
}
}
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,
caller: MaybeLocation<&'w mut &'static Location<'static>>,
) -> Self
pub fn new( value: &'w mut T, added: &'w mut Tick, last_changed: &'w mut Tick, last_run: Tick, this_run: Tick, caller: MaybeLocation<&'w mut &'static Location<'static>>, ) -> 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);
}
}
Sourcepub fn filter_map_unchanged<U: ?Sized>(
self,
f: impl FnOnce(&mut T) -> Option<&mut U>,
) -> Option<Mut<'w, U>>
pub fn filter_map_unchanged<U: ?Sized>( self, f: impl FnOnce(&mut T) -> Option<&mut U>, ) -> Option<Mut<'w, U>>
Optionally maps to an inner value by applying a function to the contained reference.
This is useful in a situation where you need to convert a Mut<T>
to a Mut<U>
, but only if T
contains U
.
As with map_unchanged
, you should never modify the argument passed to the closure.
Sourcepub fn try_map_unchanged<U: ?Sized, E>(
self,
f: impl FnOnce(&mut T) -> Result<&mut U, E>,
) -> Result<Mut<'w, U>, E>
pub fn try_map_unchanged<U: ?Sized, E>( self, f: impl FnOnce(&mut T) -> Result<&mut U, E>, ) -> Result<Mut<'w, U>, E>
Optionally maps to an inner value by applying a function to the contained reference, returns an error on failure.
This is useful in a situation where you need to convert a Mut<T>
to a Mut<U>
, but only if T
contains U
.
As with map_unchanged
, you should never modify the argument passed to the closure.
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§fn changed_by(&self) -> MaybeLocation
fn changed_by(&self) -> MaybeLocation
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 set_last_added(&mut self, last_added: Tick)
fn set_last_added(&mut self, last_added: Tick)
Source§fn bypass_change_detection(&mut self) -> &mut Self::Inner
fn bypass_change_detection(&mut self) -> &mut Self::Inner
Source§fn set_if_neq(&mut self, value: Self::Inner) -> bool
fn set_if_neq(&mut self, value: Self::Inner) -> bool
*self != value
.
Returns true
if the value was overwritten, and returns false
if it was not. Read moreSource§fn replace_if_neq(&mut self, value: Self::Inner) -> Option<Self::Inner>
fn replace_if_neq(&mut self, value: Self::Inner) -> Option<Self::Inner>
*self != value
,
returning the previous value if this occurs. Read moreSource§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<Mutability = Mutable>> QueryData for Mut<'__w, T>
impl<'__w, T: Component<Mutability = Mutable>> QueryData for Mut<'__w, T>
Source§const IS_READ_ONLY: bool = false
const IS_READ_ONLY: bool = false
Source§type ReadOnly = Ref<'__w, T>
type ReadOnly = Ref<'__w, T>
QueryData
, which satisfies the ReadOnlyQueryData
trait.Source§type Item<'w, 's> = Mut<'w, T>
type Item<'w, 's> = Mut<'w, T>
WorldQuery
This will be the data retrieved by the query,
and is visible to the end user when calling e.g. Query<Self>::get
.Source§fn shrink<'wlong: 'wshort, 'wshort, 's>(
item: Self::Item<'wlong, 's>,
) -> Self::Item<'wshort, 's>
fn shrink<'wlong: 'wshort, 'wshort, 's>( item: Self::Item<'wlong, 's>, ) -> Self::Item<'wshort, 's>
Source§unsafe fn fetch<'w, 's>(
state: &'s Self::State,
fetch: &mut Self::Fetch<'w>,
entity: Entity,
table_row: TableRow,
) -> Self::Item<'w, 's>
unsafe fn fetch<'w, 's>( state: &'s Self::State, fetch: &mut Self::Fetch<'w>, entity: Entity, table_row: TableRow, ) -> Self::Item<'w, 's>
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 an entity
in the current archetype.
Accesses components registered in WorldQuery::update_component_access
. Read moreSource§fn provide_extra_access(
_state: &mut Self::State,
_access: &mut Access,
_available_access: &Access,
)
fn provide_extra_access( _state: &mut Self::State, _access: &mut Access, _available_access: &Access, )
update_component_access
.
Implementations may add additional access that is a subset of available_access
and does not conflict with anything in access
,
and must update access
to include that access. Read moreSource§impl<T: Component<Mutability = Mutable>> ReleaseStateQueryData for Mut<'_, T>
impl<T: Component<Mutability = Mutable>> ReleaseStateQueryData for Mut<'_, T>
Source§fn release_state<'w>(item: Self::Item<'w, '_>) -> Self::Item<'w, 'static>
fn release_state<'w>(item: Self::Item<'w, '_>) -> Self::Item<'w, 'static>
'static
state lifetime.Source§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.
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
adds 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.
Source§const IS_DENSE: bool = <&mut T as WorldQuery>::IS_DENSE
const IS_DENSE: bool = <&mut T as WorldQuery>::IS_DENSE
Source§type Fetch<'w> = WriteFetch<'w, T>
type Fetch<'w> = WriteFetch<'w, T>
WorldQuery
to compute Self::Item
for each entity.Source§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_fetch<'wlong: 'wshort, 'wshort>(
fetch: Self::Fetch<'wlong>,
) -> Self::Fetch<'wshort>
fn shrink_fetch<'wlong: 'wshort, 'wshort>( fetch: Self::Fetch<'wlong>, ) -> Self::Fetch<'wshort>
Source§unsafe fn init_fetch<'w, 's>(
world: UnsafeWorldCell<'w>,
state: &ComponentId,
last_run: Tick,
this_run: Tick,
) -> WriteFetch<'w, T>
unsafe fn init_fetch<'w, 's>( world: UnsafeWorldCell<'w>, state: &ComponentId, last_run: Tick, this_run: Tick, ) -> WriteFetch<'w, T>
Self::Fetch
,
by combining data from the World
with the cached Self::State
.
Readonly accesses resources registered in WorldQuery::update_component_access
. Read moreSource§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§fn update_component_access(
component_id: &ComponentId,
access: &mut FilteredAccess,
)
fn update_component_access( component_id: &ComponentId, access: &mut FilteredAccess, )
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
Auto 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>
, which can then be
downcast
into Box<dyn 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>
, which 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.Source§impl<T> DowncastSend for T
impl<T> DowncastSend for T
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
Source§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
Source§impl<T> IntoResult<T> for T
impl<T> IntoResult<T> for T
Source§fn into_result(self) -> Result<T, RunSystemError>
fn into_result(self) -> Result<T, RunSystemError>
Source§impl<R> Rng for R
impl<R> Rng for R
Source§fn random<T>(&mut self) -> Twhere
StandardUniform: Distribution<T>,
fn random<T>(&mut self) -> Twhere
StandardUniform: Distribution<T>,
StandardUniform
distribution. Read moreSource§fn random_iter<T>(self) -> Iter<StandardUniform, Self, T>
fn random_iter<T>(self) -> Iter<StandardUniform, Self, T>
Source§fn random_range<T, R>(&mut self, range: R) -> Twhere
T: SampleUniform,
R: SampleRange<T>,
fn random_range<T, R>(&mut self, range: R) -> Twhere
T: SampleUniform,
R: SampleRange<T>,
Source§fn random_bool(&mut self, p: f64) -> bool
fn random_bool(&mut self, p: f64) -> bool
p
of being true. Read moreSource§fn random_ratio(&mut self, numerator: u32, denominator: u32) -> bool
fn random_ratio(&mut self, numerator: u32, denominator: u32) -> bool
numerator/denominator
of being
true. Read moreSource§fn sample<T, D>(&mut self, distr: D) -> Twhere
D: Distribution<T>,
fn sample<T, D>(&mut self, distr: D) -> Twhere
D: Distribution<T>,
Source§fn sample_iter<T, D>(self, distr: D) -> Iter<D, Self, T>where
D: Distribution<T>,
Self: Sized,
fn sample_iter<T, D>(self, distr: D) -> Iter<D, Self, T>where
D: Distribution<T>,
Self: Sized,
Source§fn gen<T>(&mut self) -> Twhere
StandardUniform: Distribution<T>,
fn gen<T>(&mut self) -> Twhere
StandardUniform: Distribution<T>,
random
to avoid conflict with the new gen
keyword in Rust 2024.Rng::random
.Source§fn gen_range<T, R>(&mut self, range: R) -> Twhere
T: SampleUniform,
R: SampleRange<T>,
fn gen_range<T, R>(&mut self, range: R) -> Twhere
T: SampleUniform,
R: SampleRange<T>,
random_range
Rng::random_range
.Source§impl<R> TryRngCore for R
impl<R> TryRngCore for R
Source§type Error = Infallible
type Error = Infallible
Source§fn try_next_u32(&mut self) -> Result<u32, <R as TryRngCore>::Error>
fn try_next_u32(&mut self) -> Result<u32, <R as TryRngCore>::Error>
u32
.Source§fn try_next_u64(&mut self) -> Result<u64, <R as TryRngCore>::Error>
fn try_next_u64(&mut self) -> Result<u64, <R as TryRngCore>::Error>
u64
.Source§fn try_fill_bytes(
&mut self,
dst: &mut [u8],
) -> Result<(), <R as TryRngCore>::Error>
fn try_fill_bytes( &mut self, dst: &mut [u8], ) -> Result<(), <R as TryRngCore>::Error>
dest
entirely with random data.Source§fn unwrap_mut(&mut self) -> UnwrapMut<'_, Self>
fn unwrap_mut(&mut self) -> UnwrapMut<'_, Self>
UnwrapMut
wrapper.Source§fn read_adapter(&mut self) -> RngReadAdapter<'_, Self>where
Self: Sized,
fn read_adapter(&mut self) -> RngReadAdapter<'_, Self>where
Self: Sized,
RngCore
to a RngReadAdapter
.