UnityGLTF icon indicating copy to clipboard operation
UnityGLTF copied to clipboard

Explicitly flag glTF files with a single root node on export

Open aaronfranke opened this issue 6 months ago • 1 comments

This PR adds support for exporting files with the GODOT_single_root extension. This vendor extension is recognized by Khronos in their repository's vendor extensions folder (but not developed by or officially endorsed by Khronos).

What about import? UnityGLTF already implicitly has the import behavior which GODOT_single_root explicitly defines, so there is nothing to do on import.

UnityGLTF automatically takes glTF files with a single root node and makes that the root object of the imported file. Other glTF importers, such as Godot and Three.js, will not automatically do this, instead they will generate an empty object representing the glTF scene, and add the glTF root nodes as children of that. Therefore, this flag existing provides a hint to other importers that they should do what UnityGLTF does. This improves interoperability with Godot Engine, and likely soon Three.js. With this PR, you can send objects back and forth between Unity and Godot via glTF and UnityGLTF and get the same node hierarchy each time, whereas without this PR, each time you export from UnityGLTF and import into Godot, it will generate an extra root node. For engines without support for GODOT_single_root, this changes nothing, and files will continue to work exactly as before.

The code in this PR expands a bit on the code from @hybridherbst in https://github.com/KhronosGroup/UnityGLTF/commit/ede47727a6145fb1bd899f5b1443ddd238b37257. The UnityGLTF TreatEmptyRootAsScene feature is what Godot calls "multi root", without a flag where an extra node is generated is called "keep root", and with the GODOT_single_root flag is called "single root", where single root is identical to keep root in implementations that do not recognize GODOT_single_root.

Note: The "GODOT_single_root" extension name is prefixed with "GODOT_" because that is the context in which that extension was developed, however this does not mean it is only intended to be used for Godot. Quite the opposite actually, this is designed to improve interoperability between game engines for glTF files containing "one object". The "EXT_" prefix is reserved for extensions developed by multiple vendors, it does not prescribe which apps can use it.

This is my first contribution to UnityGLTF. I've tested this by exporting a few glTF files in the editor which should or should not have this flag set. If any changes are needed I will be happy to update the PR.

aaronfranke avatar May 17 '25 17:05 aaronfranke

CLA assistant check
All committers have signed the CLA.

CLAassistant avatar May 17 '25 17:05 CLAassistant