工坊手册

主题

HumanUnit ​

概览 ​

字段值
KindUnit · 单位 Unit
Realmcommon

继承关系 ​

  • Unit（4 属性 / 25 函数 / 6 事件）
    • SpaceUnit（2 属性 / 9 函数）
      • [HumanUnit]（26 属性 / 27 函数 / 2 事件）

继承成员 ​

2 个来源 / 6 属性 / 34 函数 / 6 事件

人形生物单位是场景中承载人形外观与物理表现的单位实体，既能设置位置、旋转、缩放与渲染模型，也能通过人形生物控制器驱动移动、跳跃等行为。它同时提供质量、重力、线速度、角速度、碰撞组等物理参数，以及肤色、自定义外观、按资源挂接网格并着色的外观定制能力。此外还会在本地触发碰撞进入与碰撞离开事件，便于处理接触到其他单位的反馈。

适用场景 ​

常用于需要放置可移动角色的场景：为实例指定 RenderMeshId 与 Position 后配合控制器让人形单位行走奔跑，或用 AddMeshByAssetId 给角色挂接武器、饰品等额外网格。也适合在需要按碰撞组过滤接触、或在本地监听碰撞进入与离开时使用。

使用要点 ​

先用 game:CreateUnit("HumanUnit", config) 或 World:CreateUnit("HumanUnit", config) 创建实例，随后可通过 GetPosition、SetPosition、GetRotation、SetRotation、GetScale 等接口读写基础变换；需要物理效果时调用 ApplyForceToCenterOfMass 或 ApplyForceAtWorldPosition 施加力，外观层面可用 AddMeshByAssetId、SetMeshColor、SetModelTexture 替换模型与材质。碰撞关系可通过 AddCollisionWithGroup、AddNoCollisionPairWithUnit 管理，并监听 OnCollisionEnter、OnCollisionExit 事件响应接触。

注意事项 ​

引擎使用 Y 轴向上的坐标系（重力默认 [0, -9.8, 0]）。施加向上的力应使用 Vector3.New(0,正值,0) 而非 Vector3.New(0,0,正值)。

代码示例 ​

读取已配置人形单位的控制器 ​

lua
-- @runtime client
-- 先在编辑器中配置名为 Hero 的 HumanUnit 及其控制器
local World = game:GetService("World")

local humanUnit = World:FindFirstChild("Hero", true)
if humanUnit == nil or not humanUnit:IsA("HumanUnit") then return end

if humanUnit.Controller ~= nil then
    print("人形控制器:", humanUnit.Controller)
end

属性 (26) ​

Name类型默认值说明
PositionVector3[0.0, 0.0, 0.0]HumanUnit 的世界位置属性，类型为 Vector3，默认值为 (0, 0, 0)，可在属性面板中编辑。
RotationQuaternion[0.0, 0.0, 0.0, 1.0]HumanUnit 的旋转属性，类型为 Quaternion，默认值为 (0, 0, 0, 1)，可在属性面板中编辑。
ScaleVector3[1.0, 1.0, 1.0]HumanUnit 的缩放属性，类型为 Vector3，默认值为 (1, 1, 1)，可在属性面板中编辑。
VisibleBooltrueHumanUnit 的可见性。
RenderMeshIdStringofficial://mesh/9000969HumanUnit 的渲染模型资源标识符。
ControllerHumanController-HumanUnit 的控制器属性，类型为 HumanController，表示该人形单位所关联的人形控制器实例。
EnableControllerBoolfalse标识 HumanUnit 是否创建 Controller（控制器）的布尔属性，默认值为 false。
EnableAnimatorBooltrue标识 HumanUnit 是否默认添加 Animator 的布尔属性，默认值为 true。
EnableAnimScriptBooltrue是否在创建 HumanUnit 时自动添加动画脚本。
BodyTypeIntEnums.BodyType.Dynamic刚体类型：Static(静态，不受力)、Kinematic(运动学，仅脚本控制移动)、Dynamic(动态，受物理模拟)
PhysicsActiveBooltrue是否启用 HumanUnit 的物理模拟。
CollisionGroupStringCharacterHumanUnit 所属的碰撞组名称。
CanCollideBooltrueHumanUnit 是否参与物理碰撞。
MassFloat10HumanUnit 的质量。
MasslessBoolfalseHumanUnit 是否视为无质量。
CenterOfMassVector3[0, 0, 0]HumanUnit 的质心属性，类型为 Vector3，默认值为 (0, 0, 0)，可在属性面板中编辑。
RotationLockedBooltrue是否锁定 HumanUnit 的旋转。
GravityEnabledBooltrue是否对 HumanUnit 应用重力。
UseIndividualGravityBoolfalse是否使用自定义重力值。
IndividualGravityValueVector3[0, -9.8, 0]HumanUnit 的自定义重力值属性，类型为 Vector3，默认值为 (0, -9.8, 0)，可在属性面板中编辑。
AngularVelocityVector3[0, 0, 0]HumanUnit 的角速度属性，类型为 Vector3，默认值为 (0, 0, 0)。
LinearVelocityVector3[0, 0, 0]HumanUnit 的线速度属性，类型为 Vector3，默认值为 (0, 0, 0)。
AnimatorAnimator-获取该 HumanUnit 上的 Animator 实例，其查找方式为遍历子节点。
HumanSkinColorVector4[0.0, 1.0, 1.0, 1.0]HumanUnit 的人形肤色属性，类型为 Vector4，默认值为 (0, 1, 1, 1)，可在属性面板中编辑。
UseCustomAppearanceBoolfalse是否使用自定义外观，布尔类型开关。
CustomAppearanceIdString""人形单位的自定义外观 ID，类型为字符串，用于标识该单位所使用的自定义外观。

