3D 物理

一个 3D 模型已经能导入、能动、能变形、能被照亮。这一页讲的是让它站在某处: 一个由 Jolt Physics 驱动的刚体世界,跑在它自己的 WebAssembly 模块里。

它与 2D 物理并存,不是取代:2D 场景保留它已经有的 求解器、单位和手感,而一个从不索取 3D 世界的项目也从不加载它。

刚体

一个实体同时带着 RigidBody3D 和一个形状时才在世界里。没有形状的刚体没有任何 广延可供碰撞,所以它干脆不被注册——而不是变成一个永远下落的隐形点。

cmds.spawn()
  .insert(Transform, { position: { x: 0, y: 400, z: 0 } })
  .insert(RigidBody3D, { bodyType: BodyType.Dynamic })
  .insert(CapsuleCollider3D, { radius: 30, halfHeight: 50 });

字段	作用
bodyType	Static 从不移动,Kinematic 由你搬动,Dynamic 由求解器解。
gravityScale	这个刚体分担的重力比例。0 是失重,不是「掉得慢」。
linearDamping / angularDamping	运动衰减的快慢。
fixedRotation	冻结刚体被给定的朝向——让角色不会倒下的那个开关。它不会把一个一开始就歪的刚体扶正。
continuousCollision	检查这一步走过的整条路径,而不只是它最后停在哪。子弹需要它;默认关闭,因为它更贵。

形状

组件	广延
BoxCollider3D	每个轴上的 halfExtents。
SphereCollider3D	radius。
CapsuleCollider3D	一个直立胶囊:halfHeight 是圆柱段的一半,两端各扣一个 radius 的半球,所以总高是 2 * (halfHeight + radius)。

注意

尺寸按世界单位书写,以米为单位抵达求解器,用的是 2D 世界同一个 pixelsPerUnit (默认 100)。一个按米调好的求解器在角色高 180 单位时完全不是它自己,所以这次换算 不是可选项——它正是一个 60 单位宽的胶囊会像人一样倒下的原因。

用导入的几何做碰撞

MeshCollider3D 直接拿网格自己的三角形做碰撞——地形、楼梯、房间内部, 这些正是盒子和胶囊说不出来的东西。

cmds.spawn()
  .insert(Transform, {})
  .insert(RigidBody3D, { bodyType: BodyType.Static })
  .insert(MeshCollider3D, { mesh: 'assets/models/level.esmesh' });

注意

它永远是静态的,不管 RigidBody3D 怎么写:三角汤没有惯性张量,求解器没有东西可推。 而且三角形是单面的——一块绕序朝下的地板,射线照样报命中,刚体却会直接穿过去。 导入的几何拦不住任何东西时,先怀疑这个。

需要会动的导入几何,就用 ConvexCollider3D:它拿同一批顶点最紧的那个凸体去碰撞, 而凸体对求解器来说和盒子一样容易。一块石头、一个倒角的箱子、一只会滚的木桶—— 凡是凹陷细节不需要被摸出来的东西。

cmds.spawn()
  .insert(Transform, { position: { x: 0, y: 400, z: 0 } })
  .insert(RigidBody3D, { bodyType: BodyType.Dynamic })
  .insert(ConvexCollider3D, { mesh: 'assets/models/rock.esmesh' });

看见形状

视口把每个 3D 碰撞体画成线框,并跟着实体一起转——屏幕上没有任何别的东西 能说出「模型外面那个盒子有多大」。它和 2D 碰撞体 gizmo 共用同一个开关。

一个实体只会拿到一个刚体形状,按 BoxCollider3D、SphereCollider3D、 MeshCollider3D、ConvexCollider3D、CapsuleCollider3D 的顺序挑。落选的那些——被禁用的、 被这个顺序盖住的、以及所有挂在没有启用 RigidBody3D 的实体上的——画成暗淡虚线: 仍然摆得动,但一眼就看得出世界不会拿它去碰撞。CharacterController3D 的胶囊 画在它旁边,因为角色是被扫掠的而不是被求解的。

