WorldUnit

WorldUnit 是三维场景中兼具物理模拟与渲染表现的实体组件，可用 RenderMeshId 与 PhysicsMeshId 分别指定显示模型与物理碰撞资源，并通过 BodyType、Mass、LinearDamping、Angular...

概览

WorldUnit 是三维场景中兼具物理模拟与渲染表现的实体组件，可用 RenderMeshId 与 PhysicsMeshId 分别指定显示模型与物理碰撞资源，并通过 BodyType、Mass、LinearDamping、AngularDamping 等属性塑造运动特性。它支持按碰撞组管理碰撞关系与互不碰撞配对，还能对质心、局部坐标或世界坐标施加力、冲量与力矩，并可结合 OnCollisionEnter、OnLiftedBegin 等本地事件实现交互反馈。

继承自 BasePart；可通过 World:CreateUnit("WorldUnit", ...) 创建；返回单个单位

函数

AddCollisionWithGroup

签名：AddCollisionWithGroup(groupName: String)

添加一个允许与当前 WorldUnit 发生碰撞的碰撞组。

参数	类型	说明
groupName	String	碰撞组名

注册并添加允许碰撞的组

-- @runtime server
local physicsService = game:GetService("PhysicsService")
local groupName = "MyGroup"
pcall(function() physicsService:RegisterCollisionGroup(groupName) end)
local unit = game:GetService("World"):CreateUnit("WorldUnit", {})
unit:AddCollisionWithGroup(groupName)

RemoveCollisionWithGroup

签名：RemoveCollisionWithGroup(groupName: String)

从当前 WorldUnit 的允许碰撞列表中移除指定碰撞组。

参数	类型	说明
groupName	String	碰撞组名

移除已添加的碰撞组

-- @runtime server
local physicsService = game:GetService("PhysicsService")
local groupName = "TemporaryGroup"
pcall(function() physicsService:RegisterCollisionGroup(groupName) end)
local unit = game:GetService("World"):CreateUnit("WorldUnit", {})
unit:AddCollisionWithGroup(groupName)
unit:RemoveCollisionWithGroup(groupName)

GetCollisionWithGroups

签名：GetCollisionWithGroups() -> Array

获取当前 WorldUnit 允许发生碰撞的碰撞组名称列表。

返回值 Array

读取允许碰撞的组

-- @runtime client
local unit = game:GetService("World"):CreateUnit("WorldUnit", {})
for _, groupName in ipairs(unit:GetCollisionWithGroups()) do
    print("允许碰撞组:", groupName)
end

ApplyForceToCenterOfMass

签名：ApplyForceToCenterOfMass(force: Vector3)

在 WorldUnit 的质心处施加力，参数为力向量。

参数	类型	说明
force	Vector3	施加的力

给动态单位的质心施加向上的力

-- @runtime client
local unit = game:GetService("World"):CreateUnit("WorldUnit", { BodyType = Enums.BodyType.Dynamic, PhysicsActive = true })
unit:ApplyForceToCenterOfMass(Vector3.New(0, 200, 0))

ApplyForceAtLocalPosition

签名：ApplyForceAtLocalPosition(force: Vector3, localPosition: Vector3)

在 WorldUnit 的局部坐标位置施加力，参数分别为力向量与局部坐标位置。

参数	类型	说明
force	Vector3	施加的力
localPosition	Vector3	局部空间坐标系下的力的施加点

在动态单位的局部位置施加力

-- @runtime client
local unit = game:GetService("World"):CreateUnit("WorldUnit", { BodyType = Enums.BodyType.Dynamic, PhysicsActive = true })
unit:ApplyForceAtLocalPosition(Vector3.New(0, 100, 0), Vector3.New(1, 0, 0))

ApplyForceAtWorldPosition

签名：ApplyForceAtWorldPosition(force: Vector3, worldPosition: Vector3)

在 WorldUnit 的世界坐标位置施加力，参数分别为力向量与世界坐标位置。

参数	类型	说明
force	Vector3	施加的力
worldPosition	Vector3	世界空间坐标系下的力的施加点

在动态单位的世界位置施加力

