主题
HumanUnit
人形生物单位用于在场景中生成可受控、可施力的角色实体，既能设置位置、旋转、缩放与模型资源，也能围绕 Controller、Animator 组织移动与动画表现。它把物理与外观分离管理：一方面通过 BodyType、PhysicsActive...
概览
人形生物单位用于在场景中生成可受控、可施力的角色实体，既能设置位置、旋转、缩放与模型资源，也能围绕 Controller、Animator 组织移动与动画表现。它把物理与外观分离管理：一方面通过 BodyType、PhysicsActive、Mass、GravityEnabled、LinearVelocity、AngularVelocity 等属性参与物理模拟，另一方面通过 RenderMeshId、HumanSkinColor、UseCustomAppearance 等控制呈现。此外还提供碰撞组、忽略碰撞对以及网格材质的运行时调整能力，并对外抛出本地碰撞进出事件。
继承自
SpaceUnit；可通过World:CreateUnit("HumanUnit", ...)创建；返回单个单位
函数
SetNetworkOwner
签名：SetNetworkOwner(player: Player)
设置该 HumanUnit 的网络拥有者，把传入的玩家指定为该单位的网络拥有者。
注意： 该网络所有权能力属于服务端运行时，且当前 Editor Surface 不公开 Players 服务或其它稳定 Player 获取链；不要在 Editor 示例中编造 game/editor:GetService("Players")。
| 参数 | 类型 | 说明 |
|---|---|---|
player | Player | 玩家 |
GetNetworkOwner
签名：GetNetworkOwner() -> Player
获取当前 HumanUnit 的网络拥有者，返回值为 Player 类型。
注意： 该网络所有权能力属于服务端运行时。Editor Lua 只保留公开签名，不提供可运行示例。
返回值 Player
GetPosition
签名：GetPosition() -> Vector3
获取 HumanUnit 的物理位置，返回 Vector3。
返回值 Vector3
读取人形单位位置
lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Position = Vector3.New(0, 0, 0) })
local position = humanUnit:GetPosition()
print("位置:", position)SetPosition
签名：SetPosition(pos: Vector3)
设置 HumanUnit 的物理位置。
| 参数 | 类型 | 说明 |
|---|---|---|
pos | Vector3 | 坐标 |
移动人形单位
lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Position = Vector3.New(0, 0, 0) })
humanUnit:SetPosition(Vector3.New(5, 0, 0))GetRotation
签名：GetRotation() -> Quaternion
获取 HumanUnit 当前的物理旋转四元数。
返回值 Quaternion
读取人形单位旋转
lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Position = Vector3.New(0, 0, 0) })
local rotation = humanUnit:GetRotation()
print("旋转:", rotation)SetRotation
签名：SetRotation(rotation: Quaternion)
设置 HumanUnit 的物理旋转为指定的四元数。
| 参数 | 类型 | 说明 |
|---|---|---|
rotation | Quaternion | 旋转 |
设置人形单位旋转
lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Position = Vector3.New(0, 0, 0) })
local rotation = Quaternion.FromEulerAngles(0, math.rad(90), 0)
humanUnit:SetRotation(rotation)GetScale
签名：GetScale() -> Vector3
获取 HumanUnit 的缩放，返回 Vector3。
返回值 Vector3
读取人形单位缩放
lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Scale = Vector3.New(1, 1, 1) })
local scale = humanUnit:GetScale()
print("缩放:", scale)SetScale
签名：SetScale(scale: Vector3)
设置 HumanUnit 的缩放。
| 参数 | 类型 | 说明 |
|---|---|---|
scale | Vector3 | 缩放 |
设置人形单位缩放
lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Scale = Vector3.New(1, 1, 1) })
humanUnit:SetScale(Vector3.New(1.2, 1.2, 1.2))GetYaw
签名：GetYaw() -> Float
获取该 HumanUnit 的 Yaw 朝向数值。
返回值 Float
读取人形单位朝向角
lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Position = Vector3.New(0, 0, 0) })
local yaw = humanUnit:GetYaw()
print("Yaw:", yaw)GetRenderPosition
签名：GetRenderPosition() -> Vector3
获取 HumanUnit 的渲染位置，返回 Vector3。
返回值 Vector3
读取人形单位渲染位置
lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Position = Vector3.New(0, 0, 0) })
local renderPosition = humanUnit:GetRenderPosition()
print("渲染位置:", renderPosition)GetRenderRotation
签名：GetRenderRotation() -> Quaternion
获取 HumanUnit 的显示旋转，即渲染表现所使用的旋转四元数。
返回值 Quaternion
读取人形单位渲染旋转
lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Position = Vector3.New(0, 0, 0) })
local renderRotation = humanUnit:GetRenderRotation()
print("渲染旋转:", renderRotation)AddCollisionWithGroup
签名：AddCollisionWithGroup(groupName: String)
添加一个允许与当前 HumanUnit 发生碰撞的碰撞组。
| 参数 | 类型 | 说明 |
|---|---|---|
groupName | String | 碰撞组名 |
添加允许碰撞的碰撞组
lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Name = "Hero" })
humanUnit:AddCollisionWithGroup("Prop")RemoveCollisionWithGroup
签名：RemoveCollisionWithGroup(groupName: String)
从当前 HumanUnit 的允许碰撞列表中移除指定碰撞组。
| 参数 | 类型 | 说明 |
|---|---|---|
groupName | String | 碰撞组名 |
移除允许碰撞的碰撞组
lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Name = "Hero" })
humanUnit:AddCollisionWithGroup("Prop")
humanUnit:RemoveCollisionWithGroup("Prop")GetCollisionWithGroups
签名：GetCollisionWithGroups() -> Array
获取当前 HumanUnit 允许发生碰撞的碰撞组名称列表。
返回值 Array
读取已添加的碰撞组
lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Name = "Hero" })
humanUnit:AddCollisionWithGroup("Prop")
for _, groupName in ipairs(humanUnit:GetCollisionWithGroups()) do
print("碰撞组:", groupName)
endApplyForceToCenterOfMass
签名：ApplyForceToCenterOfMass(force: Vector3)
在 HumanUnit 的质心施加力。
| 参数 | 类型 | 说明 |
|---|---|---|
force | Vector3 | 施加的力 |
在质心施加向上的力
lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Position = Vector3.New(0, 0, 0) })
humanUnit:ApplyForceToCenterOfMass(Vector3.New(0, 500, 0))ApplyForceAtLocalPosition
签名：ApplyForceAtLocalPosition(force: Vector3, localPosition: Vector3)
在 HumanUnit 的局部坐标位置施加力。
| 参数 | 类型 | 说明 |
|---|---|---|
force | Vector3 | 施加的力 |
localPosition | Vector3 | 局部空间坐标系下的力量的施加点 |
在局部位置施加力
lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Position = Vector3.New(0, 0, 0) })
local force = Vector3.New(0, 300, 0)
local localPosition = Vector3.New(0, 1, 0)
humanUnit:ApplyForceAtLocalPosition(force, localPosition)ApplyForceAtWorldPosition
签名：ApplyForceAtWorldPosition(force: Vector3, worldPosition: Vector3)
在 HumanUnit 的世界坐标位置施加力。
| 参数 | 类型 | 说明 |
|---|---|---|
force | Vector3 | 施加的力 |
worldPosition | Vector3 | 世界空间坐标系下的力量的施加点 |
在世界位置施加力
lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Position = Vector3.New(0, 0, 0) })
local force = Vector3.New(0, 300, 0)
local worldPosition = humanUnit:GetPosition() + Vector3.New(0, 1, 0)
humanUnit:ApplyForceAtWorldPosition(force, worldPosition)AddNoCollisionPairWithUnit
签名：AddNoCollisionPairWithUnit(targetUnit: SpaceUnit)
为该 HumanUnit 添加一个不碰撞单位对，使该人形单位与指定单位之间不再产生碰撞。
| 参数 | 类型 | 说明 |
|---|---|---|
targetUnit | SpaceUnit | 目标单位 |
让 HumanUnit 与指定单位互不碰撞
lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Name = "Hero" })
local targetUnit = World:CreateUnit("WorldUnit", { Name = "IgnoredTarget" })
humanUnit:AddNoCollisionPairWithUnit(targetUnit)RemoveNoCollisionPairWithUnit
签名：RemoveNoCollisionPairWithUnit(targetUnit: SpaceUnit)
移除该 HumanUnit 与指定单位之间的不碰撞设置，取消此前添加的该不碰撞单位对。
| 参数 | 类型 | 说明 |
|---|---|---|
targetUnit | SpaceUnit | 目标单位 |
恢复 HumanUnit 与指定单位碰撞
lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Name = "Hero" })
local targetUnit = World:CreateUnit("WorldUnit", { Name = "IgnoredTarget" })
humanUnit:AddNoCollisionPairWithUnit(targetUnit)
humanUnit:RemoveNoCollisionPairWithUnit(targetUnit)RemoveAllNoCollisionPairWithUnit
签名：RemoveAllNoCollisionPairWithUnit()
移除 HumanUnit 的所有不碰撞单位对。
清空 HumanUnit 的不碰撞配对
lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Name = "Hero" })
humanUnit:RemoveAllNoCollisionPairWithUnit()GetNoCollisionPairUnitList
签名：GetNoCollisionPairUnitList() -> Array
获取该 HumanUnit 当前已设置的不碰撞单位列表，返回由 SpaceUnit 组成的数组。
返回值 Array
读取 HumanUnit 的不碰撞单位列表
lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Name = "Hero" })
local targetUnit = World:CreateUnit("WorldUnit", { Name = "IgnoredTarget" })
humanUnit:AddNoCollisionPairWithUnit(targetUnit)
for _, unit in ipairs(humanUnit:GetNoCollisionPairUnitList()) do
print("不碰撞单位:", unit.Name)
endAddMeshByAssetId
签名：AddMeshByAssetId(assetId: String)
为该 HumanUnit 添加人形蒙皮，参数为蒙皮资产 ID 字符串。
| 参数 | 类型 | 说明 |
|---|---|---|
assetId | String | 资源ID |
给人形单位添加蒙皮资源
lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Name = "Hero" })
humanUnit:AddMeshByAssetId("official://skin/10001")RemoveMeshByAssetId
签名：RemoveMeshByAssetId(assetId: String)
移除该 HumanUnit 上由 assetId 指定的人形蒙皮。
| 参数 | 类型 | 说明 |
|---|---|---|
assetId | String | 资源ID |
移除人形单位蒙皮资源
lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Name = "Hero" })
local assetId = "official://skin/10001"
humanUnit:AddMeshByAssetId(assetId)
humanUnit:RemoveMeshByAssetId(assetId)SetMeshColor
签名：SetMeshColor(assetId: String, colorKey: HumanMeshColor, color: Color, materialIndex: Int)
设置指定人形蒙皮的染色，需要给出蒙皮资产 ID、颜色通道、颜色值与材质索引。
| 参数 | 类型 | 说明 |
|---|---|---|
assetId | String | 网格资源ID |
colorKey | HumanMeshColor | 染色区域 |
color | Color | 颜色 |
materialIndex | Int | 材质索引 |
设置指定蒙皮染色区域
lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Name = "Hero" })
local assetId = "official://skin/10001"
humanUnit:AddMeshByAssetId(assetId)
humanUnit:SetMeshColor(assetId, Enums.HumanMeshColor.COLOR1, Color.New(255, 180, 120, 255), 0)SetMeshTexture
签名：SetMeshTexture(meshAssetId: String, textureAssetId: String, materialIndex: Int)
设置人形蒙皮的贴图，需要提供蒙皮资产 ID、贴图资产 ID 与材质索引。
| 参数 | 类型 | 说明 |
|---|---|---|
meshAssetId | String | 网格资源ID |
textureAssetId | String | 贴图资源ID |
materialIndex | Int | 材质索引 |
设置指定蒙皮的材质贴图
lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Name = "Hero" })
local meshAssetId = "official://skin/10001"
humanUnit:AddMeshByAssetId(meshAssetId)
humanUnit:SetMeshTexture(meshAssetId, "official://image/10001", 0)SetModelTexture
签名：SetModelTexture(assetId: String, materialIndex: Int)
替换人形自定义模型指定材质的贴图，仅对已配置自定义模型的 HumanUnit 生效。
| 参数 | 类型 | 说明 |
|---|---|---|
assetId | String | 贴图资源ID |
materialIndex | Int | 材质索引 |
替换已配置自定义人形的贴图
lua
-- @runtime client
local humanUnit = game:GetService('World'):FindFirstChild('CustomHuman', true)
if humanUnit == nil or not humanUnit:IsA('HumanUnit') then return end
local textureUri = humanUnit:GetAttribute('ModelTextureUri')
if type(textureUri) ~= 'string' or textureUri == '' then return end
humanUnit:SetModelTexture(textureUri, 0)SetModelColor
签名：SetModelColor(colorKey: HumanMeshColor, color: Color, materialIndex: Int)
设置自定义人形模型指定区域的颜色，仅对已配置自定义模型的 HumanUnit 生效。
| 参数 | 类型 | 说明 |
|---|---|---|
colorKey | HumanMeshColor | 染色区域 |
color | Color | 颜色 |
materialIndex | Int | 材质索引 |
设置自定义人形模型染色
lua
-- @runtime client
local humanUnit = game:GetService('World'):FindFirstChild('CustomHuman', true)
if humanUnit == nil or not humanUnit:IsA('HumanUnit') then return end
humanUnit:SetModelColor(Enums.HumanMeshColor.COLOR1, Color.New(255, 200, 160, 255), 0)属性
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
Position | Vector3 | [0.0, 0.0, 0.0] | HumanUnit 在世界空间中的位置，类型为 Vector3。 |
Rotation | Quaternion | [0.0, 0.0, 0.0, 1.0] | HumanUnit 当前的旋转姿态，以四元数形式表示。 |
Scale | Vector3 | [1.0, 1.0, 1.0] | HumanUnit 的缩放比例，类型为 Vector3。 |
Visible | Bool | true | HumanUnit 的可见性。 |
RenderMeshId | String | official://mesh/9000969 | 单位使用的骨骼网格资源路径，支持 official:// 协议引用官方资源。 |
Controller | HumanController | - | HumanUnit 的人形生物控制器属性，表示该人形单位所关联的 HumanController 对象，读取后可用于人形单位的相关控制逻辑。 |
EnableController | Bool | false | 标识 HumanUnit 是否创建 Controller（控制器）的布尔属性，默认值为 false。 |
EnableAnimator | Bool | true | 单位创建时是否自动挂载 Animator。 |
EnableAnimScript | Bool | true | 单位创建时是否自动挂载动画蓝图脚本。 |
BodyType | Int | Enums.BodyType.Dynamic | 刚体类型：Static(静态，不受力)、Kinematic(运动学，仅脚本控制移动)、Dynamic(动态，受物理模拟) |
PhysicsActive | Bool | true | 是否启用物理模拟，关闭后单位不受重力、碰撞等物理影响。 |
CollisionGroup | String | Character | 单位所属的碰撞预设组名称，决定默认的碰撞过滤规则。 |
CanCollide | Bool | true | 是否启用碰撞检测，关闭后该单位将穿过其他物理对象。 |
Mass | Float | 10 | 单位质量，影响碰撞反馈和受力效果，仅 Dynamic 类型有效。取值范围 [0.01, 2147483640]。 |
Massless | Bool | false | 是否将质量视为零，启用后碰撞不会产生反作用力。 |
CenterOfMass | Vector3 | [0, 0, 0] | 相对于模型原点的质心偏移，影响旋转和受力行为。取值范围 [-50.0, 50.0]。 |
RotationLocked | Bool | true | 是否锁定 HumanUnit 的旋转。 |
GravityEnabled | Bool | true | 是否受全局重力影响，关闭后单位将漂浮。 |
UseIndividualGravity | Bool | false | 是否覆盖全局重力，启用后将使用 IndividualGravityValue 指定的重力方向与大小。 |
IndividualGravityValue | Vector3 | [0, -9.8, 0] | 自定义重力加速度向量。 |
AngularVelocity | Vector3 | [0, 0, 0] | HumanUnit 的角速度，类型为 Vector3。 |
LinearVelocity | Vector3 | [0, 0, 0] | HumanUnit 的线速度，类型为 Vector3。 |
Animator | Animator | - | 获取该 HumanUnit 上的 Animator 实例，其查找方式为遍历子节点。 |
HumanSkinColor | Vector4 | [0.0, 1.0, 1.0, 1.0] | 人形肤色，类型为 Vector4，用四个分量描述角色的肤色取值。 |
UseCustomAppearance | Bool | false | 是否使用自定义外观，布尔类型开关。 |
CustomAppearanceId | String | "" | 人形单位的自定义外观 ID，类型为字符串，用于标识该单位所使用的自定义外观。 |
事件
OnCollisionEnter
签名：OnCollisionEnter(otherUnit: Unit)
当本单位与其他 Unit 开始碰撞时触发
| 参数 | 类型 | 说明 |
|---|---|---|
otherUnit | Unit | 碰撞到的单位 |
OnCollisionExit
签名：OnCollisionExit(otherUnit: Unit)
当本单位与其他 Unit 结束碰撞时触发
| 参数 | 类型 | 说明 |
|---|---|---|
otherUnit | Unit | 结束碰撞的单位 |