Remame Entity::new(id: u32) to from_raw

[alice-i-cecile]

What problem does this solve or what need does it fill?

Users are commonly confused by this method, and try and fail to use it for synchronization tasks.

What solution would you like?

Make this method pub(crate).

What alternative(s) have you considered?

Better document if and when it can be correctly used.

Additional context

Generally the advice when attempting to synchronize the ECS is to insert a secondary identifier as a component, rather than attempting to ensure that Entity lines up between the instances.

I have not seen any valid external use of this API, but if they exist, we should attempt to create workarounds or focus on the documentation path.

[mockersf]

This is currently used in scenes and in transforms. Transforms could probably be rework to not use it, but it seems harder for scenes.

[HackerFoo]

I use this method to initialize a known sizeVec<Entity> using

  let mut entities = vec![Entity::new(0); n];

that is then overwritten by index with valid entities for all indices, but in random order. This pattern is often used for building indices or sorting parallel vectors, where one vector is sorted and others are permuted in the same way.

I'd prefer to use Default::default() if it were implemented for Entity, which would give an always invalid Entity.

[mockersf]

Maybe related to #3029 which introduce the notion of an invalid entity

[Davier]

I have not seen any valid external use of this API, but if they exist, we should attempt to create workarounds or focus on the documentation path.

I use it externally when deriving Reflect for any component that has an Entity field (like in impl FromWorld for Parent)

[bjorn3]

Maybe rename new to from_raw?

[alice-i-cecile]

Maybe rename new to from_raw?

I like this, and think this is how we should proceed. A better name, plus clear docs should resolve the confusion.

The feedback from the users about how this is used is very useful; @Davier's use case in particular seems very challenging to eliminate.