diff --git a/benches/benches/bevy_ecs/commands.rs b/benches/benches/bevy_ecs/commands.rs
index c4d974238dadb..3d78a16decdf2 100644
--- a/benches/benches/bevy_ecs/commands.rs
+++ b/benches/benches/bevy_ecs/commands.rs
@@ -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);
diff --git a/benches/benches/bevy_ecs/world_get.rs b/benches/benches/bevy_ecs/world_get.rs
index fc943ede4742f..0cc420e2b3504 100644
--- a/benches/benches/bevy_ecs/world_get.rs
+++ b/benches/benches/bevy_ecs/world_get.rs
@@ -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::
(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::(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());
}
});
diff --git a/crates/bevy_ecs/src/entity/mod.rs b/crates/bevy_ecs/src/entity/mod.rs
index c74974d7a4457..85e2e4a263a8b 100644
--- a/crates/bevy_ecs/src/entity/mod.rs
+++ b/crates/bevy_ecs/src/entity/mod.rs
@@ -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)
}
}
diff --git a/crates/bevy_ecs/src/entity/serde.rs b/crates/bevy_ecs/src/entity/serde.rs
index 5c589bda4d200..94b46468c231c 100644
--- a/crates/bevy_ecs/src/entity/serde.rs
+++ b/crates/bevy_ecs/src/entity/serde.rs
@@ -32,6 +32,6 @@ impl<'de> Visitor<'de> for EntityVisitor {
where
E: serde::de::Error,
{
- Ok(Entity::new(v))
+ Ok(Entity::from_raw(v))
}
}
diff --git a/crates/bevy_ecs/src/lib.rs b/crates/bevy_ecs/src/lib.rs
index dfccb44440db5..30d70ca17efab 100644
--- a/crates/bevy_ecs/src/lib.rs
+++ b/crates/bevy_ecs/src/lib.rs
@@ -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,
diff --git a/crates/bevy_ecs/src/storage/sparse_set.rs b/crates/bevy_ecs/src/storage/sparse_set.rs
index ef0ab475507a2..ed11fdc65859c 100644
--- a/crates/bevy_ecs/src/storage/sparse_set.rs
+++ b/crates/bevy_ecs/src/storage/sparse_set.rs
@@ -448,11 +448,11 @@ mod tests {
#[test]
fn sparse_set() {
let mut set = SparseSet::::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));
diff --git a/crates/bevy_ecs/src/storage/table.rs b/crates/bevy_ecs/src/storage/table.rs
index d4bd5b471f1b9..2d5c39eef02dd 100644
--- a/crates/bevy_ecs/src/storage/table.rs
+++ b/crates/bevy_ecs/src/storage/table.rs
@@ -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::>();
+ let entities = (0..200).map(Entity::from_raw).collect::>();
for entity in entities.iter() {
// SAFE: we allocate and immediately set data afterwards
unsafe {
diff --git a/crates/bevy_scene/src/dynamic_scene.rs b/crates/bevy_scene/src/dynamic_scene.rs
index 194590fd1c995..ab15cbd61dbdd 100644
--- a/crates/bevy_scene/src/dynamic_scene.rs
+++ b/crates/bevy_scene/src/dynamic_scene.rs
@@ -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.
diff --git a/crates/bevy_transform/src/components/parent.rs b/crates/bevy_transform/src/components/parent.rs
index c594d4c4dae2d..5f03dc06535c6 100644
--- a/crates/bevy_transform/src/components/parent.rs
+++ b/crates/bevy_transform/src/components/parent.rs
@@ -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))
}
}