BaseController

概览

字段	值
Kind	`Unit` · 单位 Unit
Realm	`common`

继承关系

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

继承成员

1 个来源 / 4 属性 / 25 函数 / 6 事件

来自 Unit（4 属性 / 25 函数 / 6 事件）
- 属性：AssetId、Name、Desc、Parent
- 函数：ClearAllChildren、GetChildren、GetDescendants、IsAncestorOf、IsDescendantOf、FindFirstAncestor、FindFirstAncestorWhichIsA、FindFirstAncestorOfClass、FindFirstChild、FindFirstChildWhichIsA、FindFirstChildOfClass、HasChildren、GetChildCount、GetChildAtIndex、SetAttribute、GetAttribute、GetAllProps、Clone、IsA、Destroy、GetPropertyChangedSignal、GetAttributeChangedSignal、FindFromPath、GetFullPath、GetDebugId
- 事件：ChildAdded、ChildRemoved、DescendantAdded、DescendantRemoving、AncestryChanged、Destroying

BaseController 是角色控制器的基类，负责生命值、移动、跳跃和状态切换等通用行为；实例通过 HumanUnit、EggyUnit 等公开角色类型的 Controller 属性获取，基础 Unit 不声明 Controller。

适用场景

需要读取或切换角色状态、控制移动和跳跃、处理生命值，或监听落地、死亡、碰撞等角色事件时使用。

使用要点

客户端通常通过 Players.LocalPlayer.Character.Controller 获取当前角色控制器；获取角色与 Controller 后先判空，再调用 Move、Jump、GetState 等接口或监听状态事件。涉及伤害、复活等会影响游戏状态的操作时，应由业务的权威端决定是否执行。

注意事项

Controller 依附于具体角色单位，常见路径是 Players.LocalPlayer.Character.Controller；不要泛化为所有 Unit 都有 Controller 属性。当前公开 Meta 中 HumanUnit、EggyUnit 等角色单位暴露 Controller，基础 Unit 不暴露该属性。

代码示例

读取当前玩家角色的控制器状态

lua

-- @runtime client
local Players = game:GetService('Players')
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer and localPlayer.Character
local controller = character and character.Controller
if controller == nil then
    return
end

print('当前角色状态:', controller:GetState())

属性 (12)

Name	类型	默认值	说明
`Health`	`Float`	`100.0`	浮点属性，表示控制器所属单位当前的生命值。
`MaxHealth`	`Float`	`100.0`	浮点属性，表示控制器所属单位的最大生命值。
`MaxMultiJumpCount`	`Int`	`1`	整数属性，表示多段跳次数。
`MultiJumpCooldown`	`Float`	`0.35`	浮点属性，表示多段跳冷却时间。
`WalkSpeed`	`Float`	`7.0`	浮点属性，表示控制器所属单位的移动速度。
`JumpPower`	`Float`	`23.0`	浮点属性，表示跳跃时的垂直速度。
`GravityEnabled`	`Bool`	`true`	布尔属性，用于控制该控制器所属单位是否受重力作用。
`HPBarShowMode`	`Int`	`Enums.HpBarShowMode.None`	血条显示模式：None 不显示，Persistent 常驻显示，NotFull 在血量不满时显示。
`DisplayDistanceType`	`Int`	`Enums.DisplayDistanceType.Viewer`	显示距离类型：None 隐藏，Viewer 按观察者距离显示，Subject 按被观察者距离显示。
`NameDisplayDistance`	`Float`	`20.0`	浮点属性，表示名字显示距离。
`HealthDisplayDistance`	`Float`	`20.0`	浮点属性，表示血条显示距离。
`AutoRotate`	`Bool`	`true`	布尔属性，表示是否自动朝向移动方向。

关联类型

Unit

事件 (11)

StateChanged

签名：StateChanged(old: ControllerStateType, new: ControllerStateType) 触发：local

本地事件，在角色状态发生变化时触发，回调参数为变化前后的状态 old 与 new，类型均为 ControllerStateType。

回调参数	类型	说明
`old`	ControllerStateType	旧状态
`new`	ControllerStateType	新状态

