Object3D: added attach() method

docs/api/en/core/Object3D.html

@@ -217,6 +217,9 @@ <h3>[method:null applyMatrix]( [param:Matrix4 matrix] )</h3>
 		<h3>[method:this applyQuaternion]( [param:Quaternion quaternion] )</h3>
 		<p>Applies the rotation represented by the quaternion to the object.</p>
 
+		<h3>[method:this attach]( [param:Object3D object] )</h3>
+		<p>Adds *object* as a child of this, while maintaining the object's world transform.</p>
+
 		<h3>[method:Object3D clone]( [param:Boolean recursive] )</h3>
 		<p>
 		recursive -- if true, descendants of the object are also cloned. Default is true.<br /><br />

src/core/Object3D.d.ts

@@ -287,6 +287,11 @@ export class Object3D extends EventDispatcher {
    */
   remove(...object: Object3D[]): this;
 
+  /**
+   * Adds object as a child of this, while maintaining the object's world transform.
+   */
+  attach(object: Object3D): this;
+
   /**
    * Searches through the object's children and returns the first with a matching id.
    * @param id  Unique number of the object instance

src/core/Object3D.js

@@ -433,6 +433,38 @@ Object3D.prototype = Object.assign( Object.create( EventDispatcher.prototype ),
 
 	},
 
+	attach: function () {
+
+		// adds object as a child of this, while maintaining the object's world transform
+
+		var m = new Matrix4();
+
+		return function attach( object ) {
+
+			this.updateWorldMatrix( true, false );
+
+			m.getInverse( this.matrixWorld );
+
+			if ( object.parent !== null ) {
+
+				object.parent.updateWorldMatrix( true, false );
+
+				m.multiply( object.parent.matrixWorld );
+
+			}
+
+			object.applyMatrix( m );
+
+			object.updateWorldMatrix( false, false );
+
+			this.add( object );
+
+			return this;
+
+		};
+
+	}(),
+
 	getObjectById: function ( id ) {
 
 		return this.getObjectByProperty( 'id', id );