Clarify glTF coordinate conversion documentation

[greeble-dev]

Objective

Add more information to the documentation for glTF coordinate conversion. This tries to address the issues raised in #22209.

Solution

The new docs cover exactly which entities will have a correct Transform::forward, assuming the glTF file consistently uses the standard glTF coordinate system for both scenes and nodes.

I've also restored the warning that was in the 0.17 documentation:

CAUTION: This is an experimental feature. Behavior may change in future versions.

This is because:

1. I want to add node conversion in 0.19, and that might involve changing how scene conversion works.
2. Cart has mentioned that BSN might restructure scenes, which could also change how scene conversion works.

Screenshot:

If this PR lands then I might do another PR to update the migration guide - I can't update it in this PR as the guides are only in the 0.18 branch.

[greeble-dev]

I'm adding this to the 0.18 milestone - it's a docs only change to a feature that was changed substantially in 0.18.

[ChristopherBiscardi]

• Every entity is created by the glTF loader, not just the "scene entity"
• SceneInstance and SceneRoot are not part of a scene. If you spawn a scene using the SceneSpawner you will not have a SceneInstance or a SceneRoot.

Here's an alternative:

Bevy's glTF loader creates an Entity for each glTF Scene to contain the glTF Scene's nodes. This Scene Entity's children are the entities created from the top-level nodes in the glTF Scene definition. Each node can also continue to have its own child nodes. The Scene Entity that was created to contain the glTF Scene's nodes is the one that becomes rotated.

If you use SceneRoot to spawn the entire scene as a child, that means the Entity with the SceneRoot is parent of the full set of Scene nodes described in the previous paragraph, including the Scene Entity. The child Entity of the SceneRoot is the one that is rotated according to the previous paragraph.

[greeble-dev]

Every entity is created by the glTF loader, not just the "scene entity"

The parent of the scene entity is not created by the loader. I was worried that the user might interpret "scene entity" as the parent entity that they created, so it's worth emphasising that the loader creates the scene entity even if it's arguably redundant.

SceneInstance and SceneRoot are not part of a scene. If you spawn a scene using the SceneSpawner you will not have a SceneInstance or a SceneRoot.

The reference to SceneInstance was originally added by Cart. So you're correct and I'm open to changing it, but I'm reluctant to do so without a second opinion. Maybe it was an oversight and should be changed, or maybe there's an assumption that most people use SceneRoot/SceneInstance and that keeps the explanation simpler.

[ChristopherBiscardi]

This sounds like you agree with the suggested rewrite but want to add SceneInstance into the second paragraph in addition to SceneRoot.

[greeble-dev]

I don't agree with the suggested rewrite. I think the current description is good enough, assuming most people are spawning scenes via components.

If I feel there's a consensus that the current description isn't good enough, I'd still need to take a different approach - the suggested rewrite doesn't cover another place that references the scene entity:

[ChristopherBiscardi]

ok. I think the PR is not sufficient, so I'll leave the change suggestion.

Different documentation sections that are incorrect should also be updated, which is separate from this suggestion and does not affect its relevance.

[ChristopherBiscardi]

Approving because the experimental note needs to make it into 0.18, but I maintain the suggested change should be made.