Renamed Entity::new to Entity::from_raw (#3465)

# Objective

- Rename `Entity::new(id: u32)` to `Entity::from_raw(id: u32)`.
- Add further documentation.
- fixes #3108

## Solution

- Renamed `Entity::new(id: u32)` to `Entity::from_raw(id: u32)`.
- Docs extended.

I derived the examples from the discussion of issue #3108 .

The [first case](https://github.com/bevyengine/bevy/issues/3108#issuecomment-966669781) mentioned in the linked issue is quite obvious but the [second one](https://github.com/bevyengine/bevy/issues/3108#issuecomment-967093902) probably needs further explanation.


Co-authored-by: r4gus <david@thesugar.de>
This commit is contained in:
David Sugar 2021-12-29 20:49:00 +00:00
parent fd743ec57f
commit 8a8293b266
9 changed files with 64 additions and 25 deletions

View file

@ -250,7 +250,7 @@ fn get_or_spawn(criterion: &mut Criterion) {
let mut commands = Commands::new(&mut command_queue, &world);
for i in 0..10_000 {
commands
.get_or_spawn(Entity::new(i))
.get_or_spawn(Entity::from_raw(i))
.insert_bundle((Matrix::default(), Vec3::default()));
}
command_queue.apply(&mut world);
@ -265,7 +265,7 @@ fn get_or_spawn(criterion: &mut Criterion) {
let mut commands = Commands::new(&mut command_queue, &world);
let mut values = Vec::with_capacity(10_000);
for i in 0..10_000 {
values.push((Entity::new(i), (Matrix::default(), Vec3::default())));
values.push((Entity::from_raw(i), (Matrix::default(), Vec3::default())));
}
commands.insert_or_spawn_batch(values);
command_queue.apply(&mut world);

View file

@ -37,7 +37,7 @@ fn world_entity(criterion: &mut Criterion) {
bencher.iter(|| {
for i in 0..entity_count {
let entity = Entity::new(i);
let entity = Entity::from_raw(i);
black_box(world.entity(entity));
}
});
@ -58,7 +58,7 @@ fn world_get(criterion: &mut Criterion) {
bencher.iter(|| {
for i in 0..entity_count {
let entity = Entity::new(i);
let entity = Entity::from_raw(i);
assert!(world.get::<Table>(entity).is_some());
}
});
@ -68,7 +68,7 @@ fn world_get(criterion: &mut Criterion) {
bencher.iter(|| {
for i in 0..entity_count {
let entity = Entity::new(i);
let entity = Entity::from_raw(i);
assert!(world.get::<Sparse>(entity).is_some());
}
});
@ -90,7 +90,7 @@ fn world_query_get(criterion: &mut Criterion) {
bencher.iter(|| {
for i in 0..entity_count {
let entity = Entity::new(i);
let entity = Entity::from_raw(i);
assert!(query.get(&world, entity).is_ok());
}
});
@ -101,7 +101,7 @@ fn world_query_get(criterion: &mut Criterion) {
bencher.iter(|| {
for i in 0..entity_count {
let entity = Entity::new(i);
let entity = Entity::from_raw(i);
assert!(query.get(&world, entity).is_ok());
}
});

View file

@ -57,15 +57,54 @@ pub enum AllocAtWithoutReplacement {
}
impl Entity {
/// Creates a new entity reference with a generation of 0.
/// Creates a new entity reference with the specified `id` and a generation of 0.
///
/// # Note
///
/// Spawning a specific `entity` value is rarely the right choice. Most apps should favor
/// Spawning a specific `entity` value is __rarely the right choice__. Most apps should favor
/// [`Commands::spawn`](crate::system::Commands::spawn). This method should generally
/// only be used for sharing entities across apps, and only when they have a scheme
/// worked out to share an ID space (which doesn't happen by default).
pub fn new(id: u32) -> Entity {
///
/// In general, one should not try to synchronize the ECS by attempting to ensure that
/// `Entity` lines up between instances, but instead insert a secondary identifier as
/// a component.
///
/// There are still some use cases where it might be appropriate to use this function
/// externally.
///
/// ## Examples
///
/// Initializing a collection (e.g. `array` or `Vec`) with a known size:
///
/// ```no_run
/// # use bevy_ecs::prelude::*;
/// // Create a new array of size 10 and initialize it with (invalid) entities.
/// let mut entities: [Entity; 10] = [Entity::from_raw(0); 10];
///
/// // ... replace the entities with valid ones.
/// ```
///
/// Deriving `Reflect` for a component that has an `Entity` field:
///
/// ```no_run
/// # use bevy_ecs::{prelude::*, component::*};
/// # use bevy_reflect::Reflect;
/// #[derive(Reflect, Component)]
/// #[reflect(Component)]
/// pub struct MyStruct {
/// pub entity: Entity,
/// }
///
/// impl FromWorld for MyStruct {
/// fn from_world(_world: &mut World) -> Self {
/// Self {
/// entity: Entity::from_raw(u32::MAX),
/// }
/// }
/// }
/// ```
pub fn from_raw(id: u32) -> Entity {
Entity { id, generation: 0 }
}
@ -120,7 +159,7 @@ impl SparseSetIndex for Entity {
}
fn get_sparse_set_index(value: usize) -> Self {
Entity::new(value as u32)
Entity::from_raw(value as u32)
}
}

View file

@ -32,6 +32,6 @@ impl<'de> Visitor<'de> for EntityVisitor {
where
E: serde::de::Error,
{
Ok(Entity::new(v))
Ok(Entity::from_raw(v))
}
}

View file

@ -1307,8 +1307,8 @@ mod tests {
let mut world_a = World::new();
let world_b = World::new();
let mut query = world_a.query::<&A>();
let _ = query.get(&world_a, Entity::new(0));
let _ = query.get(&world_b, Entity::new(0));
let _ = query.get(&world_a, Entity::from_raw(0));
let _ = query.get(&world_b, Entity::from_raw(0));
}
#[test]
@ -1531,7 +1531,7 @@ mod tests {
fn insert_or_spawn_batch() {
let mut world = World::default();
let e0 = world.spawn().insert(A(0)).id();
let e1 = Entity::new(1);
let e1 = Entity::from_raw(1);
let values = vec![(e0, (B(0), C)), (e1, (B(1), C))];
@ -1568,7 +1568,7 @@ mod tests {
fn insert_or_spawn_batch_invalid() {
let mut world = World::default();
let e0 = world.spawn().insert(A(0)).id();
let e1 = Entity::new(1);
let e1 = Entity::from_raw(1);
let e2 = world.spawn().id();
let invalid_e2 = Entity {
generation: 1,

View file

@ -448,11 +448,11 @@ mod tests {
#[test]
fn sparse_set() {
let mut set = SparseSet::<Entity, Foo>::default();
let e0 = Entity::new(0);
let e1 = Entity::new(1);
let e2 = Entity::new(2);
let e3 = Entity::new(3);
let e4 = Entity::new(4);
let e0 = Entity::from_raw(0);
let e1 = Entity::from_raw(1);
let e2 = Entity::from_raw(2);
let e3 = Entity::from_raw(3);
let e4 = Entity::from_raw(4);
set.insert(e1, Foo(1));
set.insert(e2, Foo(2));

View file

@ -540,7 +540,7 @@ mod tests {
let columns = &[component_id];
let mut table = Table::with_capacity(0, columns.len());
table.add_column(components.get_info(component_id).unwrap());
let entities = (0..200).map(Entity::new).collect::<Vec<_>>();
let entities = (0..200).map(Entity::from_raw).collect::<Vec<_>>();
for entity in entities.iter() {
// SAFE: we allocate and immediately set data afterwards
unsafe {

View file

@ -87,7 +87,7 @@ impl DynamicScene {
// or spawn a new entity with a transiently unique id if there is
// no corresponding entry.
let entity = *entity_map
.entry(bevy_ecs::entity::Entity::new(scene_entity.entity))
.entry(bevy_ecs::entity::Entity::from_raw(scene_entity.entity))
.or_insert_with(|| world.spawn().id());
// Apply/ add each component to the given entity.

View file

@ -17,7 +17,7 @@ pub struct Parent(pub Entity);
// better ways to handle cases like this.
impl FromWorld for Parent {
fn from_world(_world: &mut World) -> Self {
Parent(Entity::new(u32::MAX))
Parent(Entity::from_raw(u32::MAX))
}
}
@ -56,6 +56,6 @@ impl MapEntities for PreviousParent {
// TODO: Better handle this case see `impl FromWorld for Parent`
impl FromWorld for PreviousParent {
fn from_world(_world: &mut World) -> Self {
PreviousParent(Entity::new(u32::MAX))
PreviousParent(Entity::from_raw(u32::MAX))
}
}