@@ -227,6 +227,11 @@ use core::{
227
227
/// # struct ComponentA;
228
228
/// # fn system(
229
229
/// // This will panic!
230
+ /// // EntityRef provides read access to ALL components on an entity.
231
+ /// // When combined with &mut ComponentA in the same query, it creates
232
+ /// // a conflict because EntityRef could read ComponentA while the &mut
233
+ /// // attempts to modify it - violating Rust's borrowing rules of no
234
+ /// // simultaneous read+write access.
230
235
/// query: Query<(EntityRef, &mut ComponentA)>
231
236
/// # ) {}
232
237
/// # bevy_ecs::system::assert_system_does_not_conflict(system);
@@ -239,11 +244,18 @@ use core::{
239
244
/// # struct ComponentB;
240
245
/// # fn system(
241
246
/// // This will not panic.
247
+ /// // This creates a perfect separation where:
248
+ /// // 1. First query reads entities that have ComponentA
249
+ /// // 2. Second query modifies ComponentB only on entities that DON'T have ComponentA
250
+ /// // Result: No entity can ever be accessed by both queries simultaneously
242
251
/// query_a: Query<EntityRef, With<ComponentA>>,
243
252
/// query_b: Query<&mut ComponentB, Without<ComponentA>>,
244
253
/// # ) {}
245
254
/// # bevy_ecs::system::assert_system_does_not_conflict(system);
246
255
/// ```
256
+ /// The fundamental rule: [`EntityRef`]'s ability to read all components means it can never
257
+ /// coexist with mutable access. With/Without filters guarantee this by keeping the
258
+ /// queries on completely separate entities.
247
259
///
248
260
/// # Accessing query items
249
261
///
0 commit comments