fix(entity): traverse front-to-back in getComponentsInChildren

packages/core/src/Entity.ts

@@ -296,9 +296,10 @@ export class Entity extends EngineObject {
 
   /**
    * Get the components which match the type of the entity and it's children.
+   * @remarks The components are returned in depth-first pre-order: the entity itself first, then each child's subtree in sibling order.
    * @param type - The component type
    * @param results - The components collection
-   * @returns	The components collection which match the type
+   * @returns The components collection which match the type
    */
   getComponentsIncludeChildren<T extends Component>(type: ComponentConstructor<T>, results: T[]): T[] {
     results.length = 0;
@@ -682,14 +683,16 @@ export class Entity extends EngineObject {
   }
 
   private _getComponentsInChildren<T extends Component>(type: ComponentConstructor<T>, results: T[]): void {
-    for (let i = this._components.length - 1; i >= 0; i--) {
-      const component = this._components[i];
+    const components = this._components;
+    for (let i = 0, n = components.length; i < n; i++) {
+      const component = components[i];
       if (component instanceof type) {
         results.push(component);
       }
     }
-    for (let i = this._children.length - 1; i >= 0; i--) {
-      this._children[i]._getComponentsInChildren<T>(type, results);
+    const children = this._children;
+    for (let i = 0, n = children.length; i < n; i++) {
+      children[i]._getComponentsInChildren<T>(type, results);
     }
   }
 

tests/src/core/Entity.test.ts

@@ -873,4 +873,46 @@ describe("Entity", async () => {
       expect(order).toEqual(["C", "B", "A"]);
     });
   });
+
+  describe("getComponentsIncludeChildren", () => {
+    class ScriptA extends Script {}
+    class ScriptB extends Script {}
+
+    it("should return components in depth-first front-to-back order", () => {
+      const root = new Entity(engine, "root");
+      root.parent = scene.getRootEntity();
+
+      const child0 = new Entity(engine, "child0");
+      child0.parent = root;
+      const child1 = new Entity(engine, "child1");
+      child1.parent = root;
+
+      const grandchild = new Entity(engine, "grandchild");
+      grandchild.parent = child0;
+
+      const compRoot = root.addComponent(ScriptA);
+      const compChild0 = child0.addComponent(ScriptA);
+      const compGrandchild = grandchild.addComponent(ScriptA);
+      const compChild1 = child1.addComponent(ScriptA);
+
+      const results: ScriptA[] = [];
+      root.getComponentsIncludeChildren(ScriptA, results);
+
+      expect(results).toEqual([compRoot, compChild0, compGrandchild, compChild1]);
+    });
+
+    it("should return multiple components per entity in add order", () => {
+      const root = new Entity(engine, "root");
+      root.parent = scene.getRootEntity();
+
+      const comp1 = root.addComponent(ScriptA);
+      const comp2 = root.addComponent(ScriptB);
+
+      const results: Script[] = [];
+      root.getComponentsIncludeChildren(Script, results);
+
+      expect(results[0]).eq(comp1);
+      expect(results[1]).eq(comp2);
+    });
+  });
 });