Skip to content

Explicitly flag glTF files with a single root node on export #850

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: dev
Choose a base branch
from

Conversation

aaronfranke
Copy link

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 ede4772. 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.

@CLAassistant
Copy link

CLAassistant commented May 17, 2025

CLA assistant check
All committers have signed the CLA.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants