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

[cptbtptpbcptdtptp]

Summary

• _getComponentsInChildren previously traversed components and children back-to-front (length-1 → 0), causing results to be returned in reverse hierarchy order.
• Changed to front-to-back (0 → N) depth-first pre-order traversal, which is the industry-standard convention for hierarchy queries.

Test plan

• Existing unit tests pass (pnpm run test)
• Verify getComponentsIncludeChildren returns components in the expected hierarchy order (parent-first, depth-first)

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Standardized component retrieval to use depth-first pre-order traversal for consistent result ordering across entity hierarchies.

• Documentation

  • Clarified documentation specifying the exact traversal sequence used for component searches.

• Tests

  • Added comprehensive test coverage to verify component retrieval order consistency and proper handling of multiple matching components.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 197ffbba-ef7d-4c20-9ac5-f28f5e56bbc3

📥 Commits

Reviewing files that changed from the base of the PR and between 9e9d58e and 1f1d6e7.

📒 Files selected for processing (1)

• packages/core/src/Entity.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/core/src/Entity.ts

---

Walkthrough

This PR documents and implements a traversal order change in _getComponentsInChildren from reverse iteration to forward iteration, affecting the sequence in which components are collected from entity hierarchies. Tests verify depth-first pre-order collection and component add-order preservation.

Changes

Component Traversal Order

Layer / File(s)	Summary
Documentation and forward-iteration implementation packages/core/src/Entity.ts	getComponentsIncludeChildren JSDoc remarks now specify depth-first pre-order traversal semantics. _getComponentsInChildren changes from reverse to forward iteration over _components and _children, recursing into child entities in ascending sibling order.
Tests for traversal order and add-order preservation tests/src/core/Entity.test.ts	Adds test cases asserting depth-first front-to-back component collection across parent/child/grandchild entities and confirming multiple matching components on one entity are returned in add-order.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 A method once danced in reverse and back,
Now forward it hops down the component track.
From children collected in proper array,
The entities queue up a new, ordered way.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: converting the traversal order from back-to-front to front-to-back in getComponentsInChildren, which is the primary fix in this changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/entity-getcomponents-order

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.16%. Comparing base (97d8d61) to head (1f1d6e7).
⚠️ Report is 6 commits behind head on dev/2.0.

Additional details and impacted files

@@             Coverage Diff             @@
##           dev/2.0    #3030      +/-   ##
===========================================
+ Coverage    77.31%   79.16%   +1.85%     
===========================================
  Files          914      914              
  Lines       101723   101669      -54     
  Branches     10437    11208     +771     
===========================================
+ Hits         78647    80488    +1841     
+ Misses       22892    20994    -1898     
- Partials       184      187       +3     

Flag	Coverage Δ
unittests	79.16% <100.00%> (+1.85%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[GuoLei1990]

总结

把 _getComponentsInChildren 从 back-to-front（length-1 → 0）改为 front-to-back（0 → N）深度优先前序遍历，使返回顺序符合层级直觉（self 在前、子节点按 sibling 顺序、深度优先）。方向正确，是一个干净的小修复，且 loop 写法（hoist _components/_children 到局部、缓存 n）与同文件 _setActiveInHierarchy、getComponents 一致，无新分配、无热路径退化。

验证

• 真实 bug 修复（反向证伪通过）：手工回放旧逻辑——
  • 顺序测试旧实现产出 [compRoot, compChild1, compChild0, compGrandchild]，新实现 [compRoot, compChild0, compGrandchild, compChild1]；
  • add-order 测试旧实现产出 [comp2, comp1]，新实现 [comp1, comp2]。
    两条测试在修复前必 fail、修复后 pass，是合格回归。
• 消费者零回归：3 个内部消费者（Animator._controlledRenderers 仅做 isCulled 任一为真的判断、两处 ParticleGenerator play/stop 遍历）均按无序集合消费，改顺序不影响任何现有行为。
• 递归 vs 迭代：保持递归（深度优先），与意图一致，无需改写。
• 竞品对标：Unity GetComponentsInChildren 同样是深度优先前序（self → 递归 children），本次对齐正确。

问题

无 P0/P1。

• [P2] packages/core/src/Entity.ts:297-302 — 公开方法 getComponentsIncludeChildren 的 JSDoc 仍未承诺返回顺序，但本 PR 的测试已把"深度优先前序（父在子前、子按 sibling 顺序）"锁成契约。文档应与被测试锁定的契约对齐，建议补一句说明返回顺序。顺带：该 JSDoc 第 301 行 @returns 后是个 tab 而非空格（pre-existing），改这块时一并修掉。非阻塞。

简化建议

代码已足够简洁，无进一步精简空间。

[GuoLei1990]

总结

增量审查针对最新 commit `1f1d6e7d`（自上轮以来唯一改动，`Entity.ts` +2 -1）。这一 commit 正是上轮我提的 [P2]：把"深度优先前序"的返回顺序写进公开 JSDoc，并把 `@returns` 后的 tab 修成空格。问题已闭环，本 PR 现在是一个干净完整的小修复，可以合入。

验证

• JSDoc 与契约对齐（已修复） — 新增 `@remarks The components are returned in depth-first pre-order: the entity itself first, then each child's subtree in sibling order.`。核对实现：`_getComponentsInChildren` 先 front-to-back push 本 entity 的匹配组件（"entity itself first"），再 front-to-back 递归 `_children`（"each child's subtree in sibling order"），与测试锁定的 `[compRoot, compChild0, compGrandchild, compChild1]` 完全一致，文档无 aspirational 偏差。
• tab → space（已修复） — 第 301 行 `@returns` 后的 tab 已改为常规空格。
• JSDoc 风格合规 — 单行 `@remarks` 形式与项目惯例一致（`Background.ts`、`Camera.ts:68/250`、`Engine.ts:205/411` 均为单行内联 `@remarks`），无需展开多行。

问题

无。上轮唯一的 [P2] 已修复，本次 commit 不引入任何新代码或行为变化（CodeRabbit 与 `git compare` 均确认 diff 仅此一处文档改动）。

之前已关闭的几点（消费者零回归、与 `getComponents`/`_setActiveInHierarchy` 的 loop 写法一致、反向证伪测试合格、Unity 深度优先前序对标）维持结论，不再重复。

LGTM 👍