feat(useSeek): Add seekAll and seekAllByName methods to useSeek…

… composable (#433) * Added seekAll and SeekAllByName methods to useSeek composable * Use .includes to check for value instead of strict comparison. Update useSeek documentation to include these 2 new functions
Tresjs · Nov 5, 2023 · ef905a3 · ef905a3
1 parent 45aeafd
commit ef905a3
Show file tree

Hide file tree

Showing 2 changed files with 54 additions and 3 deletions.
diff --git a/docs/api/composables.md b/docs/api/composables.md
@@ -152,10 +152,10 @@ Similar to above composable, the `useTexture` composable returns a promise, you
 
 ## useSeek
 
-The `useSeek` composable provides utilities to easily traverse and navigate through complex ThreeJS scenes and object children graphs. It exports two functions, `seek` and `seekByName`, which allow you to find child objects based on specific properties.
+The `useSeek` composable provides utilities to easily traverse and navigate through complex ThreeJS scenes and object children graphs. It exports 4 functions which allow you to find child objects based on specific properties.
 
 ```ts
-const { seek, seekbyName } = useSeek()
+const { seek, seekByName, seekAll, seekAllByName } = useSeek()
 ```
 
 The seek function accepts three parameters:
@@ -164,7 +164,7 @@ The seek function accepts three parameters:
 - `property`: The property to be used in the search condition.
 - `value`: The value of the property to match.
 
-Both function traverses the object and returns the child object with the specified property and value. If no child with the given property and value is found, it returns null and logs a warning.
+The `seek` and `seekByName` function traverses the object and returns the child object with the specified property and value. If no child with the given property and value is found, it returns null and logs a warning.
 
 ```ts
 const carRef = ref(null)
@@ -179,6 +179,18 @@ watch(carRef, ({ model }) => {
 })
 ```
 
+Similarly, the `seekAll` and `seekAllByName` functions return an array of child objects whose property includes the given value. If no matches are found, then they return an empty array and a warning is logged.
+
+```ts
+const character = ref(null)
+
+watch(character, ({ model }) => {
+  if (model) {
+    const bones = seekAll(character, type, 'Bone')
+  }
+})
+```
+
 ## useTresContext
 This composable aims to provide access to the state model which contains multiple useful properties.
 

diff --git a/src/composables/useSeek/index.ts b/src/composables/useSeek/index.ts
@@ -9,6 +9,8 @@ import { useLogger } from '../useLogger'
 export interface UseSeekReturn {
   seek: (parent: THREE.Scene | THREE.Object3D, property: string, value: string) => THREE.Object3D | null
   seekByName: (parent: THREE.Scene | THREE.Object3D, value: string) => THREE.Object3D | null
+  seekAll: (parent: THREE.Scene | THREE.Object3D, property: string, value: string) => THREE.Object3D[]
+  seekAllByName: (parent: THREE.Scene | THREE.Object3D, value: string) => THREE.Object3D[]
 }
 
 /**
@@ -44,6 +46,30 @@ export function useSeek(): UseSeekReturn {
     return foundChild
   }
 
+  /**
+ * Returns an array of child objects of the parent given a property
+ *
+ * @param {(THREE.Scene | THREE.Object3D)} parent
+ * @param {string} property
+ * @param {string} value
+ * @return {*}  {(THREE.Object3D[])}
+ */
+  function seekAll(parent: THREE.Scene | THREE.Object3D, property: string, value: string): THREE.Object3D[] {
+    const foundChildren: THREE.Object3D[] = []
+
+    parent.traverse((child) => {
+      if ((child as any)[property].includes(value)) {
+        foundChildren.push(child)
+      }
+    })
+
+    if (!foundChildren.length) {
+      logWarning(`Children with ${property} '${value}' not found.`)
+    }
+
+    return foundChildren
+  }
+
   /**
    * Returns a child object of the parent given a child.name
    *
@@ -55,8 +81,21 @@ export function useSeek(): UseSeekReturn {
     return seek(parent, 'name', value)
   }
 
+  /**
+ * Returns an array of child objects of the parent given a child.name
+ *
+ * @param {(THREE.Scene | THREE.Object3D)} parent
+ * @param {string} value
+ * @return {*}  {(THREE.Object3D[])}
+ */
+  function seekAllByName(parent: THREE.Scene | THREE.Object3D, value: string): THREE.Object3D[] {
+    return seekAll(parent, 'name', value)
+  }
+
   return {
     seek,
     seekByName,
+    seekAll,
+    seekAllByName,
   }
 }