工坊手册

主题

WorldUnit ​

概览 ​

字段值
KindUnit · 单位 Unit
Realmcommon

继承关系 ​

继承成员 ​

3 个来源 / 30 属性 / 43 函数 / 6 事件

WorldUnit 是同时具备渲染显示与物理模拟能力的三维空间单元，可以配置模型资源、物理资源、碰撞开关、质量、重力、阻尼以及线速度与角速度等参数。它对外提供施加力、冲量与力矩的能力，并能通过碰撞组和互不碰撞配对来管理单元之间的碰撞关系。碰撞进入、碰撞退出以及被其他单元抓举等行为都会以事件形式向外通知。

适用场景 ​

适合在场景中生成可被碰撞、推动或投掷的实体，例如批量创建带渲染的碎片并为它们赋予随机角速度与冲量，让其按物理规律散开后再统一回收。

使用要点 ​

先通过 World:CreateUnit("WorldUnit", config) 创建实例，按需配置 RenderMeshId、PhysicsMeshId、Enums.BodyType.Dynamic 与 PhysicsActive。创建后可用 ApplyImpulse、ApplyForceToCenterOfMass 或 ApplyTorque 施加物理作用；GetVelocityAtPosition(position) 返回指定世界位置的 Vector3 速度向量。碰撞过滤使用碰撞组或不碰撞单位对接口，实体不再使用时调用 Destroy()。

注意事项 ​

施加力、冲量或力矩前，应把 BodyType 设为 Enums.BodyType.Dynamic 并启用 PhysicsActive；需要可见且可碰撞的实体时，同时设置有效的 RenderMeshId 与 PhysicsMeshId。UseSkinList 与 SkinSlots 是公开的运行时属性；修改槽位列表后应整体赋回 SkinSlots。

代码示例 ​

创建可见的动态物理单位 ​

lua
-- @runtime client
local world = game:GetService("World")
local unit = world:CreateUnit("WorldUnit", {
    Name = "DynamicCrate",
    RenderMeshId = "official://mesh/59268",
    PhysicsMeshId = "official://mesh/59268",
    Position = Vector3.New(0, 3, 0),
    BodyType = Enums.BodyType.Dynamic,
    PhysicsActive = true,
})
unit:ApplyImpulse(Vector3.New(0, 80, 0))

属性 (31) ​

Name类型默认值说明
RenderMeshIdStringofficial://mesh/59268模型资源ID，类型为字符串，用于指定该 WorldUnit 所引用的渲染模型资源标识。
LocalTransparencyModifierFloat1WorldUnit 的本地透明度乘数，用于在本机侧对其透明度做整体调节。
ModelBindParentBoolfalse启用后，当父节点为 WorldUnit、RenderUnit、TriggerUnit、PhysicsUnit 等支持父子带动的场景单位时，当前单位将整体跟随父节点运动，保持与父节点的相对位置和旋转。运行时可通过脚本设置 .ModelBindParent = true/false 动态切换该行为。
TransparentRenderBiasInt0WorldUnit 渲染半透明效果时使用的偏置值。
UseSkinListBoolfalse多槽位皮肤开关；启用后按各子网格的 SkinSlots 配置皮肤与染色。
SkinSlotsArray<SkinSlot>[]各子网格的皮肤与染色配置列表；元素包含 SkinId 和 ModelColor1~4。
PhysicsMeshIdStringofficial://mesh/59268WorldUnit 参与物理计算所使用的物理资源标识，取值为资源 URI 字符串。
BodyTypeIntEnums.BodyType.Dynamic物理类型标识；赋值时使用 Enums.BodyType.Static、Enums.BodyType.Kinematic 或 Enums.BodyType.Dynamic。
PhysicsActiveBooltrue是否启用物理模拟，关闭后物体不参与碰撞和物理计算
CollisionGroupString""WorldUnit 所属的碰撞组名称，用于碰撞关系的分组管理。
CanCollideBooltrue设置 WorldUnit 能否与其他单位发生碰撞。
CanTouchBooltrue设置本 WorldUnit 能否被其他单位触发碰撞事件。
CanTriggerBooltrue设置本 WorldUnit 能否触发其他单位的碰撞事件。
MassFloat10物体的质量，仅对动态(Dynamic)物体生效
MasslessBoolfalse设置 WorldUnit 是否为无质量。
CustomPhysicalPropertiesPhysicalProperties-自定义物理材质属性，类型为 PhysicalProperties，用于为 WorldUnit 提供自定义的物理材质数据。
CenterOfMassVector3[0, 0, 0]WorldUnit 的 CenterOfMass 属性，类型为 Vector3，表示该单位的质心，默认值为 (0, 0, 0)。
GravityEnabledBooltrue是否受重力影响，仅对动态(Dynamic)物体生效
UseIndividualGravityBoolfalse设置 WorldUnit 是否使用自定义重力值。
IndividualGravityValueVector3[0, -9.8, 0]WorldUnit 的 IndividualGravityValue 属性，类型为 Vector3，表示该单位使用的自定义重力值，默认值为 (0, -9.8, 0)。
LinearDampingFloat0线速度的阻尼系数，值越大减速越快，仅对动态(Dynamic)物体生效
AngularDampingFloat0角速度的阻尼系数，值越大旋转减速越快，仅对动态(Dynamic)物体生效
AngularVelocityVector3[0, 0, 0]WorldUnit 的 AngularVelocity 属性，类型为 Vector3，表示该单位的角速度，默认值为 (0, 0, 0)。
LinearVelocityVector3[0, 0, 0]WorldUnit 的 LinearVelocity 属性，类型为 Vector3，表示该单位的线速度，默认值为 (0, 0, 0)。
ClimbableBoolfalse玩家角色是否可以攀爬此物体，仅对静态(Static)物体生效
LiftableBoolfalse玩家角色是否可以抓举此物体，仅对动态(Dynamic)物体生效
UseCustomThrownAngleBoolfalse设置 WorldUnit 是否使用自定义投掷角度。
CustomThrownAngleFloat45.0设置 WorldUnit 被投掷时使用的角度。
UseCustomThrownForceBoolfalse布尔类型属性，用于决定投掷单位时是否使用 CustomThrownForce 指定的自定义力度。
CustomThrownForceFloat150.0浮点类型属性，表示投掷单位时使用的自定义力度数值。
CanQueryBooltrue布尔类型属性，用于控制该 WorldUnit 是否可以被射线检测等查询操作命中。默认值为 true，表示该单位参与查询。

