Skip to content

HumanUnit

概览

字段
KindUnit · 单位 Unit
Realmcommon

继承关系

  • Unit(4 属性 / 25 函数 / 6 事件)
    • SpaceUnit(3 属性 / 9 函数)
      • [HumanUnit](23 属性 / 27 函数 / 2 事件)

继承成员

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

HumanUnit 是场景中可创建的人形生物单位,用于构建玩家角色、NPC 等需要人形外观与物理表现的对象。它提供位置、旋转、缩放、可见性等基础变换属性,以及物理模拟(质量、重力、碰撞组、力的施加)、模型外观(渲染网格、模型颜色与纹理、附加网格)和控制器/动画(Controller、Animator)等完整能力。可通过 OnCollisionEnter 与 OnCollisionExit 事件感知本地碰撞。

适用场景

在创建玩家角色或任意人形 NPC 时,通常先通过 game:CreateUnit("HumanUnit", config) 或 World:CreateUnit("HumanUnit", config) 生成实例,再开启 EnableController、EnableAnimator 以启用控制器与动画器,实现角色姿态与行为控制。

使用要点

首先通过 game:CreateUnit("HumanUnit", config) 或 World:CreateUnit("HumanUnit", config) 获取 HumanUnit 实例,随后可直接读写 Position、Rotation、Scale、Visible 等属性。若需要物理表现,设置 PhysicsActive、Mass、GravityEnabled 等属性,并调用 ApplyForceToCenterOfMass、ApplyForceAtWorldPosition 等函数施加力。外观调整可使用 AddMeshByAssetId、SetModelColor、SetModelTexture;碰撞交互则通过 AddCollisionWithGroup 配置碰撞组,并连接 OnCollisionEnter、OnCollisionExit 事件。多端联机时还可借助 SetNetworkOwner 指定网络归属。

注意事项

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

代码示例

服务端创建人形单位并启用控制器

lua
-- @runtime server
-- 服务端脚本:创建可控制的人形单位
local World = game:GetService("World")

local humanUnit = World:CreateUnit("HumanUnit", {
    Name = "Hero",
    Position = Vector3.New(0, 0, 0),
    EnableController = true,
})

if humanUnit.Controller ~= nil then
    humanUnit.Controller.WalkSpeed = 16
    humanUnit.Controller.JumpPower = 8
    humanUnit.Controller:Jump()
end

属性 (23)

Name类型默认值说明
PositionVector3[0.0, 0.0, 0.0]HumanUnit 在世界空间中的位置,类型为 Vector3
RotationQuaternion[0.0, 0.0, 0.0, 1.0]HumanUnit 当前的旋转姿态,以四元数形式表示。
ScaleVector3[1.0, 1.0, 1.0]HumanUnit 的缩放比例,类型为 Vector3
VisibleBooltrueHumanUnit 的可见性。
RenderMeshIdStringofficial://mesh/9000969HumanUnit 的渲染模型资源标识符。
ControllerHumanController-HumanUnit 关联的 HumanController 实例,用于控制移动、跳跃等行为。
EnableControllerBoolfalse是否在创建 HumanUnit 时自动创建 HumanController
EnableAnimatorBooltrue是否在创建 HumanUnit 时自动添加 Animator 组件。
EnableAnimScriptBooltrue是否在创建 HumanUnit 时自动添加动画脚本。
BodyTypeIntEnums.BodyType.Dynamic刚体类型:Static(静态,不受力)、Kinematic(运动学,仅脚本控制移动)、Dynamic(动态,受物理模拟)
PhysicsActiveBooltrue是否启用 HumanUnit 的物理模拟。
CollisionGroupStringCharacterHumanUnit 所属的碰撞组名称。
CanCollideBooltrueHumanUnit 是否参与物理碰撞。
MassFloat10HumanUnit 的质量。
MasslessBoolfalseHumanUnit 是否视为无质量。
CenterOfMassVector3[0, 0, 0]HumanUnit 的质心相对于单位原点的局部偏移,类型为 Vector3
RotationLockedBooltrue是否锁定 HumanUnit 的旋转。
GravityEnabledBooltrue是否对 HumanUnit 应用重力。
UseIndividualGravityBoolfalse是否使用自定义重力值。
IndividualGravityValueVector3[0, -9.8, 0]HumanUnit 的自定义重力值,类型为 Vector3
AngularVelocityVector3[0, 0, 0]HumanUnit 的角速度,类型为 Vector3
LinearVelocityVector3[0, 0, 0]HumanUnit 的线速度,类型为 Vector3
AnimatorAnimator-HumanUnit 的 Animator 组件,用于控制动画播放。

关联类型

事件 (2)

OnCollisionEnter

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

HumanUnit 与被碰撞单位开始发生碰撞时触发。回调参数 otherUnit 为当前与该 HumanUnit 发生碰撞的单位实例。

回调参数类型说明
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 为与该 HumanUnit 结束碰撞的单位实例。

回调参数类型说明
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

设置该人形单位的网络拥有者,需要传入一个 Player 类型的参数。

参数类型说明
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 (网络拥有者;没有明确所有者时可能没有有效结果)

获取该人形单位的网络拥有者,返回值为 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 的物理位置。

参数类型说明
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 (旋转)

示例代码

读取人形单位旋转

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 的物理旋转为指定的四元数。

参数类型说明
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 的缩放。

参数类型说明
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 (显示旋转)

示例代码

读取人形单位渲染旋转

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 的质心施加力。

参数类型说明
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 的局部坐标位置施加力。

参数类型说明
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 的世界坐标位置施加力。

参数类型说明
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

添加 HumanUnit 与指定 SpaceUnit 的不碰撞对。

参数类型说明
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

移除 HumanUnit 与指定 SpaceUnit 的不碰撞对。

参数类型说明
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;

获取与 HumanUnit 不碰撞的单位列表,返回 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 上指定资源 ID 的人形蒙皮。

参数类型说明
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

设置 HumanUnit 上指定蒙皮资源的染色。

参数类型说明
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 本体的贴图。

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

返回值 void

示例代码

设置人形模型贴图

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

SetModelColor

签名:SetModelColor(colorKey: HumanMeshColor, color: Color, materialIndex: Int) -> void

设置 HumanUnit 本体的染色。

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

返回值 void

示例代码

设置人形模型染色

lua
-- @runtime client
local World = game:GetService("World")
local humanUnit = World:CreateUnit("HumanUnit", { Name = "Hero" })
humanUnit:SetModelColor(Enums.HumanMeshColor.COLOR1, Color.New(255, 200, 160, 255), 0)