fix-3d-physics-collisions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Diagnose and fix 3D physics collisions

诊断并修复 3D 物理碰撞

Important

重要事项

Use the unity cli (
```
unity command --format json
```
) and the
```
unity-cli
```
and
```
unity-pipeline
```
skills for each step.
Don't use
```
using
```
directives or unqualified types in the
```
snippet
```
for
```
eval
```
, because the compiler only reads
```
using UnityEngine
```
, and a bare
```
AssetDatabase
```
or
```
Object
```
causes errors (CS0246 / CS0103 / CS0104).
```
return
```
what you want to read; it arrives at
```
data.result.result
```
.
Create a restore point you can roll back to if your changes fail.
Do only what's asked. Don't change unrelated assets or files.
Avoid long explanations.
Never leave verification code in the user's script. Never build logging or detection they didn't ask for, because it clutters their project and console. Read state through
```
eval
```
instead, as described in Final step.

每个步骤都使用 unity CLI（
```
unity command --format json
```
）以及
```
unity-cli
```
和
```
unity-pipeline
```
skill。
在
```
eval
```
的
```
snippet
```
中不要使用
```
using
```
指令或未限定类型名的类型，因为编译器只会读取
```
using UnityEngine
```
，而裸用的
```
AssetDatabase
```
或
```
Object
```
会导致错误（CS0246 / CS0103 / CS0104）。
```
return
```
你想读取的内容；结果会出现在
```
data.result.result
```
。
创建一个还原点，以便在修改失败时回滚。
只做被要求的事情。不要修改无关的 asset 或文件。
避免冗长解释。
绝不要在用户脚本中留下验证代码。绝不要构建用户未要求的日志或检测逻辑，因为它们会污染项目和控制台。请按照最后一步所述，通过
```
eval
```
读取状态。

Full topic map

完整主题索引

Before you go forward with a workflow or diagnosis:

Open and read the documentation page(s) that cover the specific subject related to what you intend to do or fix and check if you've missed anything.
Name the file(s) you read in your response.

This is because your training knowledge about Unity might be out of date, incorrect, or for the wrong Unity version.

If the prompt matches a STOP CHECK Fast-Path, skip this reading, because the Fast-Path answer is the complete response and already agrees with these pages.

If the Editor install folder has a

Data/Documentation

folder (eg

...Unity/Hub/Editor/6000.6.0b2/Editor/Data/Documentation

), read the html files from the

<editor-install>/Editor/Data/Documentation/en/Manual

folder. Otherwise the docs pages are online at

https://docs.unity.com/en-us/engine/<VERSION>/manual/

Links inside the pages start with
```
/engine/
```
. Add
```
https://docs.unity.com/en-us
```
before them.

If the page doesn't exist for that Unity version, use the

href

in the

xrefmap.yml