示例代码

监听角色状态切换

lua

-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then return end

-- StateChanged 回调提供切换前后的 ControllerStateType 状态值
baseController.StateChanged:Once(function(old, new)
    print("状态由", old, "切换为", new)
end)
print("已注册状态变化监听")

ExtraStatesChanged

签名：ExtraStatesChanged(old: String[], new: String[]) 触发：local

本地事件，在附加状态列表发生变化时触发，回调参数为变化前后的状态名数组 old 与 new，类型均为 String[]。

回调参数	类型	说明
`old`	`String[]`	旧附加状态列表
`new`	`String[]`	新附加状态列表

示例代码

监听附加状态列表变化

lua

-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then return end

-- ExtraStatesChanged 回调携带变化前后的附加状态名列表
baseController.ExtraStatesChanged:Once(function(old, new)
    -- 直接消费回调参数，说明哪一组状态发生了变化
    print("附加状态变化，旧列表:", old, "新列表:", new)
end)
print("已注册附加状态变化监听")

OnLanded

签名：OnLanded() 触发：local

本地事件，在单位落地时触发，不带回调参数，仅客户端生效。

示例代码

监听角色落地

lua

-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then return end

-- OnLanded 为本地事件，角色从空中落地时触发
baseController.OnLanded:Once(function()
    print("角色落地了")
end)
print("已注册落地监听")

OnStartFalling

签名：OnStartFalling() 触发：local

本地事件，在单位开始下落时触发，不带回调参数，仅客户端生效。

示例代码

监听角色开始下落

lua

-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then return end

-- OnStartFalling 为本地事件，角色开始下落时触发
baseController.OnStartFalling:Once(function()
    print("角色开始下落")
end)
print("已注册下落监听")

Died

签名：Died() 触发：local

本地事件，在控制器所属单位死亡时触发，不带回调参数。

示例代码

监听角色死亡事件

lua

-- @runtime client
-- 通过 Players 服务获取本地角色身上的 BaseController
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then return end

-- Died 为本地事件，角色死亡时触发一次
baseController.Died:Once(function()
    -- 回调无参数，直接输出提示确认触发
    print("角色已死亡")
end)
print("已注册死亡监听")

HealthChanged

签名：HealthChanged(health: Float) 触发：local

本地事件，在生命值变化时触发，回调参数为变化后的生命值 health，类型为 Float。

回调参数	类型	说明
`health`	`Float`	当前生命值

示例代码

监听生命值变化

lua

-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then return end

-- HealthChanged 在生命值发生变化时触发，参数为最新生命值
baseController.HealthChanged:Once(function(health)
    print("当前生命值:", health)
end)
print("已注册生命值监听")

MoveToFinished

签名：MoveToFinished(isReached: Bool) 触发：local

本地事件，在 MoveTo 移动结束时触发，回调参数 isReached 为 Bool，表示是否已到达目标。

回调参数	类型	说明
`isReached`	`Bool`	是否到达目的地

示例代码

监听 MoveTo 移动结束

lua

-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then return end

-- MoveToFinished 在 MoveTo 流程结束时触发，isReached 表示是否抵达目标
baseController.MoveToFinished:Once(function(isReached)
    print("移动结束，是否到达目标:", isReached)
end)
print("已注册移动结束监听")

OnReborn

签名：OnReborn(unit: SpaceUnit) 触发：local

BaseController 的本地事件，在控制器所控制的单位复活时触发，回调参数 unit 为本次复活的单位（SpaceUnit）。

回调参数	类型	说明
`unit`	SpaceUnit	触发的生物

示例代码

监听角色复活事件

lua

-- @runtime client
-- 获取本地玩家角色上的控制器
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then
    return
end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then
    return
end

-- 监听复活事件：回调参数 unit 为复活后的空间单位
baseController.OnReborn:Once(function(unit)
    print("角色复活完成，复活单位:", unit)
end)

-- 主动请求复活，触发上面的监听
baseController:Reborn()

OnJump

签名：OnJump(unit: SpaceUnit) 触发：local

