Object3D: add generator-based traversal methods (#28053)

* Object3D: add traversal generator methods

* feat: add opt condition to traversal generators

* feat: move generator functions to SceneUtils

* fix(test): move tests, oops

* fix: remove unit tests

* fix: remove condition callback (always yield)

* Update SceneUtils.js

Fix JSDoc.

---------

Co-authored-by: Michael Herzog <[email protected]>

examples/jsm/utils/SceneUtils.js

@@ -245,10 +245,69 @@ function sortInstancedMesh( mesh, compareFn ) {
 
 }
 
+/**
+ * @param {Object3D} object Object to traverse.
+ * @yields {Object3D} Objects that passed the filter condition.
+ */
+function* traverseGenerator( object ) {
+
+	yield object;
+
+	const children = object.children;
+
+	for ( let i = 0, l = children.length; i < l; i ++ ) {
+
+		yield* traverseGenerator( children[ i ] );
+
+	}
+
+}
+
+/**
+ * @param {Object3D} object Object to traverse.
+ * @yields {Object3D} Objects that passed the filter condition.
+ */
+function* traverseVisibleGenerator( object ) {
+
+	if ( object.visible === false ) return;
+
+	yield object;
+
+	const children = object.children;
+
+	for ( let i = 0, l = children.length; i < l; i ++ ) {
+
+		yield* traverseVisibleGenerator( children[ i ] );
+
+	}
+
+}
+
+/**
+ * @param {Object3D} object Object to traverse.
+ * @yields {Object3D} Objects that passed the filter condition.
+ */
+function* traverseAncestorsGenerator( object ) {
+
+	const parent = object.parent;
+
+	if ( parent !== null ) {
+
+		yield parent;
+
+		yield* traverseAncestorsGenerator( parent );
+
+	}
+
+}
+
 export {
 	createMeshesFromInstancedMesh,
 	createMeshesFromMultiMaterialMesh,
 	createMultiMaterialObject,
 	reduceVertices,
-	sortInstancedMesh
+	sortInstancedMesh,
+	traverseGenerator,
+	traverseVisibleGenerator,
+	traverseAncestorsGenerator
 };