diff --git a/crates/bevy_ecs/src/world/entity_ref.rs b/crates/bevy_ecs/src/world/entity_ref.rs index 4303c5f55e..00cadfb8c9 100644 --- a/crates/bevy_ecs/src/world/entity_ref.rs +++ b/crates/bevy_ecs/src/world/entity_ref.rs @@ -602,7 +602,11 @@ impl<'w> EntityMut<'w> { /// /// # Safety /// - /// - `T` must be a mutable component + /// - One of the following should be true: + /// - Either `T` is mutable, or + /// - `OnReplace` hooks and observers for that component on that entity should trigger immediately before the mutation + /// and `OnInsert` should trigger immediately after the mutation, or + /// - The user should uphold documented invariants of `T`. If no such documentation provided, it is impossible for the end user to uphold this. #[inline] pub unsafe fn get_mut_assume_mutable(&mut self) -> Option> { // SAFETY: @@ -1472,7 +1476,11 @@ impl<'w> EntityWorldMut<'w> { /// /// # Safety /// - /// - `T` must be a mutable component + /// - One of the following should be true: + /// - Either `T` is mutable, or + /// - `OnReplace` hooks and observers for that component on that entity should trigger immediately before the mutation + /// and `OnInsert` should trigger immediately after the mutation, or + /// - The user should uphold documented invariants of `T`. If no such documentation provided, it is impossible for the end user to uphold this. #[inline] pub unsafe fn get_mut_assume_mutable(&mut self) -> Option> { self.as_mutable().into_mut_assume_mutable() @@ -3851,7 +3859,11 @@ impl<'w> FilteredEntityMut<'w> { /// /// # Safety /// - /// - `T` must be a mutable component + /// - One of the following should be true: + /// - Either `T` is mutable, or + /// - `OnReplace` hooks and observers for that component on that entity should trigger immediately before the mutation + /// and `OnInsert` should trigger immediately after the mutation, or + /// - The user should uphold documented invariants of `T`. If no such documentation provided, it is impossible for the end user to uphold this. #[inline] pub unsafe fn into_mut_assume_mutable(self) -> Option> { let id = self diff --git a/crates/bevy_ecs/src/world/unsafe_world_cell.rs b/crates/bevy_ecs/src/world/unsafe_world_cell.rs index 38d4333843..bd3b3a4106 100644 --- a/crates/bevy_ecs/src/world/unsafe_world_cell.rs +++ b/crates/bevy_ecs/src/world/unsafe_world_cell.rs @@ -948,7 +948,11 @@ impl<'w> UnsafeEntityCell<'w> { /// It is the caller's responsibility to ensure that /// - the [`UnsafeEntityCell`] has permission to access the component mutably /// - no other references to the component exist at the same time - /// - the component `T` is mutable + /// - One of the following should be true: + /// - Either `T` is mutable, or + /// - `OnReplace` hooks and observers for that component on that entity should trigger immediately before the mutation + /// and `OnInsert` should trigger immediately after the mutation, or + /// - The user should uphold documented invariants of `T`. If no such documentation provided, it is impossible for the end user to uphold this. #[inline] pub unsafe fn get_mut_assume_mutable(self) -> Option> { // SAFETY: same safety requirements @@ -959,7 +963,11 @@ impl<'w> UnsafeEntityCell<'w> { /// It is the caller's responsibility to ensure that /// - the [`UnsafeEntityCell`] has permission to access the component mutably /// - no other references to the component exist at the same time - /// - The component `T` is mutable + /// - One of the following should be true: + /// - Either `T` is mutable, or + /// - `OnReplace` hooks and observers for that component on that entity should trigger immediately before the mutation + /// and `OnInsert` should trigger immediately after the mutation, or + /// - The user should uphold documented invariants of `T`. If no such documentation provided, it is impossible for the end user to uphold this. #[inline] pub(crate) unsafe fn get_mut_using_ticks_assume_mutable( &self,