bevy/crates/bevy_ecs/src/world
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_ref.rs bevy_ecs: add untyped methods for inserting components and bundles (#7204) 2023-03-21 00:33:11 +00:00
error.rs Add World::try_run_schedule (#8028) 2023-03-17 01:22:54 +00:00
identifier.rs Use UnsafeWorldCell to increase code quality for SystemParam (#8174) 2023-04-01 15:45:07 +00:00
mod.rs Miscellaneous cleanups to World::resource_scope (#8256) 2023-03-30 10:17:08 +00:00
spawn_batch.rs Increase type safety and clarity for change detection (#7905) 2023-03-09 17:17:02 +00:00
unsafe_world_cell.rs Use UnsafeWorldCell to increase code quality for SystemParam (#8174) 2023-04-01 15:45:07 +00:00
world_cell.rs Move all logic to UnsafeWorldCell (#7381) 2023-02-06 19:02:52 +00:00