注意

网格碰撞体画的是它三角形的包围盒而不是每一条边——那些三角形就是你已经在看的 这个网格,几千条投影出来的边只会把它埋掉。

游戏跑起来的时候

编辑器的 gizmo 在 Play 时全部隐藏,所以由运行中的游戏画它自己的。 需要弄清「它为什么卡在那儿」时,把 Physics3DDebugDraw 资源打开:

app.getResource(Physics3DDebugDraw).enabled = true;

字段	作用
enabled	默认关闭——每帧每条边一根线,这是有代价的。
showColliders	求解器真的建出来的每个刚体的形状。
showContacts	这一步报告的每个接触点上画一个十字。

注意

这里只画求解器真的建了的那些。被禁用的碰撞体属于编辑态,该在编辑器里看—— 运行中的游戏把它画出来就是在描述一场不可能发生的碰撞。

这层覆盖不参与深度测试,所以埋在墙里的形状照样看得见。调试视图就是要这样。

角色

CharacterController3D 取代 RigidBody3D 而不是与它并存:被求解器推的刚体 和自己扫掠的角色,是「这个实体在哪」的两个答案。每步从游戏逻辑设 velocity,再把结果读回来。

const c = world.get(player, CharacterController3D);
c.velocity.x = input.axis('move') * 200;
if (input.justPressed('jump') && c.isOnFloor) c.velocity.y = 500;

字段	作用
velocity	期望速度,世界单位/秒。y 为正就是跳。
stepHeight	能迈上去而不是被挡住的最高台阶。0 就什么都迈不上。
snapDown	过坡顶时向下够多远以贴住地面。0 是关掉。
maxSlope	能站住的最陡地面;比这更陡就会滑下去。
pushForce	撞上动态刚体时能推多用力。0 什么都推不动。
isOnFloor / floorNormal / realVelocity	输出,步进之后读。

注意

垂直分量由引擎替你维护:velocity.y = 0 的意思是「走」,不是「悬在空中」。 在 Jolt 里角色不会自己下落——垂直速度属于调用者——所以这一层替你积分重力, 而不是让每个调用者各自重新发现这件事。

角色是被扫掠的而不是被求解的,所以没有任何东西会自己给它让路:pushForce 就是它可以花在推东西上的力。默认值足以推动一个和它自己差不多大的箱子; 更重的要给更多,而 0 会让它把所有东西都当成墙。

关节

门、绳桥、升降台、布娃娃:它们都不是「一个刚体加一个形状」, 而是两个刚体外加一条「它们之间可以怎么动」的规则。 关节挂在声明它的那个实体上,并指名另一个实体。

cmds.spawn()
  .insert(Transform, { position: { x: 100, y: 0, z: 0 } })
  .insert(RigidBody3D, {})
  .insert(BoxCollider3D, { halfExtents: { x: 50, y: 100, z: 5 } })
  .insert(HingeJoint3D, {
    connectedEntity: frame,
    anchor: { x: -50, y: 0, z: 0 },   // 门自己的那条边
    axis: { x: 0, y: 1, z: 0 },       // 竖直
    enableLimit: true, lowerAngle: 0, upperAngle: Math.PI / 2,
  });

组件	规则
PointJoint3D	共享一个点,三轴自由转动。
HingeJoint3D	一根转轴,可选限位与马达。
SliderJoint3D	一条滑轨,可选限位与马达。
DistanceJoint3D	保持一段距离:只给 maxLength 就是绳,两个长度相等就是杆,给了 frequency 就是弹簧。
FixedJoint3D	完全不给自由度——两者作为一个整体运动。

anchor 与 axis 写在声明关节的那个实体自己的局部空间里,用世界单位, 在关节建立的那一刻按它的变换解算成世界量。那个姿态同时也是所有限位的零点: 一扇摆成关闭状态的门,angle 就是 0,开到 upperAngle。