BaseController 的本地事件，在控制器所控制的单位起跳时触发，回调参数 unit 为触发本次起跳的单位（SpaceUnit）。

回调参数	类型	说明
`unit`	SpaceUnit	触发的生物

示例代码

监听角色起跳事件

lua

-- @runtime client
-- 获取本地玩家角色上的控制器（BaseController 挂在角色 Unit 上）
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then
    return
end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then
    return
end

-- 监听起跳事件：回调参数 unit 为触发本次跳跃的空间单位
baseController.OnJump:Once(function(unit)
    print("角色起跳，触发单位:", unit)
end)

-- 主动控制角色跳跃，以便触发上面的监听
baseController:Jump()

OnCollisionEnter

签名：OnCollisionEnter(other: Unit, info: Table) 触发：local

控制器所属单位在与其他单位发生碰撞进入时触发的本地事件，回调会收到碰撞对方单位以及一份碰撞信息表。

回调参数	类型	说明
`other`	Unit	碰撞的对方对象
`info`	`Table`	碰撞信息，包含point和normal

示例代码

单次监听碰撞进入事件

lua

-- @runtime client
-- 获取本地玩家角色上的控制器实例（BaseController 是挂在角色单位上的控制器组件）
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer and localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then return end

-- 单次监听碰撞进入事件，回调会收到碰撞对象与碰撞信息表
baseController.OnCollisionEnter:Once(function(other, info)
    -- other：碰撞到的单位；info：本次碰撞的信息表
    print("发生碰撞进入，对方单位:", other, "碰撞信息:", info)
end)

OnCollisionExit

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

控制器所属单位结束与某个单位的碰撞时触发的本地事件，回调会收到碰撞对方单位。

回调参数	类型	说明
`other`	Unit	碰撞的对方对象

示例代码

单次监听碰撞退出事件

lua

-- @runtime client
-- 获取本地玩家角色上的控制器实例
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer and localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then return end

-- 单次监听碰撞结束事件，回调只收到结束碰撞的对象
baseController.OnCollisionExit:Once(function(other)
    -- other：结束碰撞的单位
    print("碰撞结束，对方单位:", other)
end)

函数 (22)

GetState

签名：GetState() -> ControllerStateType (当前状态类型)

获取当前角色状态，返回值为 ControllerStateType。

返回值 ControllerStateType (当前状态类型)

示例代码

读取角色当前状态

lua

-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then return end

-- GetState 返回当前角色的 ControllerStateType 状态
local state = baseController:GetState()
print("当前角色状态:", state)
-- 与死亡状态比较，用于判断角色是否已死亡
if state == Enums.ControllerStateType.Dead then
    print("角色处于死亡状态")
end

ChangeState

签名：ChangeState(state: ControllerStateType, force?: Bool) -> void

把控制器的角色状态切换为指定状态，并可通过可选参数 force 强制切换。目标状态使用 ControllerStateType 枚举描述。

参数	类型	说明
`state`	ControllerStateType	目标状态
`force?`	`Bool`	是否强制切换状态

返回值 void

示例代码

强制切换角色状态并验证结果

lua

-- @runtime client
-- 通过本地玩家角色获取 BaseController（控制器挂载在角色单位上）
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer.Character
if character == nil then return end
local baseController = character.Controller
if baseController == nil then return end

-- 记录切换前状态，便于对比 ChangeState 的效果
print("切换前状态:", baseController:GetState())

-- 监听状态变化事件，确认切换动作被真实执行
baseController.StateChanged:Once(function(oldState, newState)
    print("状态变化:", oldState, "->", newState)
end)

-- 强制切换到跳跃状态（第二个参数 force 为 true，表示跳过常规条件限制直接切换）
baseController:ChangeState(Enums.ControllerStateType.Jumping, true)

-- 读取当前状态，验证切换结果
print("切换后状态:", baseController:GetState())

SetStateEnabled

签名：SetStateEnabled(state: ControllerStateType, enabled: Bool) -> void

