bevy/crates/bevy_ecs/src
JoJoJet 3442a13d2c
Use UnsafeWorldCell to increase code quality for SystemParam (#8174)
# Objective

The type `&World` is currently in an awkward place, since it has two
meanings:
1. Read-only access to the entire world.
2. Interior mutable access to the world; immutable and/or mutable access
to certain portions of world data.

This makes `&World` difficult to reason about, and surprising to see in
function signatures if one does not know about the interior mutable
property.

The type `UnsafeWorldCell` was added in #6404, which is meant to
alleviate this confusion by adding a dedicated type for interior mutable
world access. However, much of the engine still treats `&World` as an
interior mutable-ish type. One of those places is `SystemParam`.

## Solution

Modify `SystemParam::get_param` to accept `UnsafeWorldCell` instead of
`&World`. Simplify the safety invariants, since the `UnsafeWorldCell`
type encapsulates the concept of constrained world access.

---

## Changelog

`SystemParam::get_param` now accepts an `UnsafeWorldCell` instead of
`&World`. This type provides a high-level API for unsafe interior
mutable world access.

## Migration Guide

For manual implementers of `SystemParam`: the function `get_item` now
takes `UnsafeWorldCell` instead of `&World`. To access world data, use:

* `.get_entity()`, which returns an `UnsafeEntityCell` which can be used
to access component data.
* `get_resource()` and its variants, to access resource data.
2023-04-01 15:45:07 +00:00
..
entity Remove redundant bounds check in Entities::get (#8108) 2023-03-16 22:49:36 +00:00
query Fix inaccurate documentation on `QueryState::for_each_unchecked (#8277) 2023-03-31 16:54:36 +00:00
schedule Replace some unsafe system executor code with safe code (#8274) 2023-03-31 21:56:49 +00:00
storage Increase type safety and clarity for change detection (#7905) 2023-03-09 17:17:02 +00:00
system Use UnsafeWorldCell to increase code quality for SystemParam (#8174) 2023-04-01 15:45:07 +00:00
world Use UnsafeWorldCell to increase code quality for SystemParam (#8174) 2023-04-01 15:45:07 +00:00
archetype.rs Document bevy_ecs::storage (#7770) 2023-03-09 07:22:48 +00:00
bundle.rs Reduce branching when inserting components (#8053) 2023-03-21 20:37:25 +00:00
change_detection.rs Improve documentation for set_if_neq (#8254) 2023-03-30 15:43:13 +00:00
component.rs Increase type safety and clarity for change detection (#7905) 2023-03-09 17:17:02 +00:00
event.rs docs: update docs and comments that still refer to stages (#8156) 2023-03-27 21:50:21 +00:00
lib.rs Schedule-First: the new and improved add_systems (#8079) 2023-03-18 01:45:34 +00:00
reflect.rs Bugfix: Scene reload fix (nonbreaking) (#7951) 2023-03-27 22:18:45 +00:00
removal_detection.rs Use UnsafeWorldCell to increase code quality for SystemParam (#8174) 2023-04-01 15:45:07 +00:00