motorSpeed 随时可以由游戏逻辑改写——变了就会重新驱动世界。反方向上, HingeJoint3D.angle 与 SliderJoint3D.translation 每步写回, 所以游戏可以直接问「门开了多少」,不必自己再积分一遍。

注意

collideConnected 默认关闭,而且它把两个刚体并进同一个装配而不是只对这一对生效: 一串关节所能连通到的所有刚体,彼此之间都不再碰撞。门需要这个(它不能和自己的门框打架), 布娃娃也需要。确实应该互相碰的时候再把它打开。

一个实体只有一个关节——世界按「声明它的实体」给约束建索引。 需要两个关节的实体就挂一个子实体给第二个,这也正好让场景说清楚哪个是哪个。

问世界「那里有什么」

Physics3D 资源用世界单位回答空间问题。

const q = app.getResource(Physics3D);

// 这条线上有东西吗?
const hit = q.raycast(muzzle, { x: 0, y: 0, z: -2000 }, ENEMIES);

// 这个东西「过得去」吗?射线是无限细的,会从一个运动刚体根本挤不过去的缝里穿过——
// 这正是扫掠形状回答的那个不同的问题。
const blocked = q.sphereCast(from, 30, travel, WORLD);

// 在往这里放东西之前,这里已经有什么了?
const occupants = q.overlapSphere(spawnPoint, 50);

查询	回答
raycast	一条线上最近的刚体。
sphereCast	一个运动的球最先撞上的刚体。
overlapSphere / overlapBox	已经在某个体积里的所有刚体。

注意

层掩码为 0 表示所有层,不是「一个都不要」:没有要求过滤的调用者是在要全部, 而另一种读法会让最常见的调用悄悄返回空。命中法线不做单位换算——它是方向, 乘上 pixelsPerUnit 只会得到一个长度 100 的单位向量。

碰撞层

每个刚体属于十六层中的一层,由项目声明哪些层之间能互相听见。两边都得同意—— 其中一边拒绝就足以让两个刚体互不相碰,所以一条规则只需要写一次就成立。

app.addPlugin(physics3dPlugin(url, {
  layerMasks: [
    0xFFFF,             // 0: 全部
    0xFFFF,             // 1: 世界
    ~(1 << 3),          // 2: 子弹 —— 不打自己人
    0xFFFF,             // 3: 那支队伍
  ],
}));

注意

一个刚体只属于一层,不像 2D 世界那样用一组类别位:Jolt 用单个 id 给刚体分类。 另外,刚体的层在它进入世界的那一刻就固定了,所以矩阵必须在任何刚体注册之前就位—— 插件在建世界时装它。

碰撞事件

每一步都会把「谁碰到了谁」发布到 Physics3DEvents 资源里。它按固定步长排空, 所以读它的系统必须跑在固定步里——从 Update 里读只会看到上一步碰巧留下的东西。

const events = app.getResource(Physics3DEvents);
for (const hit of events.contactEnters) {
  // 两个实体,以及它们相遇的位置
  spawnSparks(hit.pointX, hit.pointY, hit.pointZ);
}
for (const { sensorEntity, visitorEntity } of events.sensorEnters) {
  if (sensorEntity === goalZone) score(visitorEntity);
}

通道	带着什么
contactEnters	两个实体、接触法线和接触点。
contactExits	只有这一对——原因见下。
sensorEnters / sensorExits	传感器在前,然后是访客。

注意

结束的接触不带几何:在那一刻求解器锁着两个刚体,其中一个甚至可能已经被销毁, 所以除了「这一对是谁」之外什么都报不出来。另外,接触也会在刚体睡着时结束, 而不只是在它移开时——请把 exit 理解成「这一对不再接触了」,而不是「有东西动了」。

带 isSensor 的碰撞体报告重叠但不拦任何东西:访客直接穿过去,并且出现在 sensorEnters 而不是 contactEnters 里。

一个场景在哪个世界里

没有东西阻止一个实体同时带两套组件,但也没有东西会把它们合并:两个世界互相看不见, 一个 2D 碰撞体永远拦不住一个 3D 刚体。一个场景选一套。