主题
PhysicsUnit
纯物理单位负责场景中不依赖渲染外观的物理模拟，可配置质量、质心、重力、线速度与角速度阻尼以及自定义物理材质属性。它提供施力、冲量、力矩与指定位置速度查询等接口驱动运动，并支持碰撞组归属与单位之间的互不碰撞配对，用于精细控制碰撞交互。
概览
纯物理单位负责场景中不依赖渲染外观的物理模拟，可配置质量、质心、重力、线速度与角速度阻尼以及自定义物理材质属性。它提供施力、冲量、力矩与指定位置速度查询等接口驱动运动，并支持碰撞组归属与单位之间的互不碰撞配对，用于精细控制碰撞交互。
继承自
BasePart；可通过World:CreateUnit("PhysicsUnit", ...)创建；返回单个单位
函数
AddCollisionWithGroup
签名：AddCollisionWithGroup(groupName: String)
添加一个允许与当前物理单位发生碰撞的碰撞组。
| 参数 | 类型 | 说明 |
|---|---|---|
groupName | String | 碰撞组名 |
注册并添加允许碰撞的组
lua
-- @runtime server
local physicsService = game:GetService("PhysicsService")
local groupName = "MyGroup"
pcall(function() physicsService:RegisterCollisionGroup(groupName) end)
local unit = game:CreateUnit("PhysicsUnit", {})
unit:AddCollisionWithGroup(groupName)
print("当前碰撞组:", table.concat(unit:GetCollisionWithGroups(), ", "))RemoveCollisionWithGroup
签名：RemoveCollisionWithGroup(groupName: String)
从当前物理单位的允许碰撞列表中移除指定碰撞组。
| 参数 | 类型 | 说明 |
|---|---|---|
groupName | String | 碰撞组名 |
移除已添加的碰撞组
lua
-- @runtime server
local physicsService = game:GetService("PhysicsService")
local groupName = "TemporaryGroup"
pcall(function() physicsService:RegisterCollisionGroup(groupName) end)
local unit = game:CreateUnit("PhysicsUnit", {})
unit:AddCollisionWithGroup(groupName)
unit:RemoveCollisionWithGroup(groupName)GetCollisionWithGroups
签名：GetCollisionWithGroups() -> Array
获取当前物理单位允许发生碰撞的碰撞组名称列表。
返回值 Array
读取允许碰撞的组
lua
-- @runtime client
local unit = game:CreateUnit("PhysicsUnit", {})
for _, groupName in ipairs(unit:GetCollisionWithGroups()) do
print("允许碰撞组:", groupName)
endApplyForceToCenterOfMass
签名：ApplyForceToCenterOfMass(force: Vector3)
在物理单位的质心处施加一个力。
| 参数 | 类型 | 说明 |
|---|---|---|
force | Vector3 | 施加的力 |
给动态单位的质心施加向上的力
lua
-- @runtime client
local unit = game:CreateUnit("PhysicsUnit", { BodyType = Enums.BodyType.Dynamic, PhysicsActive = true })
unit:ApplyForceToCenterOfMass(Vector3.New(0, 200, 0))ApplyForceAtLocalPosition
签名：ApplyForceAtLocalPosition(force: Vector3, localPosition: Vector3)
在物理单位的局部坐标位置施加一个力。
| 参数 | 类型 | 说明 |
|---|---|---|
force | Vector3 | 施加的力 |
localPosition | Vector3 | 局部空间坐标系下的力的施加点 |
在动态单位的局部位置施加力
lua
-- @runtime client
local unit = game:CreateUnit("PhysicsUnit", { BodyType = Enums.BodyType.Dynamic, PhysicsActive = true })
unit:ApplyForceAtLocalPosition(Vector3.New(0, 100, 0), Vector3.New(1, 0, 0))ApplyForceAtWorldPosition
签名：ApplyForceAtWorldPosition(force: Vector3, worldPosition: Vector3)
在物理单位的世界坐标位置施加一个力。
| 参数 | 类型 | 说明 |
|---|---|---|
force | Vector3 | 施加的力 |
worldPosition | Vector3 | 世界空间坐标系下的力的施加点 |
在动态单位的世界位置施加力
lua
-- @runtime client
local unit = game:CreateUnit("PhysicsUnit", { Position = Vector3.New(0, 5, 0), BodyType = Enums.BodyType.Dynamic, PhysicsActive = true })
unit:ApplyForceAtWorldPosition(Vector3.New(0, 0, 100), unit.Position + Vector3.New(0, 0, 1))ApplyTorque
签名：ApplyTorque(torque: Vector3)
在物理单位上施加一个力矩，使其绕质心旋转。
| 参数 | 类型 | 说明 |
|---|---|---|
torque | Vector3 | 施加的力矩 |
给动态单位施加绕 Y 轴的力矩
lua
-- @runtime client
local unit = game:CreateUnit("PhysicsUnit", { BodyType = Enums.BodyType.Dynamic, PhysicsActive = true })
unit:ApplyTorque(Vector3.New(0, 10, 0))ApplyImpulse
签名：ApplyImpulse(impulse: Vector3)
在物理单位的质心处施加一个冲量，瞬间改变物体的速度。
| 参数 | 类型 | 说明 |
|---|---|---|
impulse | Vector3 | 施加的冲量 |
给动态单位的质心施加向上冲量
lua
-- @runtime client
local unit = game:CreateUnit("PhysicsUnit", { BodyType = Enums.BodyType.Dynamic, PhysicsActive = true })
unit:ApplyImpulse(Vector3.New(0, 50, 0))ApplyImpulseAtLocalPosition
签名：ApplyImpulseAtLocalPosition(impulse: Vector3, localPosition: Vector3)
在物理单位的局部坐标位置施加一个冲量。
| 参数 | 类型 | 说明 |
|---|---|---|
impulse | Vector3 | 施加的冲量 |
localPosition | Vector3 | 局部空间坐标系下的冲量施加点 |
在动态单位的局部位置施加冲量
lua
-- @runtime client
local unit = game:CreateUnit("PhysicsUnit", { BodyType = Enums.BodyType.Dynamic, PhysicsActive = true })
unit:ApplyImpulseAtLocalPosition(Vector3.New(0, 0, 50), Vector3.New(0, 0, 1))ApplyImpulseAtWorldPosition
签名：ApplyImpulseAtWorldPosition(impulse: Vector3, worldPosition: Vector3)
在物理单位的世界坐标位置施加一个冲量。
| 参数 | 类型 | 说明 |
|---|---|---|
impulse | Vector3 | 施加的冲量 |
worldPosition | Vector3 | 世界空间坐标系下的冲量施加点 |
在动态单位的世界位置施加冲量
lua
-- @runtime client
local unit = game:CreateUnit("PhysicsUnit", { Position = Vector3.New(0, 5, 0), BodyType = Enums.BodyType.Dynamic, PhysicsActive = true })
unit:ApplyImpulseAtWorldPosition(Vector3.New(50, 0, 0), unit.Position + Vector3.New(1, 0, 0))GetVelocityAtPosition
签名：GetVelocityAtPosition(position: Vector3) -> Vector3
获取物理单位上指定世界坐标位置的速度。
| 参数 | 类型 | 说明 |
|---|---|---|
position | Vector3 | 世界坐标位置 |
返回值 Vector3
读取动态单位指定世界位置的速度
lua
-- @runtime client
local unit = game:CreateUnit("PhysicsUnit", { Position = Vector3.New(0, 5, 0), BodyType = Enums.BodyType.Dynamic, PhysicsActive = true })
unit:ApplyImpulse(Vector3.New(50, 0, 0))
local velocity = unit:GetVelocityAtPosition(unit.Position + Vector3.New(1, 0, 0))
print("指定位置速度:", velocity)AddNoCollisionPairWithUnit
签名：AddNoCollisionPairWithUnit(targetUnit: SpaceUnit)
为当前 PhysicsUnit 添加一个互不碰撞的目标单位，使该单位与目标单位之间不再产生碰撞。
| 参数 | 类型 | 说明 |
|---|---|---|
targetUnit | SpaceUnit | 目标单位 |
与目标空间单位禁用碰撞
lua
-- @runtime client
local world = game:GetService("World")
local physicsUnit = world:CreateUnit("PhysicsUnit", { Position = Vector3.New(0, 2, 0) })
local targetUnit = world:CreateUnit("WorldUnit", { Position = Vector3.New(2, 2, 0) })
physicsUnit:AddNoCollisionPairWithUnit(targetUnit)
print("已添加互不碰撞目标:", targetUnit.Name)RemoveNoCollisionPairWithUnit
签名：RemoveNoCollisionPairWithUnit(targetUnit: SpaceUnit)
移除此前为当前 PhysicsUnit 添加的某个不碰撞单位对，使该单位与目标单位恢复碰撞。
| 参数 | 类型 | 说明 |
|---|---|---|
targetUnit | SpaceUnit | 目标单位 |
恢复与目标空间单位碰撞
lua
-- @runtime client
local world = game:GetService("World")
local physicsUnit = world:CreateUnit("PhysicsUnit", { Position = Vector3.New(0, 2, 0) })
local targetUnit = world:CreateUnit("WorldUnit", { Position = Vector3.New(2, 2, 0) })
physicsUnit:AddNoCollisionPairWithUnit(targetUnit)
physicsUnit:RemoveNoCollisionPairWithUnit(targetUnit)
print("已恢复与目标单位的碰撞:", targetUnit.Name)RemoveAllNoCollisionPairWithUnit
签名：RemoveAllNoCollisionPairWithUnit()
移除所有已添加的不碰撞单位对。
建立配对后清空不碰撞列表
lua
-- @runtime client
local world = game:GetService('World')
local unit = world:CreateUnit('PhysicsUnit', {})
local other = world:CreateUnit('WorldUnit', {})
if unit == nil or other == nil then return end
unit:AddNoCollisionPairWithUnit(other)
print('清空前:', #unit:GetNoCollisionPairUnitList())
unit:RemoveAllNoCollisionPairWithUnit()
print('清空后:', #unit:GetNoCollisionPairUnitList())
other:Destroy()
unit:Destroy()GetNoCollisionPairUnitList
签名：GetNoCollisionPairUnitList() -> Array
返回当前 PhysicsUnit 已添加的所有不碰撞单位组成的列表。
返回值 Array
查询不碰撞单位列表
lua
-- @runtime client
local world = game:GetService('World')
local unitA = world:CreateUnit('PhysicsUnit', {})
local unitB = world:CreateUnit('PhysicsUnit', {})
if unitA == nil or unitB == nil then return end
unitA:AddNoCollisionPairWithUnit(unitB)
local units = unitA:GetNoCollisionPairUnitList()
for _, other in ipairs(units) do
print('不碰撞单位:', other.Name)
end属性
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
ModelBindParent | Bool | false | 启用后，当父节点为 WorldUnit、RenderUnit、TriggerUnit、PhysicsUnit 等支持父子带动的场景单位时，当前单位将整体跟随父节点运动，保持与父节点的相对位置和旋转。运行时可通过脚本设置 .ModelBindParent = true/false 动态切换该行为。 |
PhysicsMeshId | String | official://mesh/59268 | 物理资源ID |
BodyType | Int | Enums.BodyType.Dynamic | 物体的物理运动类型：静态(Static)不可修改，运动学(Kinematic)仅通过脚本逻辑驱动，动态(Dynamic)参与完整物理模拟 |
PhysicsActive | Bool | true | 是否启用物理模拟，关闭后物体不参与碰撞和物理计算 |
CollisionGroup | String | "" | 物体所属的碰撞组名称，用于按碰撞组规则过滤碰撞关系 |
CanCollide | Bool | true | 是否参与物理碰撞，关闭后物体将穿透其他物体 |
CanTouch | Bool | true | 其他物体碰到此物体时，是否触发此物体的碰撞事件 |
CanTrigger | Bool | true | 此物体碰到其他物体时，是否触发对方的碰撞事件 |
Mass | Float | 10 | 物体的质量，仅对动态(Dynamic)物体生效 |
Massless | Bool | false | 启用后此物体的质量不计入父级装配体的总质量 |
CustomPhysicalProperties | PhysicalProperties | - | 自定义物理材质参数（摩擦力、弹性、密度等），为空时使用默认值 |
CenterOfMass | Vector3 | [0, 0, 0] | 物体在局部空间中的质心偏移位置 |
GravityEnabled | Bool | true | 是否受重力影响，仅对动态(Dynamic)物体生效 |
UseIndividualGravity | Bool | false | 启用后使用自定义的重力方向和大小替代全局重力 |
IndividualGravityValue | Vector3 | [0, -9.8, 0] | 自定义重力的方向和大小，默认为 (0, -9.8, 0) |
LinearDamping | Float | 0 | 线速度的阻尼系数，值越大减速越快，仅对动态(Dynamic)物体生效 |
AngularDamping | Float | 0 | 角速度的阻尼系数，值越大旋转减速越快，仅对动态(Dynamic)物体生效 |
AngularVelocity | Vector3 | [0, 0, 0] | 物理单位的角速度，表示物体绕各轴的旋转速率。 |
LinearVelocity | Vector3 | [0, 0, 0] | 物理单位的线速度，表示物体在三维空间中的移动速度。 |
Climbable | Bool | false | 玩家角色是否可以攀爬此物体，仅对静态(Static)物体生效 |
CanQuery | Bool | true | 是否参与空间射线检测（Raycast、Spherecast 等），关闭后射线将穿透此物体 |
事件
OnCollisionEnter
签名：OnCollisionEnter(otherUnit: Unit)
当其他物体开始与此物体发生碰撞时触发
| 参数 | 类型 | 说明 |
|---|---|---|
otherUnit | Unit | 与之发生碰撞的另一个物体 |
OnCollisionExit
签名：OnCollisionExit(otherUnit: Unit)
当其他物体与此物体结束碰撞时触发
| 参数 | 类型 | 说明 |
|---|---|---|
otherUnit | Unit | 结束碰撞的另一个物体 |
OnLocalCollisionEnter
签名：OnLocalCollisionEnter(info: CollisionCallbackInfo)
当其他物体开始与此物体发生碰撞时在本地触发，回调参数为 CollisionCallbackInfo
| 参数 | 类型 | 说明 |
|---|---|---|
info | CollisionCallbackInfo | 碰撞回调信息 |
OnLocalCollisionExit
签名：OnLocalCollisionExit(info: CollisionCallbackInfo)
当其他物体与此物体结束碰撞时在本地触发；若碰撞对方在结束碰撞前被销毁，也会补发该事件。回调参数为 CollisionCallbackInfo
| 参数 | 类型 | 说明 |
|---|---|---|
info | CollisionCallbackInfo | 碰撞回调信息 |