工坊手册

主题

BaseMotorUnit ​

概览 ​

字段值
KindUnit · 单位 Unit
Realmcommon

继承关系 ​

继承成员 ​

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

运动器基类，为各类周期性或往返运动的子类（如角速度运动器）提供统一的配置入口与控制接口。通过循环、返程、单程时间、暂停时长等属性可以编排运动节奏，并借助开始、暂停、继续、返程、停止等函数对运动过程进行实时干预。运动器还会在启动与停止时触发事件，便于外部逻辑感知状态变化。

适用场景 ​

适用于需要让单位或实体按既定节奏往复运动、循环转动或定时启停的场景，通常以具体运动器子类挂接到目标单位后再配置参数。

使用要点 ​

运行时不直接创建该基类，而是先通过世界服务创建具体子类实例，例如用 World:CreateUnit 创建角速度运动器并指定目标单位作为父级。随后配置循环或返程相关属性，再调用开始函数启动运动，并通过暂停、继续、返程、停止等函数控制过程。需要感知启停时，可监听开始与停止事件。

注意事项 ​

BaseMotorUnit 是各种运动器（Angular/Linear/CurveVel/Pendulum/Waypoint）的基类，运行时不应直接创建 BaseMotorUnit；演示基类 API 时请创建具体子类。通过 IsCycle、BackTracking、HalfCycleTime、ArrivalPauseTime、BackPauseTime 与 Duration 配置循环、返程和时序，再调用 Start/Pause/Resume/Backtrack/Stop 控制运动。运动器通过 OnMotorStart / OnMotorStop 事件回调感知状态。

代码示例 ​

用具体运动器子类控制目标单位 ​

lua
-- @runtime client
local World = game:GetService('World')
local target = World:CreateUnit('WorldUnit', { Position = Vector3.New(0, 3, 0) })
local motor = World:CreateUnit('AngularMotorUnit', {
    Parent = target,
    AngularVelocity = Vector3.New(0, 90, 0),
})
motor.OnMotorStart:Once(function()
    print('运动器已启动')
end)
motor:Start()

属性 (10) ​

Name类型默认值说明
InitDelayTimeFloat0.0设定运动单元从启动到真正开始运动之前的等待时间，单位为秒。延迟期间运动单元保持静止。
IsCycleBoolfalse控制运动单元是否循环执行运动。开启后，运动流程会反复进行，直到停止或停用。
IsActiveBooltrue控制运动单元是否处于启用状态。关闭后运动单元不再执行运动逻辑，保持当前状态。
BackTrackingBoolfalse控制运动单元在到达目标位置后是否沿原路径返回起点。开启后运动单元将执行往返运动。
HalfCycleTimeFloat2.0设定运动单元完成单程运动所需的时间，单位为秒。单程运动指从起点到目标位置或从目标位置返回起点的单向过程。
ArrivalPauseTimeFloat0.0设定运动单元到达目标位置后的暂停时长，单位为秒。到达暂停结束后，运动单元才会继续后续动作（例如返程或结束）。
BackPauseTimeFloat0.0设定运动单元从目标位置返程回到起点后的暂停时长，单位为秒。仅当开启返程功能时生效。
DurationFloat0.0设定运动单元执行一次完整运动过程的持续时间，单位为秒。该时间用于控制整体运动的时长基准。
ActiveEventNameString""BaseMotorUnit 的运动开始事件名称属性，用于记录或指定电机单元开始运动阶段所对应的事件名。该属性为字符串类型，可直接读写。
StopEventNameString""BaseMotorUnit 的运动结束事件名称属性，用于记录或指定电机单元结束运动阶段所对应的事件名。该属性为字符串类型，可直接读写。

关联类型 ​

事件 (2) ​

OnMotorStart ​

签名：OnMotorStart() 触发：local

当运动器开始运动时触发。

示例代码

监听运动器启动

lua
-- @runtime client
local World = game:GetService('World')
local target = World:CreateUnit('WorldUnit', { Position = Vector3.New(0, 3, 0) })
local motor = World:CreateUnit('AngularMotorUnit', { Parent = target, AngularVelocity = Vector3.New(0, 90, 0) })
motor.OnMotorStart:Once(function() print('运动器已启动') end)
motor:Start()

OnMotorStop ​

签名：OnMotorStop() 触发：local

当运动器停止运动时触发。

示例代码

监听运动器停止

lua
-- @runtime client
local World = game:GetService('World')
local motor = World:FindFirstChild('ConfiguredLinearMotor', true)
if motor == nil or not motor:IsA('LinearMotorUnit') then return end
motor.OnMotorStop:Once(function() print('运动器已停止') end)
motor:Start()
motor:Stop()

函数 (5) ​

Start ​

签名：Start() -> void

启动运动器的运动。

返回值 void

示例代码

启动已配置的具体运动器

lua
-- @runtime client
-- 地图中需有名为 ConfiguredLinearMotor 的已配置直线运动器
local motor = game:GetService('World'):FindFirstChild('ConfiguredLinearMotor', true)
if motor == nil or not motor:IsA('LinearMotorUnit') then return end
motor:Start()

Pause ​

签名：Pause() -> void

暂停运动器的当前运动。

返回值 void

示例代码

暂停正在运行的运动器

lua
-- @runtime client
-- 目标是地图中已启动的直线运动器
local motor = game:GetService('World'):FindFirstChild('ConfiguredLinearMotor', true)
if motor == nil or not motor:IsA('LinearMotorUnit') then return end
motor:Pause()

Resume ​

签名：Resume() -> void

恢复已暂停的运动器运动。

返回值 void

示例代码

恢复已暂停的运动器

lua
-- @runtime client
-- 目标是地图中已暂停的直线运动器
local motor = game:GetService('World'):FindFirstChild('ConfiguredLinearMotor', true)
if motor == nil or not motor:IsA('LinearMotorUnit') then return end
motor:Resume()

Backtrack ​

签名：Backtrack() -> void

使运动器立即开始返程运动。

返回值 void

示例代码

让运动器开始返程

lua
-- @runtime client
local motor = game:GetService('World'):FindFirstChild('ConfiguredLinearMotor', true)
if motor == nil or not motor:IsA('LinearMotorUnit') then return end
motor:Backtrack()

Stop ​

签名：Stop() -> void

停止运动器的运动。

返回值 void

示例代码

停止运动器

lua
-- @runtime client
local motor = game:GetService('World'):FindFirstChild('ConfiguredLinearMotor', true)
if motor == nil or not motor:IsA('LinearMotorUnit') then return end
motor:Stop()