Object3D: Added getObjectsByProperty() (#25006)

* Add getAll recursive function to Object3D

* Add documentation

* Add test

* getAll function minor improvements

renamed object to childResult
inline if statement

* fix test

* Rename function

* updated test

* Update Object3D.js

Co-authored-by: mrdoob <[email protected]>

docs/api/en/core/Object3D.html

@@ -277,6 +277,14 @@
 		Searches through an object and its children, starting with the object itself, and returns the first with a property that matches the value given.
 		</p>
 
+		<h3>[method:Object3D getObjectsByProperty]( [param:String name], [param:Any value] )</h3>
+		<p>
+		name -- the property name to search for. <br />
+		value -- value of the given property. <br /><br />
+
+		Searches through an object and its children, starting with the object itself, and returns all the objects with a property that matches the value given.
+		</p>
+
 		<h3>[method:Vector3 getWorldPosition]( [param:Vector3 target] )</h3>
 		<p>
 		[page:Vector3 target] — the result will be copied into this Vector3. <br /><br />

docs/api/it/core/Object3D.html

@@ -281,6 +281,14 @@
       Cerca in un oggetto e nei suoi figli, partendo dall'oggetto stesso, e restituisce il primo con la proprietà che corrisponde al valore passato.
 		</p>
 
+		<h3>[method:Object3D getObjectsByProperty]( [param:String name], [param:Any value] )</h3>
+		<p>
+		  name -- il nome della proprietà da cercare. <br />
+		  value -- il valore della proprietà data. <br /><br />
+
+      Cerca in un oggetto e nei suoi figli, partendo dall'oggetto stesso, e restituisce tutti gli oggetti con la proprietà che corrisponde al valore passato.
+		</p>
+
 		<h3>[method:Vector3 getWorldPosition]( [param:Vector3 target] )</h3>
 		<p>
 		  [page:Vector3 target] — il risultato verrà copiato in questo Vector3. <br /><br />

docs/api/ko/core/Object3D.html

@@ -266,6 +266,14 @@
 		객체 자신부터 시작하여 객체와 객체 자식 항목을 검색하고 일치하는 값의 첫 번째 항목을 리턴합니다.
 		</p>
 
+		<h3>[method:Object3D getObjectsByProperty]( [param:String name], [param:Any value] )</h3>
+		<p>
+		name -- 검색하고자하는 이름 프로퍼티. <br />
+		value -- 프로퍼티의 값. <br /><br />
+
+		개체 자체부터 시작하여 개체와 해당 자식을 검색하고 일치하는 값의 모든 개체를 반환합니다.
+		</p>
+
 		<h3>[method:Vector3 getWorldPosition]( [param:Vector3 target] )</h3>
 		<p>
 		[page:Vector3 target] — 결과값은 이 Vector3에 복제됩니다. <br /><br />

docs/api/zh/core/Object3D.html

@@ -263,6 +263,13 @@
 		从该对象开始，搜索一个对象及其子级，返回第一个给定的属性中包含有匹配的值的子对象。
 	</p>
 
+	<h3>[method:Object3D getObjectsByProperty]( [param:String name], [param:Any value] )</h3>
+	<p>
+		name —— 将要用于查找的属性的名称。<br />
+		value —— 给定的属性的值。 <br /><br />
+		从此对象开始，搜索一个对象及其子对象，返回包含给定属性的匹配值的所有子对象。
+	</p>
+
 	<h3>[method:Vector3 getWorldPosition]( [param:Vector3 target] )</h3>
 	<p>
 		[page:Vector3 target] — 结果将被复制到这个Vector3中。<br /><br />

src/core/Object3D.js

@@ -470,6 +470,28 @@ class Object3D extends EventDispatcher {
 
 	}
 
+	getObjectsByProperty( name, value ) {
+
+		let result = [];
+
+		if ( this[ name ] === value ) result.push( this );
+
+		for ( let i = 0, l = this.children.length; i < l; i ++ ) {
+
+			const childResult = this.children[ i ].getObjectsByProperty( name, value );
+
+			if ( childResult.length > 0 ) {
+
+				result = result.concat( childResult );
+
+			}
+
+		}
+
+		return result;
+
+	}
+
 	getWorldPosition( target ) {
 
 		this.updateWorldMatrix( true, false );

test/unit/src/core/Object3D.tests.js

@@ -533,6 +533,27 @@ export default QUnit.module( 'Core', () => {
 
 		} );
 
+		QUnit.test( 'getObjectsByProperty', ( assert ) => {
+
+			var parent = new Object3D();
+			var childName = new Object3D();
+			var childNothing = new Object3D();
+			var childName2 = new Object3D();
+			var childName3 = new Object3D();
+
+			parent.prop = true;
+			childName.name = 'foo';
+			childName2.name = 'foo';
+			childName3.name = 'foo';
+			childName2.add( childName3 );
+			childName.add( childName2 );
+			parent.add( childName, childNothing );
+
+			assert.strictEqual( parent.getObjectsByProperty( 'name', 'foo' ).length, 3, 'Get amount of all childs by name "foo"' );
+			assert.strictEqual( parent.getObjectsByProperty( 'name', 'foo' ).some(obj => obj.name !== 'foo') , false, 'Get all childs by name "foo"' );
+
+		} );
+
 		QUnit.test( 'getWorldPosition', ( assert ) => {
 
 			var a = new Object3D();