fix(physics): unify scene query filtering to use collisionLayer

[GuoLei1990]

背景

之前物理系统存在两套 layer 过滤机制：

• 场景查询（raycast / sweep / overlap）使用 entity.layer 过滤
• 碰撞检测（contact / trigger）使用 collider.collisionLayer 过滤

这对用户来说很不直观——同样是物理相关的操作，需要分别设置两个不同的 layer 才能得到预期结果。

从用户角度看问题

射线检测本质上也是一种物理查询，用户的直觉是：我在 collider 上设了 collisionLayer，那所有物理相关的过滤（碰撞、射线、扫描、重叠检测）都应该走这个 layer。不应该还要额外去设 entity.layer 才能让射线检测生效。

统一后的心智模型很简单：

• collisionLayer → 管所有物理相关的事
• entity.layer → 管渲染剔除等非物理的事

职责清晰，互不干扰。这也和 Unity 的设计思路一致——用一套 layer 统一管理所有物理过滤。

改动

• PhysicsScene._createPreFilter 中将 shape.collider.entity.layer & mask 改为 shape.collider.collisionLayer & mask
• 更新 CharacterController 射线检测测试，使用 collisionLayer 替代 entity.layer

测试计划

• 验证 raycast 过滤使用 collisionLayer 正常工作
• 验证 sweep（boxCast / sphereCast / capsuleCast）过滤正常
• 验证 overlap 查询正常
• 运行已有物理单元测试

[coderabbitai]

Walkthrough

The physics scene's pre-filter logic for raycasts and sweeps now accesses collision layers directly via shape.collider.collisionLayer instead of through shape.collider.entity.layer. The test setup is updated accordingly to assign the layer value to the CharacterController component.

Changes

Cohort / File(s)	Summary
Physics Layer Property Access packages/core/src/physics/PhysicsScene.ts, tests/src/core/physics/PhysicsScene.test.ts	Changed collision layer source from entity layer property to collider's collisionLayer property for raycast/sweep pre-filtering. Updated test to set layer on CharacterController component instead of entity.

Estimated Code Review Effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

🐰 A layer here, a layer there,
Now colliders show they care,
Direct access, clean and bright,
Physics queries now see right! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: unifying scene query filtering to use collisionLayer instead of entity.layer across physics operations.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ 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/physics-scene-query-use-collision-layer

---

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 77.32%. Comparing base (8557031) to head (53ecec3).
⚠️ Report is 1 commits behind head on dev/2.0.

Additional details and impacted files

@@             Coverage Diff             @@
##           dev/2.0    #2964      +/-   ##
===========================================
- Coverage    77.54%   77.32%   -0.22%     
===========================================
  Files          900      900              
  Lines        98724    98724              
  Branches      9802     9809       +7     
===========================================
- Hits         76560    76343     -217     
- Misses       21998    22214     +216     
- Partials       166      167       +1     

Flag	Coverage Δ
unittests	77.32% <100.00%> (-0.22%)	⬇️

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

☔ View full report in Codecov by Sentry.
📢 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.

[cptbtptpbcptdtptp]

+1

[GuoLei1990]

总结

将场景查询（raycast/sweep/overlap）的过滤从 entity.layer 统一到 collider.collisionLayer，方向正确，与 Unity 的设计一致——Unity 用一套 layer 统一管理所有物理过滤。改动精准，只改了一行核心逻辑 + 测试对齐，没有多余改动。

问题

无。

改动范围小且方向清晰，代码干净。