SetStateEnabled 用于对控制器上的某一个状态进行开关设置：第一个参数从 Enums.ControllerStateType 中选择目标状态，第二个参数是布尔开关，传 true 表示允许控制器进入该状态，传 false 表示禁止。函数没有返回值，每次调用只作用于被指定的那一个状态，控制器其余状态的既有设置保持不变。它通常用来在玩法脚本中临时封印某类行为（例如禁止跳跃、禁止翻滚），之后再把同一个状态重新打开。

参数	类型	说明
`state`	ControllerStateType	指定状态
`enabled`	`Bool`	是否启用

返回值 void

示例代码

启用或禁用指定状态

lua

-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then return end

-- 禁用 Jumping 状态，阻止角色跳跃
baseController:SetStateEnabled(Enums.ControllerStateType.Jumping, false)
local enabled = baseController:GetStateEnabled(Enums.ControllerStateType.Jumping)
print("Jumping 状态是否启用:", enabled)

GetStateEnabled

签名：GetStateEnabled(state: ControllerStateType) -> Bool (该状态是否已启用)

查询指定状态是否启用，返回 Bool。

参数	类型	说明
`state`	ControllerStateType	指定状态

返回值 Bool (该状态是否已启用)

示例代码

查询指定状态是否启用

lua

-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then return end

-- 查询 Jumping 状态当前是否启用
local enabled = baseController:GetStateEnabled(Enums.ControllerStateType.Jumping)
print("Jumping 状态是否启用:", enabled)
-- 根据查询结果决定后续逻辑分支
if enabled == false then
    print("跳跃状态当前被禁用")
end

GetExtraStates

签名：GetExtraStates() -> String[] (附加状态名列表)

获取当前所有附加状态，返回附加状态名列表（String[]）。

返回值 String[] (附加状态名列表)

示例代码

获取角色附加状态列表

lua

-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then return end

