1. 项目概述在Cocos Creator 3.6中开发2D物理游戏时很多开发者都会面临一个选择到底用Box2D物理模块还是用Builtin 2D物理模块更让人头疼的是这两个模块的碰撞监听机制看起来相似但底层实现和触发逻辑却有着天壤之别。我见过不少项目因为开发者没搞清楚这两者的区别导致碰撞检测时灵时不灵或者回调函数执行次数完全不符合预期最后不得不花大量时间排查问题。我自己在开发一个2D平台跳跃游戏时就踩过这个坑。当时为了追求更好的物理模拟精度选择了Box2D但在处理角色与地面的连续碰撞时发现onBeginContact回调有时会莫名其妙地触发两次。折腾了半天才发现是因为没理解Box2D物理步进Step与回调触发时机的关系。而切换到Builtin模块后虽然简单了却又发现缺少了onPreSolve和onPostSolve这类精细控制碰撞过程的能力。这篇文章我就结合官方文档和大量实测代码为你彻底拆解这两个模块在碰撞监听机制上的核心差异。我会从触发条件、回调时机、数据获取、性能影响四个维度进行深度对比并给出不同场景下的选型建议。无论你是刚接触Cocos物理系统的新手还是想优化现有项目的老手这篇文章都能帮你避开那些“坑”写出更稳定、高效的碰撞逻辑。2. 核心差异总览为什么不能混为一谈在深入细节之前我们先从宏观上把握Box2D和Builtin 2D物理模块的本质区别。这绝不是简单的“一个功能多一个功能少”的问题而是两种截然不同的物理引擎设计哲学在Cocos Creator中的体现。2.1 物理引擎的“血统”与设计目标Box2D是一个久负盛名、功能完整的2D刚体物理引擎库。Cocos Creator通过物理后端PhysX/Bullet等集成了它的核心功能。Box2D的设计目标是提供高度真实、可预测的物理模拟。为了实现这一点它将物理世界离散化为一个个固定的时间步Step在每个时间步内引擎会按顺序执行碰撞检测Broad Phase Narrow Phase、求解器迭代计算冲量、摩擦力等、积分更新位置速度。碰撞回调Contact Callback是这个严谨流程中的一环其触发严格遵循物理步进的节奏。Builtin 2D物理模块有时被称为内置物理或简单物理是Cocos Creator自主研发的一套轻量级系统。它的设计目标是高性能、易用、满足大多数2D游戏的基本需求。它采用更简化的连续碰撞检测CCD和离散求解逻辑牺牲了一些物理精度如复杂的关节、精确的碰撞点换来了更简单的API和更高的运行效率。它的碰撞监听更像是“事件驱动”一旦检测到碰撞体重叠就会尝试立即触发回调。2.2 碰撞监听机制的核心差异对比表为了让你一目了然我将最核心的差异总结成了下表特性维度Box2D 物理模块Builtin 2D 物理模块监听启用方式必须在RigidBody2D组件上手动勾选EnabledContactListener属性。无需额外启用。只要物体有Collider2D组件就会在碰撞时尝试触发回调。核心回调类型BEGIN_CONTACT,END_CONTACT,PRE_SOLVE,POST_SOLVE。提供了碰撞求解前后两个关键钩子。仅支持BEGIN_CONTACT和END_CONTACT。缺少对碰撞求解过程的精细控制。回调触发时机与物理步进PhysicsSystem2D.instance.step强绑定。回调在物理步进的计算过程中被调用。相对独立。在每帧的碰撞检测阶段结束后立即触发相应的回调。数据实时性回调函数中的contact对象如法向量、碰撞点代表当前物理步进开始时的状态。在POST_SOLVE中可获取求解后的冲量信息。回调函数中的信息基于当前帧的碰撞检测结果contact参数在Builtin中为null无法直接获取碰撞细节数据。性能开销更高。完整的物理模拟加上四个回调的触发对CPU有一定压力。更低。简化的物理模型和仅两个回调使其在大量物体场景下表现更佳。适用场景需要复杂物理交互如弹球、复杂关节、需要修改碰撞参数、追求物理真实性的游戏。对物理真实性要求不高需要快速原型开发、物体数量众多如弹幕、大量NPC的轻量级游戏。一个关键的心得不要把Builtin模块看作是Box2D的“阉割版”。它是为特定场景设计的“特化版”。如果你的游戏只需要“碰到没碰到”这种二元判断Builtin的简洁和高效是巨大优势。一旦你需要知道“以多大的力、在哪个点碰撞”Box2D才是唯一选择。3. 深度解析一监听启用与回调注册的“门槛”差异这是第一个也是最容易导致问题的差异点。很多开发者按照Box2D的文档写了代码放到Builtin项目里没反应或者反过来都会一头雾水。3.1 Box2D需要显式开启的“监听开关”在Box2D模块中物理世界默认是“沉默”的。即使两个刚体撞得再厉害如果你不告诉引擎“我想知道它们撞了”那么就不会有任何回调产生。这个“告诉”的动作就是在RigidBody2D组件上设置EnabledContactListener属性。操作路径在场景编辑器中选择一个带有RigidBody2D的节点 - 在属性检查器中找到RigidBody2D组件 - 展开EnabledContactListener选项并勾选。为什么这么设计这是Box2D出于性能的考虑。碰撞回调的计算和调用是有成本的。在一个复杂的物理世界里比如有成百上千个刚体如果每个碰撞都触发回调会给脚本系统带来巨大压力。因此它把这个选择权交给了开发者只有那些你真正关心、需要逻辑交互的刚体才为其开启监听。例如你只需要监听玩家角色与金币、敌人的碰撞而不需要监听背景装饰物之间的碰撞。代码层面的体现即使你在脚本中注册了全局或单个碰撞体的监听如果对应的RigidBody2D没有开启EnabledContactListener这些回调函数永远不会被执行。这是排查Box2D碰撞失效时首要检查的点。3.2 Builtin无门槛的“即碰即报”Builtin模块采用了完全相反的策略简单至上。只要一个节点上有Collider2D组件无论是BoxCollider2D, CircleCollider2D还是PolygonCollider2D当它与其他碰撞体发生重叠时引擎就会尝试触发回调。这意味着什么对于Builtin你永远不需要担心“忘了开监听”导致回调不触发。这大大降低了入门门槛也让原型开发速度飞快。你只需要挂上碰撞体写好回调函数它就能工作。潜在的风险这种便利性带来的是可控性的降低。在一个有很多静态地形碰撞体的场景中如果你不小心为所有地形都注册了全局碰撞监听那么每一帧可能都会有大量无用的回调被触发虽然单个回调开销小但数量多了依然会影响性能。因此在使用Builtin时更推荐使用针对单个碰撞体注册监听的方式精确控制哪些碰撞需要处理。3.3 注册方式的异同两者在注册监听的方式上语法是相似的这可能是造成混淆的原因之一。但它们的作用域和逻辑有细微差别。共同点都支持两种注册方式。针对单个碰撞体注册在拥有Collider2D组件的脚本中通过this.getComponent(Collider2D)获取引用然后调用其.on()方法。全局物理系统注册通过PhysicsSystem2D.instance.on()注册会监听场景中所有的碰撞事件。差异点对于Box2DEnabledContactListener是刚性前提。无论是单个注册还是全局注册都只对那些开启了该属性的刚体参与的碰撞有效。对于Builtin没有前提条件。全局注册会捕获所有碰撞单个注册只捕获该碰撞体参与的碰撞。示例代码注册监听import { _decorator, Component, Collider2D, PhysicsSystem2D, Contact2DType, IPhysics2DContact } from cc; const { ccclass, property } _decorator; ccclass(CollisionHandler) export class CollisionHandler extends Component { start() { // 方式一注册单个碰撞体的监听两者通用 let collider this.getComponent(Collider2D); if (collider) { collider.on(Contact2DType.BEGIN_CONTACT, this.onMyBeginContact, this); collider.on(Contact2DType.END_CONTACT, this.onMyEndContact, this); // Box2D独有 // collider.on(Contact2DType.PRE_SOLVE, this.onMyPreSolve, this); // collider.on(Contact2DType.POST_SOLVE, this.onMyPostSolve, this); } // 方式二注册全局物理系统的监听两者通用但逻辑不同 if (PhysicsSystem2D.instance) { // 注意对于Box2D这仍然只对开启了EnabledContactListener的刚体有效 PhysicsSystem2D.instance.on(Contact2DType.BEGIN_CONTACT, this.onGlobalBeginContact, this); } } onMyBeginContact(self: Collider2D, other: Collider2D, contact: IPhysics2DContact | null) { console.log([单个] 开始碰撞: ${this.node.name} 与 ${other.node.name}); } onGlobalBeginContact(self: Collider2D, other: Collider2D, contact: IPhysics2DContact | null) { console.log([全局] 开始碰撞: ${self.node.name} 与 ${other.node.name}); } }4. 深度解析二回调类型与触发时机的“节奏”差异这是两个模块最核心、最本质的差异直接决定了你能在碰撞过程中做什么、以及何时做。4.1 Box2D四步舞曲精准控制Box2D的碰撞处理像一场精心编排的四步舞曲每一步都有其特定任务。理解这个流程对于实现高级物理交互至关重要。1. BEGIN_CONTACT开始接触时机在两个碰撞体的AABB包围盒首次被检测到重叠的那个物理步进Step开始时。关键特性只触发一次。即使两个物体在后续多个Step中持续穿透也不会再次触发直到它们分离后再次碰撞。用途处理碰撞开始的逻辑如播放撞击音效、触发任务、增加分数。注意此时物体的位置/速度可能还未被当前Step的求解器修正。2. PRE_SOLVE求解前时机在BEGIN_CONTACT之后物理求解器计算冲量、摩擦力等开始工作之前。关键特性每个发生碰撞的物理Step都会触发。即使物体持续接触在每一个Step中在求解前都会调用。这是Box2D独有的强大功能。用途动态修改碰撞属性。你可以在这里根据当前状态如角色是否在冲刺修改本次Step中碰撞的摩擦力(setFriction)、恢复系数弹性setRestitution或者通过contact.disabledOnce true临时禁用本次Step的碰撞响应比如实现“穿墙”技能。3. POST_SOLVE求解后时机在物理求解器完成计算之后物体位置和速度被更新之前。关键特性同样是每个发生碰撞的物理Step都会触发。与PRE_SOLVE配对出现。用途获取碰撞结果。你可以通过contact.getWorldManifold()获取碰撞点(points)和法向量(normal)更重要的是可以通过contact对象获取求解器计算出的冲量信息需通过特定方式用于计算伤害、屏幕震动强度等。4. END_CONTACT结束接触时机在两个碰撞体的AABB不再重叠的那个物理步进开始时。关键特性只触发一次。用途处理碰撞结束的逻辑如结束连击计时、移除持续伤害效果。一个完整的Box2D碰撞时序模拟 假设一个球持续压在地板上3个物理Step。Step 1: BEGIN_CONTACT - PRE_SOLVE - (物理求解) - POST_SOLVE Step 2: PRE_SOLVE - (物理求解) - POST_SOLVE // 持续接触无BEGIN/END Step 3: PRE_SOLVE - (物理求解) - POST_SOLVE Step 4: (球离开) - END_CONTACT4.2 Builtin简约二重奏即时反馈Builtin的流程则简单直接得多它只关心碰撞关系的开始和结束。1. BEGIN_CONTACT开始接触时机在每帧的碰撞检测阶段当检测到两个碰撞体在本帧首次发生重叠时触发。关键特性与渲染帧同步。只要物体在视觉上重叠了回调就可能被触发。由于没有PRE_SOLVE你无法在物理计算前修改碰撞参数。2. END_CONTACT结束接触时机在每帧的碰撞检测阶段当检测到两个上一帧还在重叠的碰撞体在本帧不再重叠时触发。关键特性同样与渲染帧同步。Builtin的“持续接触”在Builtin中两个物体持续重叠时除了第一帧的BEGIN_CONTACT后续帧不会有任何回调直到它们分开触发END_CONTACT。它没有“每帧处理碰撞”的概念。4.3 关键影响连续碰撞与单次回调这个差异在实际开发中影响巨大。假设你在做一个“角色站在地面上持续扣血”的效果。使用Box2D你可以在BEGIN_CONTACT里开始一个计时器然后在每个Step的PRE_SOLVE或POST_SOLVE中扣血。这样扣血频率与物理更新频率一致是稳定且可预测的。使用Builtin你只能在BEGIN_CONTACT触发时开始扣血比如启动一个每帧执行的update函数在END_CONTACT时停止。但扣血逻辑与物理引擎解耦你需要自己管理计时。如果角色在地面上轻微滑动导致瞬间分离又接触可能会意外触发多次BEGIN_CONTACT和END_CONTACT导致逻辑混乱。踩坑实录我曾用Builtin做一个“触碰陷阱持续掉血”的功能。由于角色动画导致碰撞体形状微调在某一帧可能刚好不重叠触发了END_CONTACT下一帧又重叠触发BEGIN_CONTACT。结果就是角色站在陷阱上疯狂闪烁掉血特效并瞬间死亡。解决办法是增加一个“碰撞延迟处理”的逻辑或者改用Box2D的PRE_SOLVE来稳定判断持续接触状态。5. 深度解析三碰撞数据获取的“信息量”差异当碰撞发生时我们不仅想知道“谁撞了谁”更想知道“撞在哪”、“以什么角度撞的”。在这方面两个模块的能力差距显著。5.1 Box2D信息完备的“体检报告”Box2D通过回调函数中的第三个参数contact: IPhysics2DContact提供了丰富的碰撞信息。这是其专业性的体现。核心方法contact.getWorldManifold()这个方法返回一个worldManifold对象包含两个最重要的属性points: Vec2[]碰撞点数组。在大多数简单碰撞如两个矩形边对边碰撞中数组通常有1-2个点表示碰撞发生的局部区域。重要提示这些点不一定精确在碰撞体边界上而是求解器计算出的用于解决穿透的“参考点”。对于游戏逻辑如播放碰撞火花特效通常足够。normal: Vec2碰撞法向量。这是一个单位向量方向从selfCollider指向otherCollider指示了解决碰撞最直接的方向即将selfCollider沿此方向推开可以最快解决重叠。注意这个向量不是碰撞面的角度它只指示分离方向。例如一个球从上方落到地面法向量是(0, 1)向上从左侧撞墙法向量是(1, 0)向右。获取相对速度 如果你想计算碰撞的剧烈程度比如根据速度决定音效大小你需要手动计算在碰撞点处的相对速度。onPostSolve(selfCollider: Collider2D, otherCollider: Collider2D, contact: IPhysics2DContact) { const worldManifold contact.getWorldManifold(); if (worldManifold.points.length 0) { const point worldManifold.points[0]; // 获取两个刚体在世界坐标系下指定点的线速度 const selfBody selfCollider.body!; const otherBody otherCollider.body!; const velAtPointSelf selfBody.getLinearVelocityFromWorldPoint(point); const velAtPointOther otherBody.getLinearVelocityFromWorldPoint(point); // 计算相对速度 const relativeVel velAtPointSelf.subtract(velAtPointOther); const impactSpeed relativeVel.length(); console.log(碰撞剧烈程度: ${impactSpeed}); } }动态修改碰撞属性仅在PRE_SOLVE中有效 这是Box2D的王牌功能之一允许你根据游戏状态实时改变物理规则。onPreSolve(selfCollider: Collider2D, otherCollider: Collider2D, contact: IPhysics2DContact) { // 示例如果角色正在发动“滑铲”技能则减少与地面的摩擦力 if (otherCollider.group PhysicsGroup.GROUND this.isSliding) { contact.setFriction(0.1); // 设置为低摩擦力 } // 示例实现一个“一次性穿透”的平台 if (otherCollider.group PhysicsGroup.ONE_WAY_PLATFORM this.velocityY 0) { contact.disabledOnce true; // 仅禁用本次Step的碰撞响应 } }5.2 Builtin仅有“事件通知”在Builtin模块中回调函数的contact参数始终是null。你无法直接获取碰撞点、法向量等任何几何信息。你能获取什么只有selfCollider和otherCollider这两个引用。你只能知道“A和B撞了”但不知道“怎么撞的”。如何弥补如果需要碰撞信息你必须手动计算这通常意味着更多的性能开销和更复杂的代码。判断大致方向通过比较两个碰撞体节点的世界位置(worldPosition)来估算方向。onBeginContact(self: Collider2D, other: Collider2D) { const selfPos self.node.worldPosition; const otherPos other.node.worldPosition; const delta otherPos.subtract(selfPos); // 这是一个非常粗略的方向判断不精确 if (Math.abs(delta.x) Math.abs(delta.y)) { // 可能是左右碰撞 if (delta.x 0) console.log(来自右侧的碰撞); } else { // 可能是上下碰撞 if (delta.y 0) console.log(来自上方的碰撞); } }使用其他组件辅助如果你的碰撞体形状简单如矩形可以结合UITransform或节点尺寸来估算碰撞区域但这无法处理复杂形状或旋转后的情况。经验之谈如果你需要基于碰撞点如击中不同部位造成不同伤害或碰撞法向量如沿墙面滑落来做游戏逻辑Builtin模块几乎无法满足需求。此时应果断选择Box2D。Builtin更适合用于简单的触发器Trigger逻辑比如角色进入区域、拾取物品这些场景只需要知道“进入/离开”事件。6. 深度解析四性能与调试的“隐性成本”选择哪个模块不仅仅是功能上的取舍更是对项目性能和开发体验的权衡。6.1 性能开销分析Box2D开销主要来自三方面。一是完整的物理模拟本身计算量就大二是四个回调函数的调用尤其是在复杂场景中PRE_SOLVE和POST_SOLVE每帧每个接触点都会触发三是从C物理引擎到TypeScript脚本层的数据传递如getWorldManifold存在一定的跨语言调用成本。在移动端低端设备上大量物理交互可能导致帧率下降。Builtin由于物理模型简化且只有两个回调其开销远小于Box2D。它的大部分计算在引擎内部高效完成脚本回调负担轻。对于“糖果传奇”这类有大量可消除元素但物理交互简单的游戏Builtin是保持流畅体验的关键。性能优化建议对于Box2D精打细算EnabledContactListener只为必要的刚体开启。简化回调逻辑避免在PRE_SOLVE/POST_SOLVE中进行复杂的计算或频繁的引擎API调用如查找节点、实例化对象。合理设置物理步频在项目设置中调整PhysicsSystem2D的fixedTimeStep。更高的频率更精确但更耗性能通常30-60Hz对2D游戏足够。对于Builtin避免全局监听除非必要尽量使用针对单个碰撞体的监听减少不必要的回调触发。善用碰撞分组Group通过物理分组过滤掉根本不需要检测的碰撞对这是最有效的优化手段。6.2 调试与问题排查Box2D的调试因其流程复杂问题也更多样。常见问题包括回调不触发首先检查RigidBody2D上的EnabledContactListener是否勾选。回调触发次数异常理解BEGIN/END只触发一次而PRE/POST每Step触发是关键。检查物理步进是否稳定。contact数据为null或异常确保只在Box2D模块下使用contact的方法并在POST_SOLVE中获取最终数据。使用物理调试绘制在PhysicsSystem2D实例中开启debugDrawFlags可以直观看到碰撞体形状、刚体原点、接触点等是排查碰撞体位置、形状不对的利器。Builtin的调试问题相对简单主要集中在回调不触发99%的情况是碰撞体没有正确设置如Sensor属性不对、或者碰撞分组设置错误导致根本不会检测。回调触发时机不符合预期牢记Builtin的回调与渲染帧同步可能受到帧率波动的影响。如果需要更稳定的时序可能需要自己基于update做逻辑判断。缺少碰撞细节这是功能限制不是bug。如果需要细节必须换用Box2D。7. 实战选型指南与迁移建议了解了所有差异后如何为你的项目做出正确选择7.1 我应该选择哪个模块回答以下几个问题就能找到答案你的游戏需要真实的物理反馈吗比如球类的弹跳、多米诺骨牌效应、复杂的铰链和滑轮是- 选择Box2D。否- 进入下一题。你需要知道碰撞的精确位置、法向量或者需要动态修改摩擦力、弹性吗是- 选择Box2D。否- 进入下一题。你的场景中会有大量数百个动态物理物体吗并且对性能极其敏感是- 优先考虑Builtin。如果Builtin的功能无法满足再尝试用Box2D并进行极端优化如减少活动刚体数量。否- 进入下一题。你的碰撞逻辑是否极其简单仅仅是“进入/离开”某个区域是-Builtin是更轻量、更简单的选择。否- 对于大多数需要非 trivial 碰撞交互的2D游戏Box2D提供的功能和可控性更值得依赖。简单总结平台跳跃、物理解谜、弹球、赛车-Box2D。RPG地图触发器、消消乐、卡牌游戏、大量单位存在的策略游戏-Builtin。7.2 从Builtin迁移到Box2D的注意事项如果你的项目一开始用了Builtin后期发现功能不够需要迁移请注意以下几点启用监听给所有需要碰撞回调的RigidBody2D勾选EnabledContactListener。回调函数改造移除所有对contact参数的依赖因为Builtin下它为null。如果你的逻辑依赖BEGIN_CONTACT/END_CONTACT这部分代码通常可以直接复用。将原来在update中模拟持续碰撞的逻辑比如持续扣血考虑迁移到PRE_SOLVE中。物理参数调整Box2D的物理参数密度、摩擦力、弹性与Builtin可能不同需要重新调试手感。性能回归测试迁移后务必在目标设备上进行性能测试关注帧率变化。7.3 一个常见的混合使用策略实际上一个项目可以同时使用两个模块吗技术上Cocos Creator不允许同时激活两个2D物理后端。但是有一种折中策略对于游戏中需要复杂物理交互的核心部分如玩家、主要敌人、可互动物体使用Box2D。 对于大量的、仅需要简单触发器的环境物体如伤害区域、拾取区域可以不用物理引擎而是使用自定义的几何检测如矩形/圆形重叠检测或利用Builtin的碰撞体但仅作为触发器Sensor并在脚本中每帧手动进行距离或范围判断。这样既保留了核心物理的精确性又避免了大量物理计算的开销。最后无论选择哪个模块都请务必在项目早期就进行充分的测试特别是在低性能设备上。物理和碰撞逻辑的bug往往在开发后期才暴露修正成本很高。希望这篇对比能帮你做出明智的选择少走弯路。