JSON v5: Centralize buffers and use UUID-keyed collections

- Bump serialization version to 5
- Extract buffer data to top-level `buffers` object to avoid duplication
- Change collections (geometries, materials, textures, etc.) from arrays to UUID-keyed objects
- Remove redundant uuid property from items (uuid is now the key)
- Use explicit type strings instead of boolean flags:
  - `isInstancedBufferAttribute` → `type: 'InstancedBufferAttribute'`
  - `isInterleavedBufferAttribute` → `type: 'InterleavedBufferAttribute'`
  - `isInstancedInterleavedBuffer` → `type: 'InstancedInterleavedBuffer'`
- Add `arrayType` property to preserve typed array constructor name
- ObjectLoader: Add `_distributeBuffers()` to merge buffers into geometries
- ObjectLoader: Add `_convertLegacyCollections()` for v4 compatibility
- ObjectLoader: Parse methods now iterate over objects natively
- BufferGeometryLoader: Support both v4 and v5 attribute formats

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: mrdoob

src/core/BufferGeometry.js

@@ -1213,7 +1213,7 @@ class BufferGeometry extends EventDispatcher {
 
 		const data = {
 			metadata: {
-				version: 4.7,
+				version: 5,
 				type: 'BufferGeometry',
 				generator: 'BufferGeometry.toJSON'
 			}

src/core/InstancedBufferAttribute.js

@@ -55,10 +55,10 @@ class InstancedBufferAttribute extends BufferAttribute {
 
 		const data = super.toJSON();
 
+		data.type = 'InstancedBufferAttribute';
+		data.arrayType = data.type;
 		data.meshPerAttribute = this.meshPerAttribute;
 
-		data.isInstancedBufferAttribute = true;
-
 		return data;
 
 	}

src/core/InstancedInterleavedBuffer.js

@@ -62,7 +62,7 @@ class InstancedInterleavedBuffer extends InterleavedBuffer {
 
 		const json = super.toJSON( data );
 
-		json.isInstancedInterleavedBuffer = true;
+		json.type = 'InstancedInterleavedBuffer';
 		json.meshPerAttribute = this.meshPerAttribute;
 
 		return json;

src/core/InterleavedBuffer.js

@@ -279,8 +279,9 @@ class InterleavedBuffer {
 
 		return {
 			uuid: this.uuid,
+			type: 'InterleavedBuffer',
+			arrayType: this.array.constructor.name,
 			buffer: this.array.buffer._uuid,
-			type: this.array.constructor.name,
 			stride: this.stride
 		};
 

src/core/InterleavedBufferAttribute.js

@@ -532,7 +532,7 @@ class InterleavedBufferAttribute {
 			}
 
 			return {
-				isInterleavedBufferAttribute: true,
+				type: 'InterleavedBufferAttribute',
 				itemSize: this.itemSize,
 				data: this.data.uuid,
 				offset: this.offset,

src/core/Object3D.js

@@ -1283,7 +1283,7 @@ class Object3D extends EventDispatcher {
 			};
 
 			output.metadata = {
-				version: 4.7,
+				version: 5,
 				type: 'Object',
 				generator: 'Object3D.toJSON'
 			};
@@ -1513,45 +1513,92 @@ class Object3D extends EventDispatcher {
 
 		if ( isRootObject ) {
 
-			const geometries = extractFromCache( meta.geometries );
-			const materials = extractFromCache( meta.materials );
-			const textures = extractFromCache( meta.textures );
-			const images = extractFromCache( meta.images );
-			const shapes = extractFromCache( meta.shapes );
-			const skeletons = extractFromCache( meta.skeletons );
-			const animations = extractFromCache( meta.animations );
-			const nodes = extractFromCache( meta.nodes );
-
-			if ( geometries.length > 0 ) output.geometries = geometries;
-			if ( materials.length > 0 ) output.materials = materials;
-			if ( textures.length > 0 ) output.textures = textures;
-			if ( images.length > 0 ) output.images = images;
-			if ( shapes.length > 0 ) output.shapes = shapes;
-			if ( skeletons.length > 0 ) output.skeletons = skeletons;
-			if ( animations.length > 0 ) output.animations = animations;
-			if ( nodes.length > 0 ) output.nodes = nodes;
+			// Remove metadata and uuid (redundant since uuid is the key) from each item
+			const collections = [ meta.geometries, meta.materials, meta.textures, meta.images, meta.shapes, meta.skeletons, meta.animations, meta.nodes ];
+
+			for ( const collection of collections ) {
+
+				for ( const key in collection ) {
+
+					delete collection[ key ].metadata;
+					delete collection[ key ].uuid;
+
+				}
+
+			}
+
+			// Extract buffers from geometries to top-level
+			const buffers = extractBuffers( meta.geometries );
+			if ( Object.keys( buffers ).length > 0 ) output.buffers = buffers;
+
+			// Output collections as UUID-keyed objects
+			if ( Object.keys( meta.geometries ).length > 0 ) output.geometries = meta.geometries;
+			if ( Object.keys( meta.materials ).length > 0 ) output.materials = meta.materials;
+			if ( Object.keys( meta.textures ).length > 0 ) output.textures = meta.textures;
+			if ( Object.keys( meta.images ).length > 0 ) output.images = meta.images;
+			if ( Object.keys( meta.shapes ).length > 0 ) output.shapes = meta.shapes;
+			if ( Object.keys( meta.skeletons ).length > 0 ) output.skeletons = meta.skeletons;
+			if ( Object.keys( meta.animations ).length > 0 ) output.animations = meta.animations;
+			if ( Object.keys( meta.nodes ).length > 0 ) output.nodes = meta.nodes;
 
 		}
 
 		output.object = object;
 
 		return output;
 
-		// extract data from the cache hash
-		// remove metadata on each item
-		// and return as array
-		function extractFromCache( cache ) {
+		// Extract buffer data from geometries to top-level buffers object
+		function extractBuffers( geometries ) {
+
+			const buffers = {};
+
+			for ( const uuid in geometries ) {
+
+				const geometry = geometries[ uuid ];
+				const data = geometry.data;
+
+				if ( data === undefined ) continue;
+
+				// Extract arrayBuffers as typed array entries
+				if ( data.arrayBuffers !== undefined ) {
+
+					for ( const bufferUuid in data.arrayBuffers ) {
+
+						if ( buffers[ bufferUuid ] === undefined ) {
 
-			const values = [];
-			for ( const key in cache ) {
+							buffers[ bufferUuid ] = {
+								type: 'Uint32Array',
+								array: data.arrayBuffers[ bufferUuid ]
+							};
 
-				const data = cache[ key ];
-				delete data.metadata;
-				values.push( data );
+						}
+
+					}
+
+					delete data.arrayBuffers;
+
+				}
+
+				// Extract interleavedBuffers
+				if ( data.interleavedBuffers !== undefined ) {
+
+					for ( const bufferUuid in data.interleavedBuffers ) {
+
+						if ( buffers[ bufferUuid ] === undefined ) {
+
+							buffers[ bufferUuid ] = data.interleavedBuffers[ bufferUuid ];
+
+						}
+
+					}
+
+					delete data.interleavedBuffers;
+
+				}
 
 			}
 
-			return values;
+			return buffers;
 
 		}
 

src/loaders/BufferGeometryLoader.js

@@ -7,6 +7,7 @@ import { InstancedBufferGeometry } from '../core/InstancedBufferGeometry.js';
 import { InstancedBufferAttribute } from '../core/InstancedBufferAttribute.js';
 import { InterleavedBufferAttribute } from '../core/InterleavedBufferAttribute.js';
 import { InterleavedBuffer } from '../core/InterleavedBuffer.js';
+import { InstancedInterleavedBuffer } from '../core/InstancedInterleavedBuffer.js';
 import { getTypedArray, error } from '../utils.js';
 
 /**
@@ -99,8 +100,27 @@ class BufferGeometryLoader extends Loader {
 
 			const buffer = getArrayBuffer( json, interleavedBuffer.buffer );
 
-			const array = getTypedArray( interleavedBuffer.type, buffer );
-			const ib = new InterleavedBuffer( array, interleavedBuffer.stride );
+			// Use arrayType for v5 format, fall back to type for v4
+			const arrayType = interleavedBuffer.arrayType || interleavedBuffer.type;
+			const array = getTypedArray( arrayType, buffer );
+
+			let ib;
+
+			if ( interleavedBuffer.type === 'InstancedInterleavedBuffer' ) {
+
+				ib = new InstancedInterleavedBuffer( array, interleavedBuffer.stride, interleavedBuffer.meshPerAttribute );
+
+			} else if ( interleavedBuffer.isInstancedInterleavedBuffer ) {
+
+				// v4 backwards compatibility
+				ib = new InstancedInterleavedBuffer( array, interleavedBuffer.stride, interleavedBuffer.meshPerAttribute );
+
+			} else {
+
+				ib = new InterleavedBuffer( array, interleavedBuffer.stride );
+
+			}
+
 			ib.uuid = interleavedBuffer.uuid;
 
 			interleavedBufferMap[ uuid ] = ib;
@@ -142,16 +162,30 @@ class BufferGeometryLoader extends Loader {
 			const attribute = attributes[ key ];
 			let bufferAttribute;
 
-			if ( attribute.isInterleavedBufferAttribute ) {
+			// Check for interleaved buffer attribute (support both v4 and v5 formats)
+			const isInterleaved = attribute.isInterleavedBufferAttribute || attribute.type === 'InterleavedBufferAttribute';
+
+			if ( isInterleaved ) {
 
 				const interleavedBuffer = getInterleavedBuffer( json.data, attribute.data );
 				bufferAttribute = new InterleavedBufferAttribute( interleavedBuffer, attribute.itemSize, attribute.offset, attribute.normalized );
 
 			} else {
 
-				const typedArray = getTypedArray( attribute.type, attribute.array );
-				const bufferAttributeConstr = attribute.isInstancedBufferAttribute ? InstancedBufferAttribute : BufferAttribute;
-				bufferAttribute = new bufferAttributeConstr( typedArray, attribute.itemSize, attribute.normalized );
+				// Check for instanced buffer attribute (support both v4 and v5 formats)
+				const isInstanced = attribute.isInstancedBufferAttribute || attribute.type === 'InstancedBufferAttribute';
+
+				const typedArray = getTypedArray( isInstanced ? attribute.arrayType || 'Float32Array' : attribute.type, attribute.array );
+
+				if ( isInstanced ) {
+
+					bufferAttribute = new InstancedBufferAttribute( typedArray, attribute.itemSize, attribute.normalized, attribute.meshPerAttribute );
+
+				} else {
+
+					bufferAttribute = new BufferAttribute( typedArray, attribute.itemSize, attribute.normalized );
+
+				}
 
 			}
 
@@ -177,7 +211,10 @@ class BufferGeometryLoader extends Loader {
 					const attribute = attributeArray[ i ];
 					let bufferAttribute;
 
-					if ( attribute.isInterleavedBufferAttribute ) {
+					// Check for interleaved buffer attribute (support both v4 and v5 formats)
+					const isInterleaved = attribute.isInterleavedBufferAttribute || attribute.type === 'InterleavedBufferAttribute';
+
+					if ( isInterleaved ) {
 
 						const interleavedBuffer = getInterleavedBuffer( json.data, attribute.data );
 						bufferAttribute = new InterleavedBufferAttribute( interleavedBuffer, attribute.itemSize, attribute.offset, attribute.normalized );