-- @runtime client
local unit = game:GetService("World"):CreateUnit("WorldUnit", { 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)

对 WorldUnit 施加力矩，参数为力矩向量。

参数	类型	说明
torque	Vector3	施加的力矩

给动态单位施加绕 Y 轴的力矩

-- @runtime client
local unit = game:GetService("World"):CreateUnit("WorldUnit", { BodyType = Enums.BodyType.Dynamic, PhysicsActive = true })
unit:ApplyTorque(Vector3.New(0, 10, 0))

ApplyImpulse

签名：ApplyImpulse(impulse: Vector3)

在 WorldUnit 的质心处施加冲量，参数为冲量向量。

参数	类型	说明
impulse	Vector3	施加的冲量

给动态单位的质心施加向上冲量

-- @runtime client
local unit = game:GetService("World"):CreateUnit("WorldUnit", { BodyType = Enums.BodyType.Dynamic, PhysicsActive = true })
unit:ApplyImpulse(Vector3.New(0, 50, 0))

ApplyImpulseAtLocalPosition

签名：ApplyImpulseAtLocalPosition(impulse: Vector3, localPosition: Vector3)

在 WorldUnit 的局部坐标位置施加冲量，参数分别为冲量向量与局部坐标位置。

参数	类型	说明
impulse	Vector3	施加的冲量
localPosition	Vector3	局部空间坐标系下的冲量施加点

在动态单位的局部位置施加冲量

-- @runtime client
local unit = game:GetService("World"):CreateUnit("WorldUnit", { BodyType = Enums.BodyType.Dynamic, PhysicsActive = true })
unit:ApplyImpulseAtLocalPosition(Vector3.New(0, 0, 50), Vector3.New(0, 0, 1))

ApplyImpulseAtWorldPosition

签名：ApplyImpulseAtWorldPosition(impulse: Vector3, worldPosition: Vector3)

在 WorldUnit 的世界坐标位置施加冲量，参数分别为冲量向量与世界坐标位置。

参数	类型	说明
impulse	Vector3	施加的冲量
worldPosition	Vector3	世界空间坐标系下的冲量施加点

在动态单位的世界位置施加冲量

-- @runtime client
local unit = game:GetService("World"):CreateUnit("WorldUnit", { 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

获取 WorldUnit 在世界坐标指定位置处的速度，返回 Vector3。

参数	类型	说明
position	Vector3	世界坐标位置

返回值 Vector3

读取动态单位指定世界位置的速度

-- @runtime client
local unit = game:GetService("World"):CreateUnit("WorldUnit", { 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)

为当前 WorldUnit 与指定的目标单位建立互不碰撞的配对关系，使两者之间不再产生碰撞。

参数	类型	说明
targetUnit	SpaceUnit	目标单位

与另一个空间单位禁用碰撞

-- @runtime client
local world = game:GetService("World")
local worldUnit = world:CreateUnit("WorldUnit", { Position = Vector3.New(0, 2, 0) })
local targetUnit = world:CreateUnit("WorldUnit", { Position = Vector3.New(2, 2, 0) })

worldUnit:AddNoCollisionPairWithUnit(targetUnit)
print("已添加互不碰撞目标:", targetUnit.Name)

RemoveNoCollisionPairWithUnit

签名：RemoveNoCollisionPairWithUnit(targetUnit: SpaceUnit)

解除当前 WorldUnit 与指定目标单位之间此前建立的互不碰撞配对关系。

参数	类型	说明
targetUnit	SpaceUnit	目标单位

恢复与另一个空间单位碰撞

-- @runtime client
local world = game:GetService("World")
local worldUnit = world:CreateUnit("WorldUnit", { Position = Vector3.New(0, 2, 0) })
local targetUnit = world:CreateUnit("WorldUnit", { Position = Vector3.New(2, 2, 0) })

worldUnit:AddNoCollisionPairWithUnit(targetUnit)
worldUnit:RemoveNoCollisionPairWithUnit(targetUnit)
print("已恢复与目标单位的碰撞:", targetUnit.Name)

RemoveAllNoCollisionPairWithUnit

签名：RemoveAllNoCollisionPairWithUnit()

移除 WorldUnit 上的全部不碰撞单位对，无参数。

建立配对后清空不碰撞列表

-- @runtime client
local world = game:GetService('World')
local unit = world:CreateUnit('WorldUnit', {})
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

获取与当前 WorldUnit 建立了互不碰撞配对关系的单位列表。

返回值 Array

历史验证示例

-- @runtime client
local world = game:GetService("World")
local worldUnit = world:CreateUnit("WorldUnit", {})
if worldUnit == nil then return end
local result = worldUnit:GetNoCollisionPairUnitList()  -- 返回 Array
if result ~= nil then
    for index, item in ipairs(result) do
        print(index, item)
    end
end

SetRenderMeshWithDefaultSkin

签名：SetRenderMeshWithDefaultSkin(renderMeshId: String)

切换模型并应用默认皮肤，按传入的模型资源标识替换当前渲染模型，并使用该模型的默认皮肤。

参数	类型	说明
renderMeshId	String	模型资源

切换为项目配置的模型并应用默认皮肤

-- @runtime server
local world = game:GetService("World")
local worldUnit = world:CreateUnit("WorldUnit", {})
if worldUnit == nil then return end
-- renderMeshId 取项目为该单位配置的网格资源，不要凭空编造资源 ID
local renderMeshId = worldUnit.RenderMeshId
worldUnit:SetRenderMeshWithDefaultSkin(renderMeshId)
worldUnit:Destroy()

属性

名称	类型	默认值	说明
RenderMeshId	String	official://mesh/59268	模型资源ID，类型为字符串，用于指定该 WorldUnit 所引用的渲染模型资源标识。
LocalTransparencyModifier	Float	1	WorldUnit 的本地透明度乘数，用于在本机侧对其透明度做整体调节。
ModelBindParent	Bool	false	启用后，当父节点为 WorldUnit、RenderUnit、TriggerUnit、PhysicsUnit 等支持父子带动的场景单位时，当前单位将整体跟随父节点运动，保持与父节点的相对位置和旋转。运行时可通过脚本设置 .ModelBindParent = true/false 动态切换该行为。
TransparentRenderBias	Int	0	控制半透明物体的渲染层级偏置，值越小越先渲染。仅影响半透明物体，不透明物体不受此偏置影响。取值范围 [-15, 16]，超出会被截断到边界。注意：仅当遮挡规则(OcclusionType)为 组件半透明/镜头前推/玩家虚影 时生效；为 不处理 时本偏置不生效
UseSkinList	Bool	false	多槽位皮肤开关；启用后按各子网格的 SkinSlots 配置皮肤与染色。
SkinSlots	Array	[]	各子网格的皮肤与染色配置列表；元素包含 SkinId 和 ModelColor1~4。
PhysicsMeshId	String	official://mesh/59268	物理网格资源ID。缺省时，若初始创建时传入了 RenderMeshId，则默认使用该 RenderMeshId 作为物理资源；后续修改 .RenderMeshId 不会影响 PhysicsMeshId
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]	WorldUnit 的角速度，取值为 Vector3。
LinearVelocity	Vector3	[0, 0, 0]	WorldUnit 的线速度，取值为 Vector3。
Climbable	Bool	false	玩家角色是否可以攀爬此物体，仅对静态(Static)物体生效
Liftable	Bool	false	玩家角色是否可以抓举此物体，仅对动态(Dynamic)物体生效
UseCustomThrownAngle	Bool	false	启用后使用自定义的投掷角度替代默认投掷角度
CustomThrownAngle	Float	45.0	自定义的投掷角度，正值向上抛，负值向下抛
UseCustomThrownForce	Bool	false	启用后使用自定义的投掷力替代默认投掷力
CustomThrownForce	Float	150.0	自定义的投掷力度
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	碰撞回调信息

OnLiftedBegin

签名：OnLiftedBegin(liftunit: EggyUnit)

当此物体被玩家抓举起来时触发

参数	类型	说明
liftunit	EggyUnit	举起当前对象的生物

OnLiftedEnd

签名：OnLiftedEnd()

当此物体被玩家放下或投掷后触发