mirror of
https://github.com/bevyengine/bevy
synced 2024-11-10 07:04:33 +00:00
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:
parent
fd743ec57f
commit
8a8293b266
9 changed files with 64 additions and 25 deletions
|
@ -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);
|
||||
|
|
|
@ -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());
|
||||
}
|
||||
});
|
||||
|
|
|
@ -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)
|
||||
}
|
||||
}
|
||||
|
||||
|
|
|
@ -32,6 +32,6 @@ impl<'de> Visitor<'de> for EntityVisitor {
|
|||
where
|
||||
E: serde::de::Error,
|
||||
{
|
||||
Ok(Entity::new(v))
|
||||
Ok(Entity::from_raw(v))
|
||||
}
|
||||
}
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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));
|
||||
|
|
|
@ -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 {
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -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))
|
||||
}
|
||||
}
|
||||
|
|
Loading…
Reference in a new issue