Clarify inconsistent GltfConvertCoordinates 0.18 behavior

[ChristopherBiscardi]

Objective

When using GltfConvertCoordinates as of #20394 , which is 0.18's version, using the flags results in the forward vector moving in a different direction for various entities in the hierarchy.

This is confusing, and (in my opinion) a broken behavior since it relies on users only ever moving the scene root or mesh entities forward. It is very common that a player's object is not one mesh. In fact this is the default case of the default Blender scene. The default cube turns into

• Scene
  • Parent Entity
    • Mesh3d/Material Entity

When using these flags the "Parent Entity"'s forward vector is the one that would be targeted to move the cube, since that is the root of the object. This Entity's forward direction would be in the opposite direction of the forward direction for the mesh, resulting in different entities in the hierarchy moving in different directions with no way to identify which will behave in which way.

Solution

No fix. Just Documentation. The flag is experimental afaik and changes fall under being experimental.

[janhohenheim]

Suggested change

	///
	/// Setting any of these values to true will result in the relevant entities
	/// moving in opposite directions when using the forward direction.
	/// This means that within a scene, different entities in a hierarchy will
	/// move in different global directions when using the forward direction
	/// for that `Entity`.
	///
	/// For example, a parent `Entity` A, with a child `Entity` B that has a `Mesh3d`
	/// component:
	///
	/// - Entity A with a `Transform`
	/// - Entity B with a `Transform`, `Mesh3d`, `MeshMaterial3d`
	///
	/// ## Disclaimer
	///
	/// Setting any of these values to true will result in the relevant entities
	/// moving in opposite directions when using the forward direction.
	/// This means that within a scene, different entities in a hierarchy will
	/// move in different global directions when using the forward direction
	/// for that `Entity`.
	///
	/// For example, a parent `Entity` A, with a child `Entity` B that has a `Mesh3d`
	/// component:
	///
	/// - `SceneRoot`
	/// - Entity A with a `Transform`
	/// - Entity B with a `Transform`, `Mesh3d`, `MeshMaterial3d`

[janhohenheim]

Suggested change

	///
	/// Setting any of these values to true will result in the relevant entities
	/// moving in opposite directions when using the forward direction.
	/// This means that within a scene, different entities in a hierarchy will
	/// move in different global directions when using the forward direction
	/// for that `Entity`.
	///
	/// For example, a parent `Entity` A, with a child `Entity` B that has a `Mesh3d`
	/// component:
	///
	/// - Entity A with a `Transform`
	/// - Entity B with a `Transform`, `Mesh3d`, `MeshMaterial3d`
	///
	/// If A's forward moves "North", B's forward moves "South"
	///
	/// ## Disclaimer
	///
	/// Setting any of these values to true will result in the relevant entities
	/// moving in opposite directions when using the forward direction.
	/// This means that within a scene, different entities in a hierarchy will
	/// move in different global directions when using the forward direction
	/// for that `Entity`.
	///
	/// For example, a parent `Entity` A, with a child `Entity` B that has a `Mesh3d`
	/// component:
	///
	/// - `SceneRoot`
	/// - Entity A with a `Transform`
	/// - Entity B with a `Transform`, `Mesh3d`, `MeshMaterial3d`
	///
	/// If A's forward moves "North", B's forward moves "South"

[ChristopherBiscardi]

SceneRoot's placement here is incorrect. The tree doesn't even have to include it if spawned from a scene_spawner, and writing it like this makes it confusing as to whether it's referring to the SceneRoot or the scene's root, which are different entities.

[greeble-dev]

I'd say this behaviour is already documented on the options:

pub struct GltfConvertCoordinates {
    /// If true, convert scenes by rotating the top-level transform of the scene entity.
    ///
    /// This will ensure that [`Transform::forward`] of the "root" entity (the one with [`SceneInstance`](bevy_scene::SceneInstance))
    /// aligns with the "forward" of the glTF scene.
    ///
    /// The glTF loader creates an entity for each glTF scene. Entities are
    /// then created for each node within the glTF scene. Nodes without a
    /// parent in the glTF scene become children of the scene entity.
    ///
    /// This option only changes the transform of the scene entity. It does not
    /// directly change the transforms of node entities - it only changes them
    /// indirectly through transform inheritance.
    pub rotate_scene_entity: bool,

    /// If true, convert mesh assets. This includes skinned mesh bind poses.
    ///
    /// This option only changes mesh assets and the transforms of entities that
    /// instance meshes. It does not change the transforms of entities that
    /// correspond to glTF nodes.
    pub rotate_meshes: bool,
}

So they both state which entities they convert and which are left alone.

Maybe that's not sufficient, and they should go into more detail on what situations the behavior can create.

[ChristopherBiscardi]

I feel it is important to indicate that the current flag's behavior results in forward being inconsistent within a scene.

[greeble-dev]

I'm going to think this through, and probably draft an alternative. Might not be until early January though.

I don't think this PR should land as is, since it makes assumptions about how users have set up their glTFs. Also any clarification should be on the GltfConvertCoordinates struct, not on GltfLoader and GltfLoaderSettings .