工坊手册

主题

HumanController ​

概览 ​

字段值
KindUnit · 单位 Unit
Realmcommon

继承关系 ​

  • Unit（4 属性 / 25 函数 / 6 事件）
    • BaseController（12 属性 / 22 函数 / 11 事件）
      • [HumanController]（8 属性 / 2 函数 / 8 事件）

继承成员 ​

2 个来源 / 16 属性 / 47 函数 / 17 事件

HumanController 是人形角色的行为控制器，负责驱动物人形单位的移动速度查询、攀爬、坐下以及人形状态机等行为。它在通用控制器能力之上补充了 ClimbEnabled、ClimbMoveDirection、SeatPart、Sit、TargetPoint、EvaluateStateMachine、InertiaEnabled、NameBarOffset 等人形专属属性，并通过 GetMoveVelocity 与 GetRelativeVelocityAtFloor 暴露速度信息，同时提供 Climbing、Running、FallingDown、GettingUp、FreeFalling、Seated、OnClimbStart、OnClimbEnd 等本地状态事件。

适用场景 ​

当玩家角色确实是人形单位时，可用它查询当前移动速度、开关攀爬能力、设置攀爬方向与目标点，或监听攀爬、奔跑、下落、坐下等状态切换来驱动角色表现。例如在角色进入可攀爬区域时打开 ClimbEnabled 并监听 OnClimbStart 与 OnClimbEnd，在 Running 触发时按传入的速度值调整表现。

使用要点 ​

先从 HumanUnit 取得 Controller，例如确认角色 IsA("HumanUnit") 后读取 Controller 并判空。可读取只读 ClimbMoveDirection 观察当前攀爬方向，不能直接设置它；按公开可写属性 ClimbEnabled、InertiaEnabled、EvaluateStateMachine 调整相应开关，运动操作使用公开 Controller 方法。通过 GetMoveVelocity、GetRelativeVelocityAtFloor 查询速度，连接所需本地事件，并在不再需要时断开自有连接。

注意事项 ​

HumanController 只能从 HumanUnit.Controller 获取；Players.LocalPlayer.Character 也可能是 EggyUnit 等其它角色类型，调用 HumanController 专属成员前必须先用 IsA("HumanUnit") 判定。

代码示例 ​

从 HumanUnit.Controller 获取控制器 ​

lua
-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer

if localPlayer ~= nil and localPlayer.Character ~= nil then
    local humanUnit = localPlayer.Character
    if not humanUnit:IsA("HumanUnit") then return end
    local controller = humanUnit.Controller
    if controller ~= nil then
        local velocity = controller:GetMoveVelocity()
        print("移动速度:", velocity)
    end
end

属性 (8) ​

Name类型默认值说明
ClimbEnabledBoolfalseHumanController 的布尔属性，用于开启或关闭该控制器的攀爬能力，默认值为 false。
ClimbMoveDirectionVector3[0, 0, 0]Vector3 类型属性，用于表示该 HumanController 所属角色在攀爬状态下的移动方向。
SeatPartUnit-Unit 类型属性，表示与该 HumanController 所属角色乘坐状态关联的座椅单位对象。
SitBoolfalseSit 是 HumanController 的布尔属性，用于表示角色当前是否处于坐下状态。
TargetPointVector3[0, 0, 0]Vector3 类型属性，表示该 HumanController 所属角色的目标点位置。
EvaluateStateMachineBooltrueEvaluateStateMachine 是 HumanController 的布尔属性，标题为“启用状态机”，在 Meta 中标记为可编辑。
InertiaEnabledBooltrueInertiaEnabled 是 HumanController 的布尔属性，标题为“启用惯性”，在 Meta 中标记为可编辑。
NameBarOffsetFloat0.0NameBarOffset 是 HumanController 的 Float 类型属性，标题为“名称显示偏移”，在 Meta 中标记为可编辑。

关联类型 ​

事件 (8) ​

Climbing ​

签名：Climbing(speed: Float) 触发：local

Climbing 是 HumanController 上的本地事件，用于通知攀爬相关的状态变化，回调参数 speed 的类型为 Float。

回调参数类型说明
speedFloat当前攀爬速度

示例代码

监听角色攀爬速度

lua
-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
local humanUnit = localPlayer ~= nil and localPlayer.Character or nil
if humanUnit == nil or not humanUnit:IsA("HumanUnit") then return end
local controller = humanUnit ~= nil and humanUnit.Controller or nil
if controller ~= nil then
    controller.Climbing:Once(function(speed)
        print("攀爬速度:", speed)
    end)
end

Running ​

签名：Running(speed: Float) 触发：local

Running 是 HumanController 上的本地事件，回调参数 speed 的类型为 Float，用于通知奔跑相关的速度信息。

回调参数类型说明
speedFloat当前水平移动速度

示例代码

监听角色奔跑速度

lua
-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
local humanUnit = localPlayer ~= nil and localPlayer.Character or nil
if humanUnit == nil or not humanUnit:IsA("HumanUnit") then return end
local controller = humanUnit ~= nil and humanUnit.Controller or nil
if controller ~= nil then
    controller.Running:Once(function(speed)
        print("水平移动速度:", speed)
    end)
end

FallingDown ​

签名：FallingDown(active: Bool) 触发：local

FallingDown 是 HumanController 上的本地事件，回调参数 active 为 Bool 类型，用于表示摔倒相关状态。