关联类型 ​

事件 (2) ​

OnCollisionEnter ​

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

HumanUnit 的本地碰撞进入事件，当该单位与其它单位发生碰撞时触发，回调参数 otherUnit 为对方单位，类型为 Unit。

回调参数类型说明
otherUnitUnit碰撞到的单位

示例代码

监听人形单位开始碰撞

lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Name = "Hero", CollisionGroup = "Player" })
humanUnit.OnCollisionEnter:Once(function(otherUnit)
    print("开始碰撞:", otherUnit.Name)
end)

OnCollisionExit ​

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

HumanUnit 的本地碰撞离开事件，当该单位与其它单位结束碰撞时触发，回调参数 otherUnit 为对方单位，类型为 Unit。

回调参数类型说明
otherUnitUnit结束碰撞的单位

示例代码

监听人形单位结束碰撞

lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Name = "Hero", CollisionGroup = "Player" })
humanUnit.OnCollisionExit:Once(function(otherUnit)
    print("结束碰撞:", otherUnit.Name)
end)

函数 (27) ​

SetNetworkOwner ​

签名：SetNetworkOwner(player: Player) -> void

将该 HumanUnit 的网络拥有者设置为指定的玩家。

参数类型说明
playerPlayer玩家

返回值 void

示例代码

设置人形单位网络拥有者

lua
-- @runtime server
local Players = game:GetService("Players")
local World = game:GetService("World")

local player = Players:GetPlayers()[1]
local humanUnit = World:CreateUnit("HumanUnit", { Position = Vector3.New(0, 0, 0) })
if player ~= nil and humanUnit ~= nil then
    humanUnit:SetNetworkOwner(player)
end

GetNetworkOwner ​

签名：GetNetworkOwner() -> Player (网络拥有者；没有明确所有者时可能没有有效结果)

获取该 HumanUnit 当前所属的网络拥有者，返回值为 Player 对象。

返回值 Player (网络拥有者；没有明确所有者时可能没有有效结果)

示例代码

读取人形单位网络拥有者

lua
-- @runtime server
local World = game:GetService("World")

local humanUnit = World:CreateUnit("HumanUnit", { Position = Vector3.New(0, 0, 0) })
local owner = humanUnit:GetNetworkOwner()
if owner ~= nil then
    print("网络拥有者:", owner:GetName())
end

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

设置该 HumanUnit 的位置，参数 pos 为 Vector3，无返回值。

参数类型说明
posVector3坐标

返回值 void

示例代码

移动人形单位

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。

返回值 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) -> void

设置该 HumanUnit 的旋转，参数 rotation 为 Quaternion，无返回值。

参数类型说明
rotationQuaternion旋转

返回值 void

示例代码

设置人形单位旋转

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

设置该 HumanUnit 的缩放，参数 scale 为 Vector3，无返回值。

参数类型说明
scaleVector3缩放

返回值 void

示例代码

设置人形单位缩放

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 (Yaw朝向)

获取该 HumanUnit 的 Yaw 朝向数值。

返回值 Float (Yaw朝向)

示例代码

读取人形单位朝向角

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。

返回值 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) -> void

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

参数类型说明
groupNameString碰撞组名

返回值 void

示例代码

添加允许碰撞的碰撞组

lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Name = "Hero" })
humanUnit:AddCollisionWithGroup("Prop")

RemoveCollisionWithGroup ​

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

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

参数类型说明
groupNameString碰撞组名

返回值 void

示例代码

移除允许碰撞的碰撞组

lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Name = "Hero" })
humanUnit:AddCollisionWithGroup("Prop")
humanUnit:RemoveCollisionWithGroup("Prop")

GetCollisionWithGroups ​

签名：GetCollisionWithGroups() -> Array<String>

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

返回值 Array<String>

示例代码

读取已添加的碰撞组

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)
end

ApplyForceToCenterOfMass ​

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

在该 HumanUnit 的质心施加一个力，参数 force 为力的向量（Vector3），无返回值。

参数类型说明
forceVector3施加的力

返回值 void

示例代码

在质心施加向上的力

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

在该 HumanUnit 的局部坐标位置施加一个力，参数 force 为力的向量（Vector3），localPosition 为局部坐标系下的作用点（Vector3），无返回值。

参数类型说明
forceVector3施加的力
localPositionVector3局部空间坐标系下的力量的施加点

返回值 void

示例代码

在局部位置施加力

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

在该 HumanUnit 的世界坐标位置施加一个力，参数 force 为力的向量（Vector3），worldPosition 为世界坐标系下的作用点（Vector3），无返回值。

参数类型说明
forceVector3施加的力
worldPositionVector3世界空间坐标系下的力量的施加点

返回值 void

示例代码

在世界位置施加力

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

为当前人形单位添加一个不碰撞单位对，使该单位与指定单位之间不产生碰撞。

参数类型说明
targetUnitSpaceUnit目标单位

返回值 void

示例代码

让 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) -> void

移除当前人形单位与指定单位之间的不碰撞单位对，取消二者之间原有的忽略碰撞设置。

参数类型说明
targetUnitSpaceUnit目标单位

返回值 void

示例代码

恢复 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() -> void

移除 HumanUnit 的所有不碰撞单位对。

返回值 void

示例代码

清空 HumanUnit 的不碰撞配对

lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Name = "Hero" })
humanUnit:RemoveAllNoCollisionPairWithUnit()

GetNoCollisionPairUnitList ​

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

获取当前人形单位已设置的不碰撞单位列表，返回元素类型为 SpaceUnit 的数组。

返回值 Array<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)
for _, unit in ipairs(humanUnit:GetNoCollisionPairUnitList()) do
    print("不碰撞单位:", unit.Name)
end

AddMeshByAssetId ​

签名：AddMeshByAssetId(assetId: String) -> void

为该 HumanUnit 添加人形蒙皮，参数为蒙皮资产 ID 字符串。

参数类型说明
assetIdString蒙皮资源路径

返回值 void

示例代码

给人形单位添加蒙皮资源

lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Name = "Hero" })
humanUnit:AddMeshByAssetId("official://skin/10001")

RemoveMeshByAssetId ​

签名：RemoveMeshByAssetId(assetId: String) -> void

移除该 HumanUnit 上由 assetId 指定的人形蒙皮。

参数类型说明
assetIdString要移除的蒙皮资源路径

返回值 void

示例代码

移除人形单位蒙皮资源

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

设置指定人形蒙皮的染色，需要给出蒙皮资产 ID、颜色通道、颜色值与材质索引。

参数类型说明
assetIdString蒙皮网格资源路径，需与AddMeshByAssetId传入的一致
colorKeyHumanMeshColor要设置的染色区域类型
colorColor要设置的目标颜色
materialIndexInt目标材质索引

返回值 void

示例代码

设置指定蒙皮染色区域

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

设置人形蒙皮的贴图，需要提供蒙皮资产 ID、贴图资产 ID 与材质索引。

参数类型说明
meshAssetIdString蒙皮网格资源路径，需与AddMeshByAssetId传入的一致
textureAssetIdString要应用的贴图资源路径
materialIndexInt目标材质索引

返回值 void

示例代码

设置指定蒙皮的材质贴图

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

替换人形自定义模型指定材质的贴图，仅对已配置自定义模型的 HumanUnit 生效。

⚙ 先在地图中配置名为 CustomHuman 的自定义人形模型，并为其 ModelTextureUri 自定义属性填写项目有效贴图 URI；默认人形模型不适用。

参数类型说明
assetIdString贴图资源路径
materialIndexInt目标材质索引

返回值 void

示例代码

替换已配置自定义人形的贴图

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

设置自定义人形模型指定区域的颜色，仅对已配置自定义模型的 HumanUnit 生效。

⚙ 先在地图中配置名为 CustomHuman、带对应染色区域的自定义人形模型；默认模型和没有染色区域的资源不保证出现变化。

参数类型说明
colorKeyHumanMeshColor要设置的染色区域类型
colorColor要设置的目标颜色
materialIndexInt目标材质索引

返回值 void

示例代码

设置自定义人形模型染色

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)