entry instead (e.g.

href: 'Rigidbody.AddForce.html'

https://docs.unity3d.com/<VERSION>/Documentation/ScriptReference/Rigidbody.AddForce.html

Prefer fetching the page directly (for example

WebFetch

) over searching (for example

WebSearch

) — faster and lands on the exact reference. Only fetch what you need, and only search if you don't have the exact URL.

Before the first fetch, read the Unity version from

ProjectSettings/ProjectVersion.txt

, because the docs differ between versions. Replace

<VERSION>

in docs.unity.com and docs.unity3d.com links with only its major.minor (the first two numbers), because the full build number gives a 404.

Interaction between collider types — local
```
collider-types-interaction.html
```
: which collider pairs send collision or trigger messages.
OnCollision events — local
```
collider-interactions-oncollision.html
```
: when Unity calls the OnCollisionEnter, Stay, and Exit events.
OnTrigger events — local
```
collider-interactions-ontrigger.html
```
: how trigger colliders call OnTriggerEnter, Stay, and Exit.
Layer-based collision detection — local
```
LayerBasedCollision.html
```
: setting which layers collide in the Layer Collision Matrix.
Choose a collision detection mode — local
```
choose-collision-detection-mode.html
```
: picking Discrete or continuous detection for fast-moving objects.
Physics settings — local
```
class-PhysicsManager.html
```
: project-wide settings such as Contact Pairs Mode, Queries Hit Triggers, Invoke Collision Callbacks, and Simulation Mode.
Mesh collider component reference — local
```
class-MeshCollider.html
```
: Mesh Collider properties, including Convex and mesh cooking options.
Character Controller component reference — local
```
class-CharacterController.html
```
: how a CharacterController moves and collides without a Rigidbody.

在开始任何工作流或诊断之前：

打开并阅读涵盖你准备执行或修复的具体主题的文档页面，并检查是否有遗漏。
在回复中列出已读取的文件名。

这是因为你对 Unity 的训练知识可能已经过时、存在错误，或不适用于当前 Unity 版本。

如果提示词匹配 STOP CHECK Fast-Path，请跳过阅读，因为 Fast-Path 的回答就是完整回答，并且已经与这些页面达成一致。

如果 Editor 安装目录中有

Data/Documentation

文件夹（例如

...Unity/Hub/Editor/6000.6.0b2/Editor/Data/Documentation

），请从

<editor-install>/Editor/Data/Documentation/en/Manual

文件夹中读取 html 文件。否则，文档页面在线地址为

https://docs.unity.com/en-us/engine/<VERSION>/manual/

。

页面中的链接以
```
/engine/
```
开头。请在前面加上
```
https://docs.unity.com/en-us
```
。

如果当前 Unity 版本没有对应页面，请改用

xrefmap.yml

条目中的

href

（例如

href: 'Rigidbody.AddForce.html'

https://docs.unity3d.com/<VERSION>/Documentation/ScriptReference/Rigidbody.AddForce.html

）。

优先直接获取页面（例如

WebFetch

），而不是搜索（例如

WebSearch

）——这样速度更快，而且能直接定位到准确的参考页面。只获取所需内容；只有在没有确切 URL 时才进行搜索。

首次获取页面前，请从

ProjectSettings/ProjectVersion.txt

中读取 Unity 版本，因为不同版本的文档存在差异。请将 docs.unity.com 和 docs.unity3d.com 链接中的

<VERSION>

替换为仅包含 major.minor 的版本号（即前两个数字），因为使用完整构建号会返回 404。

Collider 类型之间的交互——本地文件
```
collider-types-interaction.html
```
：哪些 Collider 组合会发送碰撞或触发器消息。
OnCollision 事件——本地文件
```
collider-interactions-oncollision.html
```
：Unity 何时调用 OnCollisionEnter、Stay 和 Exit 事件。
OnTrigger 事件——本地文件
```
collider-interactions-ontrigger.html
```
：Trigger Collider 如何调用 OnTriggerEnter、Stay 和 Exit。
基于层的碰撞检测——本地文件
```
LayerBasedCollision.html
```
：在 Layer Collision Matrix 中设置哪些层发生碰撞。
选择碰撞检测模式——本地文件
```
choose-collision-detection-mode.html
```
：为快速移动的对象选择 Discrete 或 Continuous 检测。
物理设置——本地文件
```
class-PhysicsManager.html
```
：项目范围设置，例如 Contact Pairs Mode、Queries Hit Triggers、Invoke Collision Callbacks 和 Simulation Mode。
Mesh Collider 组件参考——本地文件
```
class-MeshCollider.html
```
：Mesh Collider 属性，包括 Convex 和网格 cooking 选项。
Character Controller 组件参考——本地文件
```
class-CharacterController.html
```
：CharacterController 如何在没有 Rigidbody 的情况下移动并发生碰撞。

API reference

API 参考

The API is

UnityEngine.Physics

UnityEngine.Rigidbody

UnityEngine.Collider

UnityEngine.CharacterController

, and

UnityEngine.PhysicsScene

, part of the Unity Engine. It is versioned by Unity version, so check the project's Unity version before relying on a specific class or method.

Use the
```
unity-cli
```
skill to check the project's Unity version.
If the Editor install folder has a
```
Data/Documentation
```
folder, grep the html files in the
```
en/ScriptReference
```
folder inside, and skip the remaining steps.

Otherwise, fetch and cache

https://docs.unity3d.com/<VERSION>/Documentation/ScriptReference/xrefmap.yml

. This file lists every public API member's fully qualified name as a

uid

(e.g.

uid: 'UnityEngine.Rigidbody.AddForce(UnityEngine.Vector3)'

Grep the yml file locally for a class or method instead of refetching per lookup. The file is large (about 6 MB), so don't read the whole file.

Convert the

uid

to a markdown page: remove the parameters in brackets, lowercase it, replace

with

, and add

.md

. Then fetch

https://docs.unity.com/en-us/engine/<VERSION>/script-reference/<converted uid>

. For example,

UnityEngine.Rigidbody.AddForce(UnityEngine.Vector3)

https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unityengine/rigidbody/addforce.md

. All overloads are on the same page.

Constructors use

ctor

(e.g.

unityengine/vector3/ctor.md

), and indexers use

item

(e.g.

unityengine/vector3/item.md

For operators, fetch the class page (e.g.
```
unityengine/vector3.md
```
) and follow its link.

Always use the docs for the project's Unity version rather than relying on training knowledge, since APIs are frequently marked obsolete between versions.

涉及的 API 包括

UnityEngine.Physics

、

UnityEngine.Rigidbody

、

UnityEngine.Collider

、

UnityEngine.CharacterController

和

UnityEngine.PhysicsScene

，它们都是 Unity Engine 的一部分。API 会随 Unity 版本变化，因此依赖特定类或方法之前，请先检查项目的 Unity 版本。

使用
```
unity-cli
```
skill 检查项目的 Unity 版本。
如果 Editor 安装目录中有
```
Data/Documentation
```
文件夹，请在其中的
```
en/ScriptReference
```
文件夹内 grep html 文件，并跳过后续步骤。

否则，获取并缓存

https://docs.unity3d.com/<VERSION>/Documentation/ScriptReference/xrefmap.yml

。该文件会将每个公开 API 成员的完全限定名称列为

uid

（例如

uid: 'UnityEngine.Rigidbody.AddForce(UnityEngine.Vector3)'

）。

在本地 grep yml 文件以查找类或方法，而不是每次查找都重新获取。该文件很大，约为 6 MB，因此不要读取整个文件。
将
```
uid
```
转换为 markdown 页面：移除方括号中的参数，将其转为小写，把
```
.
```
替换为
```
/
```
，然后添加
```
.md
```
。接着获取
```
https://docs.unity.com/en-us/engine/<VERSION>/script-reference/<converted uid>
```
。例如，
```
UnityEngine.Rigidbody.AddForce(UnityEngine.Vector3)
```
=>
```
https://docs.unity.com/en-us/engine/<VERSION>/script-reference/unityengine/rigidbody/addforce.md
```
。所有重载都位于同一页面。
- 构造函数使用
```
ctor
```
  （例如
```
unityengine/vector3/ctor.md
```
  ），索引器使用
```
item
```
  （例如
```
unityengine/vector3/item.md
```
  ）。
- 对于运算符，请获取类页面（例如
```
unityengine/vector3.md
```
  ）并沿其中的链接继续操作。

始终使用项目对应 Unity 版本的文档，而不要依赖训练知识，因为 API 经常会在不同版本之间被标记为过时。

Procedure

操作流程

Before you call any tool, match the prompt against the STOP CHECK Fast-Paths. If one matches, write that answer and go to step 5.
Otherwise, get the Unity version from
```
ProjectSettings/ProjectVersion.txt
```
, and check which physics components the objects use (Rigidbody, Collider,
```
CharacterController
```
). If there's no project or no version, assume Unity 6000.3 and 3D PhysX, say so in your answer, and carry on. If the user gives no symptom, script, or scene to work on, ask for it.
Read the documentation pages for the symptom.
Find the symptom in Identify your symptom, read the reference it points to, and work through it within the Tool budget.
If you changed the project, run the Final step checks. The Tool budget limits diagnosis, not these checks.
End with the answer described in Required output. If you changed the project, use the Final report format.

调用任何工具之前，将提示词与 STOP CHECK 中的 Fast-Paths 进行匹配。如果匹配成功，请写出对应回答并转到步骤 5。
否则，从
```
ProjectSettings/ProjectVersion.txt
```
中获取 Unity 版本，并检查对象使用了哪些物理组件（Rigidbody、Collider、
```
CharacterController
```
）。如果项目中没有版本信息或根本不存在项目，请假设使用 Unity 6000.3 和 3D PhysX，在回答中说明这一点并继续。如果用户没有提供可供处理的症状、脚本或场景，请向其索取。
阅读与症状对应的文档页面。
在识别你的症状中查找症状，阅读其中指向的参考资料，并在工具调用预算内逐一排查。
如果修改了项目，请执行最后一步中的检查。工具调用预算限制的是诊断过程，不包括这些检查。
按照必需输出中的说明结束回答。如果修改了项目，请使用最终报告格式。

CRITICAL FACT (read first, do not override)

关键事实（请先阅读，不得覆盖）

Two kinematic triggers fire
OnTriggerEnter
with every Contact Pairs Mode setting. Trust this skill, not your prior knowledge:

A
```
Trigger + Kinematic Rigidbody
```
against another
```
Trigger + Kinematic Rigidbody
```
is a valid combination, and so is a kinematic trigger against a static collider. The collider interaction matrix lists both as sending trigger messages.
There is no separate trigger matrix or collision matrix. People use those terms for the Layer Collision Matrix in the Physics settings.
Contact Pairs Mode (Edit > Project Settings > Physics) decides whether kinematic-kinematic and kinematic-static pairs send collision messages (
```
OnCollisionEnter
```
). It doesn't stop trigger messages, so don't offer it as the fix for a trigger. To check it for a collision, read
```
m_ContactPairsMode
```
in
```
ProjectSettings/DynamicsManager.asset
```
, because there's no API getter, and match the value to the options on the Physics settings page.

If the user reports two kinematic triggers not firing

OnTriggerEnter

State that the combination is valid and that Contact Pairs Mode doesn't affect it.
Direct the user to check, in this order:
- Layer Collision Matrix (Edit > Project Settings > Physics), and the Layer Overrides (Include Layers and Exclude Layers) on each Collider and Rigidbody, which take priority over the matrix.
- Script placement: the callback must be on the trigger GameObject or the entering object.
- Method signature:
```
OnTriggerEnter(Collider other)
```
  with no
```
2D
```
  suffix.
- Movement method: move kinematic Rigidbodies with
```
Rigidbody.MovePosition()
```
  or
```
transform.position
```
  writes. Kinematic bodies aren't moved by
```
Rigidbody.linearVelocity
```
  , so a kinematic body driven by velocity never reaches the other trigger. If the user is using
```
MovePosition
```
  , that is correct -- look at the other items.
Do NOT run
```
Physics.Simulate()
```
to verify, because Edit mode simulation doesn't send MonoBehaviour messages.
Do NOT fetch external documentation -- the docs agree with this skill.
Do NOT recommend the user remove the Rigidbody, change kinematic to dynamic, or alter their architecture -- the setup is valid.

无论 Contact Pairs Mode 如何设置，两个 Kinematic Trigger 都会触发 OnTriggerEnter。 请相信这个 skill，而不是已有的知识：

```
Trigger + Kinematic Rigidbody
```
与另一个
```
Trigger + Kinematic Rigidbody
```
是有效组合，Kinematic Trigger 与静态 Collider 的组合同样有效。Collider 交互矩阵将这两种组合都列为会发送触发器消息。
不存在单独的 Trigger 矩阵或 Collision 矩阵。人们通常使用这两个术语来指 Physics 设置中的 Layer Collision Matrix。
Contact Pairs Mode（Edit > Project Settings > Physics）决定 Kinematic-Kinematic 和 Kinematic-Static 对象对是否发送碰撞消息（
```
OnCollisionEnter
```
）。它不会阻止 Trigger 消息，因此不要将它作为 Trigger 问题的修复方案。要检查碰撞设置，请读取
```
ProjectSettings/DynamicsManager.asset
```
中的
```
m_ContactPairsMode
```
，因为没有对应的 API getter；然后将该值与物理设置页面上的选项进行匹配。

如果用户报告两个 Kinematic Trigger 未触发

OnTriggerEnter

：

说明该组合是有效的，并且 Contact Pairs Mode 不会影响它。
引导用户按以下顺序检查：
- Layer Collision Matrix（Edit > Project Settings > Physics），以及每个 Collider 和 Rigidbody 上的 Layer Overrides（Include Layers 和 Exclude Layers）；这些覆盖设置的优先级高于矩阵。
- 脚本位置：回调必须位于 Trigger GameObject 或进入的对象上。
- 方法签名：
```
OnTriggerEnter(Collider other)
```
  ，不得带
```
2D
```
  后缀。
- 移动方式：使用
```
Rigidbody.MovePosition()
```
  或直接写入
```
transform.position
```
  来移动 Kinematic Rigidbody。Kinematic Body 不会被
```
Rigidbody.linearVelocity
```
  移动，因此由速度驱动的 Kinematic Body 永远不会到达另一个 Trigger。如果用户使用的是
```
MovePosition
```
  ，则这一点是正确的——应检查其他项目。
不要运行
```
Physics.Simulate()
```
进行验证，因为 Edit 模式下的模拟不会发送 MonoBehaviour 消息。
不要获取外部文档——文档与这个 skill 的结论一致。
不要建议用户移除 Rigidbody、将 Kinematic 改为 Dynamic，或改变其架构——该设置是有效的。

Required output -- non-negotiable

必需输出——不可协商

Every invocation MUST end with a user-facing answer that gives the diagnosis and fix, because tool calls alone don't help the user.

Hard stop: After 5 tool calls of any kind, stop calling tools and write the most-likely diagnosis from the Fast-Paths or checklists, even if not fully confirmed.

No permission-asking: Never end with "Would you like me to proceed?" or similar. If the script is in the project or an Editor is connected, apply the fix directly by editing the script, or the scene through the Editor. Otherwise, give a complete self-contained explanation. Don't ask, because asking permission costs the user another turn.

每次调用都必须以面向用户的回答结束，其中应给出诊断和修复方案，因为只有工具调用无法帮助用户。

强制停止：任意类型的工具调用达到 5 次后，停止调用工具，并根据 Fast-Paths 或检查清单写出最可能的诊断，即使尚未完全确认。

不要请求许可：绝不能以“Would you like me to proceed?”或类似话语结束。如果脚本位于项目中或已经连接 Editor，请直接编辑脚本或通过 Editor 修改场景来应用修复。否则，提供完整且可独立执行的说明。不要询问，因为这会让用户再进行一轮交互。

STOP CHECK -- match before any tool call

STOP CHECK——在任何工具调用之前匹配

Before calling any tool, scan the user's prompt against the Fast-Paths below. The first match is the complete response -- write the answer and stop. Don't search the project, read files, inspect the scene, run C# in the Editor, or fetch documentation, because these answers are already verified.

调用任何工具之前，将用户提示词与下面的 Fast-Paths 进行匹配。第一个匹配项就是完整回答——写出答案并停止。不要搜索项目、读取文件、检查场景、在 Editor 中运行 C# 或获取文档，因为这些答案已经过验证。

Fast-Path 1 -- 2D physics or DOTS

Fast-Path 1——2D 物理或 DOTS

2D physics (
```
Rigidbody2D
```
,
```
Collider2D
```
,
```
OnCollisionEnter2D
```
,
```
Physics2D
```
): if the
```
create-2d-physics
```
skill is installed, use it instead, because it covers both 2D physics systems. Otherwise say this skill covers 3D physics only, and stop.
DOTS (
```
PhysicsCollider
```
,
```
ICollisionEventsJob
```
,
```
ITriggerEventsJob
```
,
```
Unity.Physics
```
, Havok, ECS, Entities): if a
```
physics-dots
```
skill is installed, use it instead. Otherwise start with a one-sentence disclaimer that DOTS physics is outside this skill's scope, give a brief best-effort answer with the DOTS APIs (
```
PhysicsBody
```
,
```
PhysicsCollider
```
,
```
ICollisionEventsJob
```
,
```
SimulationSingleton
```
), and end with one documentation link.

Don't apply 3D PhysX or MonoBehaviour rules to these questions, and don't suggest switching physics systems.

2D 物理（
```
Rigidbody2D
```
、
```
Collider2D
```
、
```
OnCollisionEnter2D
```
、
```
Physics2D
```
）：如果已安装
```
create-2d-physics
```
skill，请改用它，因为它涵盖两套 2D 物理系统。否则，说明此 skill 仅涵盖 3D 物理，然后停止。
DOTS（
```
PhysicsCollider
```
、
```
ICollisionEventsJob
```
、
```
ITriggerEventsJob
```
、
```
Unity.Physics
```
、Havok、ECS、Entities）：如果已安装
```
physics-dots
```
skill，请改用它。否则，先用一句话声明 DOTS 物理不在此 skill 的范围内，再使用 DOTS API（
```
PhysicsBody
```
、
```
PhysicsCollider
```
、
```
ICollisionEventsJob
```
、
```
SimulationSingleton
```
）给出简要的最佳尝试答案，并最后附上一个文档链接。

不要对这些问题套用 3D PhysX 或 MonoBehaviour 规则，也不要建议切换物理系统。

Fast-Path 2 -- Two kinematic triggers not firing OnTriggerEnter

Fast-Path 2——两个 Kinematic Trigger 未触发 OnTriggerEnter

If both objects are kinematic AND both are triggers: apply the CRITICAL FACT response, starting with the layer checks.

如果两个对象都是 Kinematic 且都是 Trigger：应用关键事实中的回答，并从 Layer 检查开始。

Fast-Path 3 -- Ragdoll explodes on frame 1 with no applied forces

Fast-Path 3——Ragdoll 在第一帧没有任何外力却炸开

If a ragdoll, jointed body, or character launches or explodes on the first frame with no applied forces:

Cause: overlapping colliders cause a one-frame depenetration velocity spike.
Fix: shrink the ragdoll colliders so none overlap at the starting pose. State it as the only primary fix.
Confirm with Window > Analysis > Physics Debugger, which the user opens. It highlights overlapping pairs on the first frame.
Do NOT list joint limits, joint projection, joint configuration, joint types, mass ratios, or drive parameters as causes, even when the prompt mentions them, because they don't cause this symptom.
Do NOT recommend disabling
```
Enable Collision
```
on the joint as the primary fix, because it hides the overlap rather than removing it.

如果 Ragdoll、含关节的物体或角色在没有施加任何力的情况下于第一帧飞散或炸开：

原因：相互重叠的 Collider 产生了一帧的解穿透速度峰值。
修复：缩小 Ragdoll Collider，使初始姿势下没有任何 Collider 相互重叠。将其作为唯一的主要修复方案。
使用 Window > Analysis > Physics Debugger 进行确认，该窗口由用户打开。它会高亮显示第一帧中的重叠对象对。
不要将 joint limits、joint projection、joint configuration、joint types、mass ratios 或 drive parameters 列为原因，即使提示词提到了它们，因为这些因素不会导致此症状。
不要建议禁用 Joint 上的 Enable Collision 作为主要修复方案，因为这只会隐藏重叠，而不会消除重叠。

Fast-Path 4 -- CharacterController + OnCollisionEnter not firing

Fast-Path 4——CharacterController + OnCollisionEnter 未触发

If the moving object has a

CharacterController

and the user expects

OnCollisionEnter

OnCollisionEnter

never fires for movement by

CharacterController.Move()

. Use

OnControllerColliderHit(ControllerColliderHit hit)

instead.

Do NOT suggest adding a
```
Rigidbody
```
, because a
```
CharacterController
```
and a
```
Rigidbody
```
on the same object fight over its movement.

如果移动对象具有

CharacterController

，而用户期望触发

OnCollisionEnter

：

通过

CharacterController.Move()

进行的移动永远不会触发

OnCollisionEnter

。请改用

OnControllerColliderHit(ControllerColliderHit hit)

。

不要建议添加
```
Rigidbody
```
，因为同一对象上的
```
CharacterController
```
和
```
Rigidbody
```
会争抢移动控制权。

Fast-Path 5 -- AddForce stopped working after object settled

Fast-Path 5——对象静止后 AddForce 停止生效

AddForce

AddTorque

stopped working after the object landed or stopped:

Cause: the Rigidbody fell asleep.
Fix: call
```
Rigidbody.WakeUp()
```
before
```
AddForce
```
. Apply the code edit directly, and don't change the Input System or other unrelated code.

如果

AddForce

或

AddTorque

在对象落地或停止后不再生效：

原因：Rigidbody 已进入休眠状态。
修复：在调用
```
AddForce
```
前调用
```
Rigidbody.WakeUp()
```
。直接应用代码修改，不要更改 Input System 或其他无关代码。

Fast-Path 6 -- All physics frozen but raycasts still work

Fast-Path 6——所有物理行为均冻结，但 Raycast 仍然有效

If callbacks have stopped and forces and gravity have no effect, but

Physics.Raycast

still hits:

Time.timeScale

. Restore it to

1f

, typically in the pause menu or cutscene controller.

如果回调已经停止、力和重力均不起作用，但

Physics.Raycast

仍然能够命中：

Time.timeScale

为

。将其恢复为

1f

，通常可在暂停菜单或过场动画控制器中完成。

Fast-Path 7 -- Raycast origin inside the target collider

Fast-Path 7——Raycast 起点位于目标 Collider 内部

Physics.Raycast

returns false and the ray starts inside the target: read the notes on the Physics.Raycast page, then move the origin outside the collider. Don't suggest Queries Hit Backfaces, because it doesn't fix this case.

如果

Physics.Raycast

返回 false，且射线起点位于目标内部：阅读 Physics.Raycast 页面上的说明，然后将射线起点移到 Collider 外部。不要建议使用 Queries Hit Backfaces，因为它无法解决此情况。

Fast-Path 8 -- Raycast misses inactive GameObject or disabled Collider

Fast-Path 8——Raycast 未命中处于非活动状态的 GameObject 或已禁用的 Collider

If the target GameObject is inactive or its Collider is disabled: raycasts ignore it. Make sure

gameObject.activeInHierarchy

and

Collider.enabled

are both true before raycasting.

如果目标 GameObject 未处于活动状态或其 Collider 已被禁用：Raycast 会忽略它。执行 Raycast 前，确保

gameObject.activeInHierarchy

和

Collider.enabled

均为 true。

Fast-Path 9 -- Raycast misses a trigger

Fast-Path 9——Raycast 未命中 Trigger

Physics.Raycast

doesn't detect a trigger collider: pass

QueryTriggerInteraction.Collide

in that call, because it overrides Queries Hit Triggers. See QueryTriggerInteraction and the Physics settings.

如果

Physics.Raycast

无法检测到 Trigger Collider：在该次调用中传入

QueryTriggerInteraction.Collide

，因为它会覆盖 Queries Hit Triggers。请参阅 QueryTriggerInteraction 和物理设置。

Fast-Path 10 -- IgnoreLayerCollision suppression persisting across scenes

Fast-Path 10——IgnoreLayerCollision 导致的抑制跨场景持续存在

Physics.IgnoreLayerCollision

suppresses collisions unexpectedly or across scenes: recommend the Layer Collision Matrix (Edit > Project Settings > Physics) first, because it's explicit and doesn't depend on runtime calls. As a code-only fallback, call

Physics.IgnoreLayerCollision(layerA, layerB, false)

at scene load.

如果

Physics.IgnoreLayerCollision

意外抑制了碰撞，或该抑制跨场景持续存在：首先建议使用 Layer Collision Matrix（Edit > Project Settings > Physics），因为它更加明确，并且不依赖运行时调用。仅使用代码时的备用方案是在场景加载时调用

Physics.IgnoreLayerCollision(layerA, layerB, false)

。

Tool budget

工具调用预算

For cases not covered by the Fast-Paths: at most 5 tool calls before committing to an answer. Don't run C# in the Editor or fetch documentation to re-check rules this skill states, because they're already verified.

对于 Fast-Paths 未涵盖的情况：在给出答案前最多调用 5 次工具。不要在 Editor 中运行 C# 或获取文档来重新检查此 skill 已陈述的规则，因为这些规则已经过验证。

Identify your symptom

识别你的症状

Read the reference file that matches the user's symptom:

Collision checklist - read when
```
OnCollisionEnter
```
,
```
Stay
```
, or
```
Exit
```
doesn't fire or objects pass through each other. Step 10 covers collisions that fail only at speed.
Trigger checklist - read when
```
OnTriggerEnter
```
,
```
Stay
```
, or
```
Exit
```
doesn't fire. It checks Is Trigger, the Rigidbody rule, layers, the callback signature and location, and non-convex mesh triggers.
Raycast checklist - read when
```
Physics.Raycast
```
misses an object. It checks the LayerMask, non-convex mesh colliders, back faces, and UI targets.
Other symptoms - read when physics works in the Editor but not in a build, a moved collider isn't seen until the next step, there's a visible gap before contact, or a body stops responding.
Collision debugger - read when the user asks to see which contacts physics reports, or the checklists don't confirm a cause. It records contacts in the Editor without adding anything to the scene, and you delete it afterwards.

请读取与用户症状相符的参考文件：

碰撞检查清单——当
```
OnCollisionEnter
```
、Stay 或 Exit 未触发，或对象相互穿透时阅读。第 10 步涵盖仅在高速下发生的碰撞失败。
触发器检查清单——当
```
OnTriggerEnter
```
、Stay 或 Exit 未触发时阅读。它会检查 Is Trigger、Rigidbody 规则、Layer、回调签名和位置，以及非凸 Mesh Trigger。
Raycast 检查清单——当
```
Physics.Raycast
```
未命中对象时阅读。它会检查 LayerMask、非凸 Mesh Collider、背面和 UI 目标。
其他症状——当物理行为在 Editor 中正常但在构建版本中异常、移动后的 Collider 直到下一步才可见、接触前存在可见间隙，或物体停止响应时阅读。
碰撞调试器——当用户想查看物理系统报告了哪些接触，或者检查清单无法确认原因时阅读。它会在 Editor 中记录接触信息，而不向场景添加任何内容，之后应将其删除。

Console errors

控制台错误

If the user's Console shows one of these errors, apply the fix in its row, because Unity creates no physics shape for the collider (or keeps the old value) until the cause is fixed.

Error text	Root cause	Fix
"Concave Mesh Colliders are not supported when used with dynamic Rigidbody GameObjects"	A non-convex MeshCollider on a non-kinematic Rigidbody, so the object falls through other colliders and raycasts miss it.	Enable Convex on the MeshCollider. Otherwise, if the convex hull is too coarse, replace it with compound primitive colliders.
"Concave Mesh Colliders are not supported when used with the Is Trigger option enabled"	A non-convex MeshCollider with Is Trigger on, so the trigger never fires.	Enable Convex on the MeshCollider.
"Contact offset must be greater than zero"	A script or the Inspector set `contactOffset` to `0` or less, and Unity kept the old value.	Set a small positive value, such as `0.001` .

如果用户的 Console 显示以下错误之一，请应用对应行中的修复方案，因为在根本原因修复之前，Unity 不会为该 Collider 创建物理形状，或者会继续保留旧值。

错误文本	根本原因	修复方案
"Concave Mesh Colliders are not supported when used with dynamic Rigidbody GameObjects"	动态 Rigidbody 上使用了非凸 MeshCollider，因此对象会穿过其他 Collider，Raycast 也会漏掉它。	在 MeshCollider 上启用 Convex。否则，如果凸包过于粗糙，请改用由多个基础 Collider 组成的复合 Collider。
"Concave Mesh Colliders are not supported when used with the Is Trigger option enabled"	启用了 Is Trigger 的非凸 MeshCollider，因此 Trigger 永远不会触发。	在 MeshCollider 上启用 Convex。
"Contact offset must be greater than zero"	脚本或 Inspector 将 `contactOffset` 设置为 `0` 或更小的值，而 Unity 保留了旧值。	设置一个较小的正数，例如 `0.001` 。

Final step

最后一步

Run these checks in order. If any check fails, reread the docs pages to find out what you missed, fix it, and run the checks again.

Use
```
console_status
```
to check the project has zero console errors.
If the user didn't ask for proof and you don't suspect a fault, stop here.
Otherwise, enter Play mode once and reproduce the case. Read the outcome the user asked for through
```
eval
```
, such as whether the bullet's Rigidbody position stopped at the wall, not just the field you changed. Don't add logging or take screenshots, because they cost time and leave changes behind.
Exit Play mode and check again that the console has zero errors.

按顺序执行以下检查。如果任何检查失败，请重新阅读文档页面，找出遗漏之处，修复问题，然后再次运行检查。

使用
```
console_status
```
检查项目是否为零控制台错误。
如果用户没有要求提供证明，且你没有怀疑存在故障，请在此停止。
否则，进入 Play 模式一次并复现问题。通过
```
eval
```
读取用户要求的结果，例如子弹的 Rigidbody position 是否停在墙面处，而不只是读取你修改的字段。不要添加日志或截取屏幕截图，因为它们会耗费时间并留下多余改动。
退出 Play 模式，然后再次检查控制台是否为零错误。

Final report

最终报告

Give the user a short checklist of what you did and why. List any side effects, such as a project setting you changed or a temporary script you added and removed. If the user needs to follow up with more steps or decisions, list them. For example:

I made the following changes:

[✓] Set the bullet Rigidbody's Collision Detection to Continuous Speculative, because it moved far enough in one physics step to pass through the wall.

Follow these steps to see the effect:

1. Enter Play mode and fire at the wall.
2. Check the bullet stops at the wall instead of passing through it.

给用户一份简短清单，说明你做了什么以及原因。列出所有副作用，例如修改了项目设置，或者添加后又删除了临时脚本。如果用户还需要后续步骤或决策，请将其列出。例如：

I made the following changes:

[✓] Set the bullet Rigidbody's Collision Detection to Continuous Speculative, because it moved far enough in one physics step to pass through the wall.

Follow these steps to see the effect:

1. Enter Play mode and fire at the wall.
2. Check the bullet stops at the wall instead of passing through it.