回调参数类型说明
activeBooltrue=进入绊倒，false=离开绊倒

示例代码

监听角色绊倒状态

lua
-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
local humanUnit = localPlayer ~= nil and localPlayer.Character or nil
if humanUnit == nil or not humanUnit:IsA("HumanUnit") then return end
local controller = humanUnit ~= nil and humanUnit.Controller or nil
if controller ~= nil then
    controller.FallingDown:Once(function(active)
        print("绊倒状态:", active)
    end)
end

GettingUp ​

签名：GettingUp(active: Bool) 触发：local

GettingUp 是 HumanController 上的本地事件，回调参数 active 为 Bool 类型，用于表示起身相关状态。

回调参数类型说明
activeBooltrue=开始起身，false=起身完成

示例代码

监听角色起身状态

lua
-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
local humanUnit = localPlayer ~= nil and localPlayer.Character or nil
if humanUnit == nil or not humanUnit:IsA("HumanUnit") then return end
local controller = humanUnit ~= nil and humanUnit.Controller or nil
if controller ~= nil then
    controller.GettingUp:Once(function(active)
        print("起身状态:", active)
    end)
end

FreeFalling ​

签名：FreeFalling(active: Bool) 触发：local

FreeFalling 是 HumanController 上的本地事件，回调参数 active 为 Bool 类型，用于表示自由下落相关状态。

回调参数类型说明
activeBooltrue=开始下落，false=落地

示例代码

监听角色自由下落状态

lua
-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
local humanUnit = localPlayer ~= nil and localPlayer.Character or nil
if humanUnit == nil or not humanUnit:IsA("HumanUnit") then return end
local controller = humanUnit ~= nil and humanUnit.Controller or nil
if controller ~= nil then
    controller.FreeFalling:Once(function(active)
        print("自由下落:", active)
    end)
end

Seated ​

签名：Seated(active: Bool, seat: Unit) 触发：local

HumanController 的本地事件，在角色乘坐状态相关情况发生时触发，回调提供 active（Bool）与 seat（Unit）两个参数，分别表示是否处于坐下状态以及关联的座椅单位。

回调参数类型说明
activeBooltrue=坐下，false=起身
seatUnit座位 Unit

示例代码

监听角色坐下状态

lua
-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
local humanUnit = localPlayer ~= nil and localPlayer.Character or nil
if humanUnit == nil or not humanUnit:IsA("HumanUnit") then return end
local controller = humanUnit ~= nil and humanUnit.Controller or nil
if controller ~= nil then
    controller.Seated:Once(function(active, seat)
        print("坐下状态:", active, "座位:", seat)
    end)
end

OnClimbStart ​

签名：OnClimbStart() 触发：local

HumanController 的本地事件，在角色开始进入攀爬状态时触发，用于通知外部逻辑攀爬行为已经开始。

示例代码

监听 OnClimbStart

lua
-- @runtime client
local function demo(humanController)
    if humanController ~= nil then
        humanController.OnClimbStart:Once(function()
            print("OnClimbStart event")
        end)
    end
end

OnClimbEnd ​

签名：OnClimbEnd() 触发：local

HumanController 的本地事件，在角色结束攀爬状态时触发，用于通知外部逻辑一次攀爬行为已经结束。

示例代码

监听 OnClimbEnd

lua
-- @runtime client
local function demo(humanController)
    if humanController ~= nil then
        humanController.OnClimbEnd:Once(function()
            print("OnClimbEnd event")
        end)
    end
end

函数 (2) ​

GetMoveVelocity ​

签名：GetMoveVelocity() -> Vector3 (当前移动速度向量)

HumanController 的函数，无参数调用，返回一个 Vector3，表示该控制器所属角色当前的移动速度向量。

⚙ 返回角色当前的移动速度向量（来自 Controller 输入），与 BasePart.AssemblyLinearVelocity（物理装配体线速度）含义不同：前者反映操控意图，后者反映实际物理运动。

返回值 Vector3 (当前移动速度向量)

示例代码

从 HumanUnit.Controller 获取移动速度

lua
-- @runtime client
-- HumanController 通过 HumanUnit.Controller 属性获取
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer and localPlayer.Character then
    local humanUnit = localPlayer.Character
    if not humanUnit:IsA("HumanUnit") then return end
    local controller = humanUnit.Controller
    if controller ~= nil then
        local velocity = controller:GetMoveVelocity()
        print(string.format('移动速度: %s', tostring(velocity)))
    end
end

GetRelativeVelocityAtFloor ​

签名：GetRelativeVelocityAtFloor() -> Vector3 (相对于站立表面的速度向量（世界空间方向）)

HumanController 的函数，无参数调用，返回一个 Vector3，表示角色相对于所站立表面的速度向量，方向为世界空间方向。

返回值 Vector3 (相对于站立表面的速度向量（世界空间方向）)

示例代码

从 HumanUnit.Controller 获取相对地面速度

lua
-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
local humanUnit = localPlayer ~= nil and localPlayer.Character or nil
if humanUnit == nil or not humanUnit:IsA("HumanUnit") then return end
local controller = humanUnit ~= nil and humanUnit.Controller or nil
if controller ~= nil then
    local velocity = controller:GetRelativeVelocityAtFloor()
    print("相对地面速度:", velocity)
end