关联类型 ​

事件 (6) ​

OnCollisionEnter ​

签名：OnCollisionEnter(otherUnit: Unit) 触发：local

WorldUnit 的碰撞进入事件，作用域为本地，触发时回调参数 otherUnit 为与该单位发生碰撞的另一个单位，类型为 Unit。

回调参数类型说明
otherUnitUnit与之发生碰撞的另一个物体

示例代码

监听编辑器动态物体开始碰撞

lua
-- @runtime client
local unit = game:GetService("World"):FindFirstChild("DynamicCrate", true)
if unit == nil or not unit:IsA("WorldUnit") then return end
unit.OnCollisionEnter:Once(function(otherUnit)
    print("开始碰撞:", otherUnit.Name)
end)

OnCollisionExit ​

签名：OnCollisionExit(otherUnit: Unit) 触发：local

WorldUnit 的碰撞退出事件，作用域为本地，触发时回调参数 otherUnit 为与该单位结束碰撞的另一个单位，类型为 Unit。

回调参数类型说明
otherUnitUnit结束碰撞的另一个物体

示例代码

监听编辑器动态物体结束碰撞

lua
-- @runtime client
local unit = game:GetService("World"):FindFirstChild("DynamicCrate", true)
if unit == nil or not unit:IsA("WorldUnit") then return end
unit.OnCollisionExit:Once(function(otherUnit)
    print("结束碰撞:", otherUnit.Name)
end)

OnLocalCollisionEnter ​

签名：OnLocalCollisionEnter(info: CollisionCallbackInfo) 触发：local

本地碰撞开始事件，回调参数为 info（类型 CollisionCallbackInfo），其中包含碰撞对方单位信息。

回调参数类型说明
infoCollisionCallbackInfo碰撞回调信息

示例代码

监听 WorldUnit.OnLocalCollisionEnter 事件的示例。

lua
-- @runtime client
local worldUnit = game:CreateUnit("WorldUnit", {})
worldUnit.OnLocalCollisionEnter:Once(function(info)
    print("info: " .. tostring(info))
end)

OnLocalCollisionExit ​

签名：OnLocalCollisionExit(info: CollisionCallbackInfo) 触发：local

本地碰撞结束事件，回调参数为 info（类型 CollisionCallbackInfo）。

回调参数类型说明
infoCollisionCallbackInfo碰撞回调信息

示例代码

监听 WorldUnit.OnLocalCollisionExit 事件的示例。

lua
-- @runtime client
local worldUnit = game:CreateUnit("WorldUnit", {})
worldUnit.OnLocalCollisionExit:Once(function(info)
    print("info: " .. tostring(info))
end)

OnLiftedBegin ​

签名：OnLiftedBegin(liftunit: EggyUnit) 触发：local

WorldUnit 的本地事件 OnLiftedBegin。当该 WorldUnit 开始被举起时触发，回调会收到一个名为 liftunit 的参数，其类型为 EggyUnit，对应该次举起行为相关的 Eggy 单位。

回调参数类型说明
liftunitEggyUnit举起当前对象的生物

示例代码

监听 WorldUnit.OnLiftedBegin 事件的示例。

lua
-- @runtime client
local worldUnit = game:CreateUnit("WorldUnit", {})
worldUnit.OnLiftedBegin:Once(function(liftunit)
    print("liftunit: " .. tostring(liftunit))
end)

