GLTFLoader/GLTFExporter: Add support for single root scenes

Author: aaronfranke

examples/jsm/exporters/GLTFExporter.js

@@ -646,7 +646,8 @@ class GLTFWriter {
 			onlyVisible: true,
 			maxTextureSize: Infinity,
 			animations: [],
-			includeCustomExtensions: false
+			includeCustomExtensions: false,
+			allowSingleRoot: false,
 		}, options );
 
 		if ( this.options.animations.length > 0 ) {
@@ -2540,6 +2541,10 @@ class GLTFWriter {
 
 		if ( objectsWithoutScene.length > 0 ) {
 
+			if ( options.allowSingleRoot && input.length === 1 ) {
+				this.extensionsUsed[ 'GODOT_single_root' ] = true;
+			}
+
 			await this.processObjectsAsync( objectsWithoutScene );
 
 		}
@@ -3567,6 +3572,7 @@ GLTFExporter.Utils = {
  * @property {number} [maxTextureSize=Infinity] - Restricts the image maximum size (both width and height) to the given value.
  * @property {Array<AnimationClip>} [animations=[]] - List of animations to be included in the export.
  * @property {boolean} [includeCustomExtensions=false] - Export custom glTF extensions defined on an object's `userData.gltfExtensions` property.
+ * @property {boolean} [allowSingleRoot=false] - When exporting a single object, flag it as the single root of the glTF file using the `GODOT_single_root` extension. This is highly recommended, but is false by default for backwards compatibility.
  **/
 
 /**

examples/jsm/loaders/GLTFLoader.js

@@ -405,7 +405,7 @@ class GLTFLoader extends Loader {
 	}
 
 	/**
-	 * Parses the given FBX data and returns the resulting group.
+	 * Parses the given glTF data and returns the generated data to `onLoad`, with the root Object3D in the `.scene` property.
 	 *
 	 * @param {string|ArrayBuffer} data - The raw glTF data.
 	 * @param {string} path - The URL base path.
@@ -619,7 +619,8 @@ const EXTENSIONS = {
 	EXT_TEXTURE_WEBP: 'EXT_texture_webp',
 	EXT_TEXTURE_AVIF: 'EXT_texture_avif',
 	EXT_MESHOPT_COMPRESSION: 'EXT_meshopt_compression',
-	EXT_MESH_GPU_INSTANCING: 'EXT_mesh_gpu_instancing'
+	EXT_MESH_GPU_INSTANCING: 'EXT_mesh_gpu_instancing',
+	GODOT_SINGLE_ROOT: 'GODOT_single_root',
 };
 
 /**
@@ -4479,18 +4480,28 @@ class GLTFParser {
 
 		const extensions = this.extensions;
 		const sceneDef = this.json.scenes[ sceneIndex ];
+		const nodeIds = sceneDef.nodes || [];
 		const parser = this;
+		const extensionsUsed = this.json.extensionsUsed;
+		const isSingleRoot = Array.isArray( extensionsUsed ) ? extensionsUsed.includes( EXTENSIONS.GODOT_SINGLE_ROOT ) : false;
 
-		// Loader returns Group, not Scene.
-		// See: https://github.com/mrdoob/three.js/issues/18342#issuecomment-578981172
-		const scene = new Group();
-		if ( sceneDef.name ) scene.name = parser.createUniqueName( sceneDef.name );
+		let scene;
+		if ( isSingleRoot ) {
 
-		assignExtrasToUserData( scene, sceneDef );
+			if ( nodeIds.length !== 1 ) {
+				throw new Error( 'THREE.GLTFLoader: glTF file with the single root flag must have exactly one scene root node. File is invalid.' );
+			}
 
-		if ( sceneDef.extensions ) addUnknownExtensionsToUserData( extensions, scene, sceneDef );
+		} else {
+			// Loader returns Group, not Scene.
+			// See: https://github.com/mrdoob/three.js/issues/18342#issuecomment-578981172
+			scene = new Group();
+			if ( sceneDef.name ) scene.name = parser.createUniqueName( sceneDef.name );
 
-		const nodeIds = sceneDef.nodes || [];
+			assignExtrasToUserData( scene, sceneDef );
+
+			if ( sceneDef.extensions ) addUnknownExtensionsToUserData( extensions, scene, sceneDef );
+		}
 
 		const pending = [];
 
@@ -4502,9 +4513,17 @@ class GLTFParser {
 
 		return Promise.all( pending ).then( function ( nodes ) {
 
-			for ( let i = 0, il = nodes.length; i < il; i ++ ) {
+			if ( isSingleRoot ) {
 
-				scene.add( nodes[ i ] );
+				scene = nodes[ 0 ];
+
+			} else {
+
+				for ( let i = 0, il = nodes.length; i < il; i ++ ) {
+
+					scene.add( nodes[ i ] );
+
+				}
 
 			}