-- GetExtraStates 返回当前所有附加状态名组成的列表
local extraStates = baseController:GetExtraStates()
print("附加状态数量:", #extraStates)
-- 逐个输出状态名，确认列表内容
for index, stateName in ipairs(extraStates) do
    print("第", index, "个附加状态:", stateName)
end

AddExtraState

签名：AddExtraState(stateName: String) -> Bool (是否添加成功)

为控制器添加一个附加状态，返回是否添加成功（Bool）。

参数	类型	说明
`stateName`	`String`	附加状态名

返回值 Bool (是否添加成功)

示例代码

为角色添加附加状态

lua

-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then return end

-- 添加一个名为 Burning 的附加状态，返回值表示是否添加成功
local added = baseController:AddExtraState("Burning")
print("添加附加状态结果:", added)
-- 读取当前附加状态列表，确认状态是否生效
local extraStates = baseController:GetExtraStates()
print("当前附加状态数量:", #extraStates)

RemoveExtraState

签名：RemoveExtraState(stateName: String) -> Bool (是否删除成功)

移除指定的附加状态，返回是否删除成功（Bool）。

参数	类型	说明
`stateName`	`String`	附加状态名

返回值 Bool (是否删除成功)

示例代码

移除角色附加状态

lua

-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then return end

-- 先添加一个附加状态，再进行移除，便于观察返回值
local added = baseController:AddExtraState("Burning")
print("添加附加状态结果:", added)
local removed = baseController:RemoveExtraState("Burning")
print("移除附加状态结果:", removed)

RegisterCustomState

签名：RegisterCustomState(stateName: String, onPreEnter: Function, onEnter: Function, onPreLeave: Function, onLeave: Function) -> Bool (是否注册成功)

RegisterCustomState 用于为 BaseController 的角色状态机注册一个自定义状态，并同时为该状态绑定四个阶段的回调函数：onPreEnter（进入前）、onEnter（进入）、onPreLeave（离开前）与 onLeave（离开）。调用时需要按顺序传入状态名字符串 stateName 以及这四个 Function 类型的回调。函数返回 Bool，表示本次注册是否成功。

参数	类型	说明
`stateName`	`String`	状态名称
`onPreEnter`	`Function`	预进入回调
`onEnter`	`Function`	进入回调
`onPreLeave`	`Function`	预离开回调
`onLeave`	`Function`	离开回调

返回值 Bool (是否注册成功)

示例代码

注册自定义角色状态

lua

-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then return end

-- 注册自定义状态 Charging，并提供进入与离开四个阶段回调
local registered = baseController:RegisterCustomState(
    "Charging",
    function()
        print("准备进入 Charging")
        return true
    end,
    function()
        print("已进入 Charging")
    end,
    function()
        print("准备离开 Charging")
        return true
    end,
    function()
        print("已离开 Charging")
    end
)
print("自定义状态注册结果:", registered)

RegisterExtraState

签名：RegisterExtraState(stateName: String, onPreEnter: Function, onEnter: Function, onPreLeave: Function, onLeave: Function) -> Bool (是否注册成功)

为控制器的状态机注册一个自定义的附加状态，并同时指定该状态在进入与离开过程中的回调函数。调用时依次传入状态名 stateName、进入前回调 onPreEnter、进入回调 onEnter、离开前回调 onPreLeave、离开回调 onLeave，函数返回一个布尔值表示注册是否成功。注册完成后，该状态名就成为状态机可识别的一个附加状态，回调会在状态切换的相应时机被触发，用于在引擎内置状态之外扩展角色的自定义行为。

参数	类型	说明
`stateName`	`String`	状态名称
`onPreEnter`	`Function`	预进入回调
`onEnter`	`Function`	进入回调
`onPreLeave`	`Function`	预离开回调
`onLeave`	`Function`	离开回调

返回值 Bool (是否注册成功)

示例代码

注册自定义附加状态

lua

-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then return end

-- 注册名为 Freeze 的附加状态，并配置添加与移除阶段回调
local registered = baseController:RegisterExtraState(
    "Freeze",
    function()
        print("准备添加 Freeze")
        return true
    end,
    function()
        print("已添加 Freeze")
    end,
    function()
        print("准备移除 Freeze")
        return true
    end,
    function()
        print("已移除 Freeze")
    end
)
print("附加状态注册结果:", registered)

UnRegisterExtraState

签名：UnRegisterExtraState(stateName: String) -> Bool (是否取消注册成功)

取消注册自定义附加状态，返回是否取消注册成功（Bool）。

参数	类型	说明
`stateName`	`String`	状态名称

返回值 Bool (是否取消注册成功)

示例代码

取消注册自定义附加状态

lua

-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then return end

-- 先注册附加状态 Freeze，再取消注册
baseController:RegisterExtraState(
    "Freeze",
    function() return true end,
    function() print("添加 Freeze") end,
    function() return true end,
    function() print("移除 Freeze") end
)
local unregistered = baseController:UnRegisterExtraState("Freeze")
print("取消注册附加状态结果:", unregistered)

UnRegisterCustomState

签名：UnRegisterCustomState(stateName: String) -> Bool (是否取消注册成功)

取消注册自定义角色状态，返回是否取消注册成功（Bool）。

参数	类型	说明
`stateName`	`String`	状态名称

返回值 Bool (是否取消注册成功)

示例代码

取消注册自定义角色状态

lua

-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then return end

-- 先注册再取消注册，验证注销流程与返回值
baseController:RegisterCustomState(
    "Charging",
    function() return true end,
    function() print("进入 Charging") end,
    function() return true end,
    function() print("离开 Charging") end
)
local unregistered = baseController:UnRegisterCustomState("Charging")
print("取消注册自定义状态结果:", unregistered)

Move

签名：Move(moveDirection: Vector3, relativeToCamera: Bool) -> void

让控制器所属单位沿指定方向持续移动，并可选择是否按相机朝向进行方向换算。

参数	类型	说明
`moveDirection`	Vector3	移动方向
`relativeToCamera`	`Bool`	是否相对于相机

返回值 void

示例代码

按镜头方向移动当前角色

lua

-- @runtime client
local Players = game:GetService("Players")
local player = Players.LocalPlayer
if player == nil then return end
local character = player and player.Character
local controller = character and character.Controller
if controller == nil then return end
controller:Move(Vector3.New(1, 0, 0), true)

MoveTo

签名：MoveTo(position: Vector3, targetUnit: Unit) -> void

让控制器所属单位移动到指定位置或指定目标单位。

参数	类型	说明
`position`	Vector3	目标位置
`targetUnit`	Unit	目标模型(可选)

返回值 void

示例代码

通过角色 Controller 让角色移动到目标位置

lua

-- @runtime client
-- BaseController 通过角色宿主单位的 .Controller 属性获取
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer.Character
if character == nil then
    return
end
local baseController = character.Controller
if baseController == nil then
    return
end

-- MoveTo(目标位置, 目标单位(可选))
local position = Vector3.New(0, 0, 0)
baseController:MoveTo(position)
print("调用完成", baseController)

Jump

签名：Jump() -> void

BaseController 的 Jump 函数用于让控制器执行一次跳跃，调用形式为 controller:Jump()。该函数不接收任何参数，也没有返回值。

返回值 void

示例代码

让角色执行一次跳跃

lua

-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then return end

-- 先确认角色在地面上，避免空中触发跳跃无效
local grounded = baseController:IsGrounded()
if grounded then
    -- 执行一次跳跃
    baseController:Jump()
    print("已请求角色跳跃")
else
    print("角色未落地，跳过跳跃请求")
end

IsGrounded

签名：IsGrounded() -> Bool (是否地面站立)

判断控制器所属单位是否处于地面站立状态，返回 Bool。

返回值 Bool (是否地面站立)

示例代码

判断角色是否落地

lua

-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then return end

-- IsGrounded 返回角色当前是否处于地面站立状态
local grounded = baseController:IsGrounded()
print("角色是否落地:", grounded)
-- 只有落地时才允许执行跳跃逻辑
if grounded then
    baseController:Jump()
end

GetFloor

签名：GetFloor() -> SpaceUnit (脚下所踩Unit)

获取控制器当前脚下所踩的对象，返回类型为 SpaceUnit。

返回值 SpaceUnit (脚下所踩Unit)

示例代码

获取角色脚下所踩的对象

lua

-- @runtime client
-- 获取本地玩家角色上的控制器
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then
    return
end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then
    return
end

-- 查询角色脚下所踩的 Unit（悬空或非 Unit 地面时返回 nil）
local floor = baseController:GetFloor()
if floor ~= nil then
    print("角色当前站在 Unit 上:", floor)
else
    print("角色当前脚下没有 Unit（悬空或非 Unit 地面）")
end

TakeDamage

签名：TakeDamage(damage: Float) -> void

TakeDamage 是 BaseController 提供的伤害结算接口，接收一个必填的 Float 类型参数 damage，用于对该控制器所代表的角色施加一次伤害。控制器当前的生存状态由 Health 与 MaxHealth 两个属性表示，因此 TakeDamage 通常与这两个属性配合使用：前者反映受伤后的剩余生命，后者给出生命上限。该方法没有返回值，调用结果需要从属性或事件侧观察。

参数	类型	说明
`damage`	`Float`	伤害数值

返回值 void

示例代码

在服务端对角色控制器结算伤害

lua

-- @runtime server
local player = game:GetService('Players'):GetPlayers()[1]
if player == nil then return end
local character = player and player.Character
local controller = character and character.Controller
if controller == nil then return end
controller:TakeDamage(10)

Heal

签名：Heal(health: Float) -> void

Heal 是 BaseController 的成员函数，用于为控制器所控制的角色恢复生命值。调用时需要传入一个 Float 类型的 health 参数，表示本次恢复的生命数值，函数没有返回值。

参数	类型	说明
`health`	`Float`	治疗数值

返回值 void

示例代码

在服务端治疗角色控制器

lua

-- @runtime server
local player = game:GetService('Players'):GetPlayers()[1]
if player == nil then return end
local character = player and player.Character
local controller = character and character.Controller
if controller == nil then return end
controller:Heal(10)

Reborn

签名：Reborn() -> void

Reborn 是 BaseController 的成员函数，成员标题为“复活角色”。该函数不接收任何参数，也没有返回值，用于让控制器所控制的对象执行一次复活处理。

返回值 void

示例代码

在服务端复活角色

lua

-- @runtime server
local player = game:GetService('Players'):GetPlayers()[1]
if player == nil then return end
local character = player and player.Character
local controller = character and character.Controller
if controller == nil then return end
controller:Reborn()

SetPhysicsActive

签名：SetPhysicsActive(active: Bool) -> void

设置当前控制器物理模拟的开关状态。传入 active 为 true 时开启物理模拟，传入 false 时关闭物理模拟。该方法属于 BaseController，挂在角色或单位上的控制器实例可直接调用。

参数	类型	说明
`active`	`Bool`	物理开关

返回值 void

示例代码

开关角色物理

lua

-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then return end

-- 关闭角色物理模拟，使其暂不受物理影响
baseController:SetPhysicsActive(false)
print("已关闭角色物理")
-- 稍后恢复物理模拟
baseController:SetPhysicsActive(true)
print("已重新开启角色物理")

ApplyForce

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

对控制器所属单位施加一个力，力的大小和方向由传入的三维向量决定。

参数	类型	说明
`force`	Vector3	施加的力

返回值 void

示例代码

给当前角色施加向上的力

lua

-- @runtime client
local Players = game:GetService("Players")
local player = Players.LocalPlayer
if player == nil then return end
local character = player and player.Character
local controller = character and character.Controller
if controller == nil then return end
controller:ApplyForce(Vector3.New(0, 200, 0))

SetMaxLinearVelocity

签名：SetMaxLinearVelocity(velocity: Float) -> void

设置当前控制器所驱动单位的最大线速度，入参 velocity 为 Float 类型且为必填，调用后没有返回值。

参数	类型	说明
`velocity`	`Float`	最大线速度

返回值 void

示例代码

设置角色最大线速度

lua

-- @runtime client
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local character = localPlayer.Character
local baseController = character and character.Controller
if baseController == nil then return end

-- 将角色线速度上限设置为 200
baseController:SetMaxLinearVelocity(200)
print("已设置最大线速度为 200")

推球撞方块

跟着做一个小游戏

边做边查

按需求查专题

疯狂农场

BaseController ​

概览 ​

继承关系 ​

继承成员 ​

适用场景 ​

使用要点 ​

注意事项 ​

代码示例 ​

读取当前玩家角色的控制器状态 ​

属性 (12) ​

关联类型 ​

事件 (11) ​

StateChanged ​

ExtraStatesChanged ​

OnLanded ​

OnStartFalling ​

Died ​

HealthChanged ​

MoveToFinished ​

OnReborn ​

OnJump ​

OnCollisionEnter ​

OnCollisionExit ​

函数 (22) ​

GetState ​

ChangeState ​

SetStateEnabled ​

GetStateEnabled ​

GetExtraStates ​

AddExtraState ​

RemoveExtraState ​

RegisterCustomState ​

RegisterExtraState ​

UnRegisterExtraState ​

UnRegisterCustomState ​

Move ​

MoveTo ​

Jump ​

IsGrounded ​

GetFloor ​

TakeDamage ​

Heal ​

Reborn ​

SetPhysicsActive ​

ApplyForce ​

SetMaxLinearVelocity ​

BaseController

概览

继承关系

继承成员

适用场景

使用要点

注意事项

代码示例

读取当前玩家角色的控制器状态

属性 (12)

关联类型

事件 (11)

StateChanged

ExtraStatesChanged

OnLanded

OnStartFalling

Died

HealthChanged

MoveToFinished

OnReborn

OnJump

OnCollisionEnter

OnCollisionExit

函数 (22)

GetState

ChangeState

SetStateEnabled

GetStateEnabled

GetExtraStates

AddExtraState

RemoveExtraState

RegisterCustomState

RegisterExtraState

UnRegisterExtraState

UnRegisterCustomState

Move

MoveTo

Jump

IsGrounded

GetFloor

TakeDamage

Heal

Reborn

SetPhysicsActive

ApplyForce

SetMaxLinearVelocity