bevy_ecs is excessively public

[alice-i-cecile]

Many internal implementation details are exposed to end users of bevy_ecs.

Most of these are very complex, largely undocumented and risky to mess with. Where possible, these should be pub(crate) instead.

Doing this makes our docs more browseable, and clearly communicates to Bevy developers which parts of the infrastructure are public API, worthy of special attention. In the extremely distant future, this would also allow us to make breaking changes to these types and methods without a major version bump.

Initial List of "Why is this pub"

• All of the types and methods in bevy::ecs::archetype, except maybe Archetypes itself
• BundleId, BundleInfo and Bundles
• ComponentId, ComponentInfo and ComponentDescriptor
• EntityLocation and EntityMeta
• all of bevy::ecs::storage

This is a reasonably aggressive list: if you can find an argument for why a type should be pub, we can leave it pub.

If another crate (bevy_scenes and bevy_reflect are the most likely candidates) relies heavily on a set of otherwise obscure functionality, we should discuss code organization.

If we could eventually use something being pub, we should probably make it private for now, and then revert that once a tangible use case arises, with a sensible API to meet those needs.

This list is also not exhaustive. I'm sure there will also be a number of methods and so on lurking that I've overlooked.

Follow-up

• The public facing API for bevy_ecs::component needs a once-over. Probably just enough to work with for scripting/reflection, but there are some rather redundant types exposed there (ComponentInfo vs ComponentDescriptor is especially confusing)
• Schedule definitely needs a scan through. A lot of these are probably going to be massively rewritten during stageless, but a more coherent docs story there is needed.
• Reflect and EntityMap types need to be shuffled around to be a bit more coherent.

From @james7132 in #5065.

[MrGVSV]

Personally, I use Archetypes, ComponentId, and ComponentInfo when debugging sometimes. Such as when I need all the components on a given entity: #3332 (comment).

Haven't used the others though.

[alice-i-cecile]

Yep, we should be sure to check in with bevy_inspector_egui before merging a PR to resolve this: they're probably our most advanced consumer of this internal information for debugging purposes.

[bjorn3]

I think we should also make sure that it is possible to implement dynamic components (as far as that doesn't need extra exports) and not require the query dsl. Both for scripting purposes.

[Nilirad]

Another possibility could be to split bevy_ecs in two crates, one, bevy_ecs_core, with a low level API, and the other, bevy_ecs, with a higher level API (i.e. the intended "public" API).

Then, both crates are re-exported, but only bevy_ecs items are included in the prelude. However, if someone wants to go "lower level", they use bevy_ecs_core.

I still have a couple of concerns on this solution:

• Is it still really needed to expose a bunch of low level APIs? As Alice explained earlier, the smaller the public API footprint, the more difficult it would be to make breaking changes.
• Could it be that splitting functionality into multiple crates may pose a problem with orphan rules?

An alternative could also relegate the noisy API into a module instead of splitting into crates. Maybe the problem is not that the crate is excessively public, but it needs to be better organized/refactored.