OnLiftedEnd ​

签名：OnLiftedEnd() 触发：local

当本 WorldUnit 结束被抓举状态时触发的本地事件，回调无参数。

示例代码

监听 WorldUnit.OnLiftedEnd 事件的示例。

lua
-- @runtime client
local worldUnit = game:CreateUnit("WorldUnit", {})
worldUnit.OnLiftedEnd:Once(function()
    print("OnLiftedEnd event")
end)

函数 (16) ​

AddCollisionWithGroup ​

签名：AddCollisionWithGroup(groupName: String) -> void

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

参数类型说明
groupNameString要加入的碰撞组名称

返回值 void

示例代码

注册并添加允许碰撞的组

lua
-- @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) -> void

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

参数类型说明
groupNameString要移除的碰撞组名称

返回值 void

示例代码

移除已添加的碰撞组

lua
-- @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<String>

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

返回值 Array<String>

示例代码

读取允许碰撞的组

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

ApplyForceToCenterOfMass ​

签名：ApplyForceToCenterOfMass(force: Vector3) -> void

在 WorldUnit 的质心处施加力。参数 force 为 Vector3 类型的力向量，函数无返回值。

参数类型说明
forceVector3世界空间中的力向量

返回值 void

示例代码

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

lua
-- @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) -> void

在 WorldUnit 的局部坐标位置施加力。参数 force 为 Vector3 类型的力向量，localPosition 为 Vector3 类型的局部坐标位置，函数无返回值。

参数类型说明
forceVector3世界空间中的力向量
localPositionVector3物体局部空间中的施力点坐标

返回值 void

示例代码

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

lua
-- @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) -> void

在 WorldUnit 的世界坐标位置施加力。参数 force 为 Vector3 类型的力向量，worldPosition 为 Vector3 类型的世界坐标位置，函数无返回值。

参数类型说明
forceVector3世界空间中的力向量
worldPositionVector3世界空间中的施力点坐标

返回值 void

示例代码

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

lua
-- @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) -> void

对 WorldUnit 施加力矩。参数 torque 为 Vector3 类型的力矩向量，函数无返回值。

参数类型说明
torqueVector3各轴方向的力矩大小

返回值 void

示例代码

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

lua
-- @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) -> void

在 WorldUnit 的质心处施加冲量。参数 impulse 为 Vector3 类型的冲量向量，函数无返回值。

参数类型说明
impulseVector3冲量向量，方向和大小决定瞬时速度变化

返回值 void

示例代码

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

lua
-- @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) -> void

在 WorldUnit 的局部坐标位置施加冲量。参数 impulse 为 Vector3 类型的冲量向量，localPosition 为 Vector3 类型的局部坐标位置，函数无返回值。

参数类型说明
impulseVector3冲量向量
localPositionVector3物体局部空间中的冲量施加点坐标

返回值 void

示例代码

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

lua
-- @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) -> void

在 WorldUnit 的世界坐标位置施加冲量。参数 impulse 为 Vector3 类型的冲量向量，worldPosition 为 Vector3 类型的世界坐标位置，函数无返回值。

参数类型说明
impulseVector3冲量向量
worldPositionVector3世界空间中的冲量施加点坐标

返回值 void

示例代码

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

lua
-- @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 在指定世界坐标位置处的速度。参数 position 为 Vector3 类型的世界坐标，返回 Vector3 类型的速度。

参数类型说明
positionVector3要查询速度的世界空间坐标点

返回值 Vector3

示例代码

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

lua
-- @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) -> void

添加不碰撞单位对，将指定单位登记为当前 WorldUnit 的不碰撞对象。

参数类型说明
targetUnitSpaceUnit要互不碰撞的目标单位

返回值 void

示例代码

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

lua
-- @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) -> void

移除不碰撞单位对，将指定单位从当前 WorldUnit 的不碰撞登记中撤销。

参数类型说明
targetUnitSpaceUnit要恢复碰撞的目标单位

返回值 void

示例代码

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

lua
-- @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() -> void

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

返回值 void

示例代码

调用 WorldUnit:RemoveAllNoCollisionPairWithUnit 的示例。

lua
-- @runtime client
local worldUnit = game:CreateUnit("WorldUnit", {})
worldUnit:RemoveAllNoCollisionPairWithUnit()
print("调用完成", worldUnit)

GetNoCollisionPairUnitList ​

签名：GetNoCollisionPairUnitList() -> Array&lt;SpaceUnit&gt;

获取不碰撞单位列表，返回当前 WorldUnit 已登记的全部不碰撞单位。

返回值 Array<SpaceUnit>

示例代码

调用 WorldUnit:GetNoCollisionPairUnitList 的示例。

lua
-- @runtime client
local worldUnit = game:CreateUnit("WorldUnit", {})
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) -> void

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

参数类型说明
renderMeshIdString模型资源ID

返回值 void

示例代码

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

lua
-- @runtime client
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()