工坊手册

主题

EffectUnit ​

概览 ​

字段值
KindUnit · 单位 Unit
Realmcommon

继承关系 ​

  • Unit（4 属性 / 25 函数 / 6 事件）

继承成员 ​

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

特效单位。EffectId 是特效资源标识。变换字段有特殊规则：Parent 为 BasePart/Attachment 子类时进入父跟随模式，Position/Rotation 由 Parent 驱动且不会被回写更新（读到的可能是旧值），SetPosition/SetRotation/SetScale/MoveTo 会被静默忽略，而 Scale 属性仍由自身控制、直写属性生效；设置 EffectBindData 后绑定优先于父跟随

适用场景 ​

当关卡中已经放置或由编辑流程配置好特效实例后，脚本可按战斗、交互或机关状态切换特效表现。

使用要点 ​

先通过 World:FindFirstChild 等公开对象树接口获取目标 EffectUnit，再调用 SetVisible、SetPosition、SetScale、SetColor、SetDuration、SetBindData 等公开成员控制表现。EffectId 用于指定特效资源，支持 official://effect/{id} 与 custom://{asset_id} 两种资源协议；Meta 标记为可编辑，未声明只读。Parent 为 BasePart/Attachment 子类时，位置与旋转由父级驱动，SetPosition、SetRotation、SetScale、MoveTo 会被静默忽略；父跟随模式下请直接写入 Scale 属性。

注意事项 ​

EffectId 支持 official://effect/{id} 与 custom://{asset_id} 两种资源协议；EnemyEffectEnable 开启时，在创建期按 特效归属 与当前玩家的阵营关系选择 EffectId 或 EnemyEffectId，创建后修改 EnemyEffectId 不会切换已播放特效。文档示例优先获取场景中已配置好的 EffectUnit，不虚构未验证的资源 ID。当前公开 Meta 没有独立的 Play 方法。SetColor 第一个参数是 Color 类型（如 Color.New(255,0,0,255)），不是字符串十六进制；强度 strength 取 0-100，混合因子 blendFactor 取 0-1，只有 efx 类特效且 EnableColor 为 true 时生效。Duration 小于等于 0 时不自动销毁并取消已有计时器，大于 0 时到期自动销毁；运行期修改重排计时器仅在客户端生效。Parent 为 BasePart/Attachment 子类时，Position/Rotation 不会被回写更新，读到的可能是旧值；SetPosition、SetRotation、SetScale、MoveTo 被静默忽略；Scale 属性仍由自身控制，直写属性生效。主动绑定优先于 Parent 跟随：绑定期间特效由挂点持续驱动，Position 表示 BindOffset，恢复 Parent 跟随需要将 EffectBindData 赋为空。

代码示例 ​

控制场景中已配置的特效 ​

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

local effect = world:FindFirstChild("MyEffect", true)
if effect ~= nil and effect:IsA("EffectUnit") then
    effect:SetColor(Color.New(255, 0, 0, 255), 100, 0.5)
    effect:SetPosition(Vector3.New(0, 5, 0))
    effect:SetVisible(true)
end

通过 Parent 让已配置特效跟随玩家角色 ​

lua
-- @runtime client
local world = game:GetService("World")
local players = game:GetService("Players")
local player = players.LocalPlayer
if player == nil then return end
local character = player and player.Character
if not character then
    print("当前没有可绑定的玩家角色")
    return
end

local effect = world:FindFirstChild("MyEffect", true)
if effect ~= nil and effect:IsA("EffectUnit") then
    -- 当前 SetBindData/StartposAttach 的挂点绑定表现依赖运行包，优先使用预配置 Parent 跟随
    effect.Parent = character
    effect:SetVisible(true)
end

属性 (19) ​

Name类型默认值说明
PositionVector3[0.0, 0.0, 0.0]单位位置。父跟随模式下（Parent 为 BasePart/Attachment 子类）位置完全由 Parent 驱动，运行期不会被回写更新（服务端初始化时会用 Parent 变换回写一次），读取得到的通常是旧值；该模式下 SetPosition / MoveTo 会被静默忽略，拦截判定只看 Parent、与是否设置绑定无关。设置 EffectBindData 后以绑定为第一优先级：特效被挂到目标挂点，由引擎按挂点持续驱动特效变换（不回写本字段），本字段的值等于传入的 BindOffset 偏移量（缺省为 (0,0,0)），不再表示世界坐标。
RotationQuaternion[0.0, 0.0, 0.0, 1.0]单位旋转（四元数）。父跟随模式下（Parent 为 BasePart/Attachment 子类）旋转由 Parent 驱动，本字段不会被回写更新；该模式下 SetRotation 会被静默忽略。
ScaleVector3[1.0, 1.0, 1.0]单位缩放。与 Position/Rotation 略有不同：父跟随模式下 Scale 属性不会被拦截，直写本字段仍生效；但 SetScale() 在该模式下与 SetPosition/SetRotation 一样被静默忽略，此时请直写本属性。
EffectIdString""特效资源。支持 official://effect/{id} 与 custom://{asset_id} 两种资源协议。
DiffuseColorColorColor.New(255, 255, 255, 255)特效自定义颜色。仅 efx 类特效支持染色（sfx 忽略本字段）；资源初始化/刷新时按 EnableColor 决定是否应用，运行期直接改本字段仍会推送到引擎。
ColorStrengthInt100颜色强度（0-100）。仅当 EnableColor 为 true 时生效。
BlendFactorFloat1.0颜色融合系数（0-1）。仅当 EnableColor 为 true 时生效。
EnableColorBoolfalse是否启用自定义颜色。false 时特效使用资源自带颜色，此时修改 DiffuseColor/ColorStrength/BlendFactor 不产生效果；true 时三者按当前值整体应用。
PlayRateFloat1.0特效播放速率，有效范围 [0.1, 50]，越界值会被截断到边界。
VisibleBooltrue可见性。只能运行时设置，等价于调用 SetVisible。
VolumeFloat50.0特效音效音量（0-100）。只能运行时设置。
DurationFloat-1持续时间（秒）。小于等于 0 表示不自动销毁自身，并取消已有计时器；大于 0 时到期自动销毁特效。运行期修改重排计时器仅在客户端生效
IsMuteBoolfalse是否静音。只能运行时设置，等价于调用 SetMute：写入 true 会把音效音量置 0；写回 false 不会自动恢复音量（需用 Volume 恢复）。
EffectBindDataEffectBindData{}EffectUnit 有两种绑定模式：1、Parent 为 BasePart/Attachment 子类时跟随 Parent；2、设置 EffectBindData 主动绑定到目标挂点。主动设置 EffectBindData 为第一优先级：绑定生效期间 Parent 跟随自动关闭，特效由引擎按挂点持续驱动（持续覆盖特效变换，不回写本字段），Position 被写成 BindOffset 偏移量，想恢复 Parent 跟随需将 EffectBindData 赋为空。
EffectEndBindDataEffectBindData{}连线特效终点挂点绑定数据（BindUnitId / BindSocket / BindOffset）。目标单位尚未创建时会等待其创建后自动接通。
EnemyEffectEnableBoolfalse启动敌我特效区分。开启后，在特效创建期根据特效归属 与当前玩家的阵营关系，决定使用 EffectId 还是 EnemyEffectId。
EnemyEffectIdString""敌方视角使用的特效资源。仅在 EnemyEffectEnable 为 true 且 特效归属 与当前玩家为敌对关系时生效，且在创建期完成替换——特效创建后再修改本字段不会切换已播放的特效。
AsyncLoadBoolfalse是否异步加载特效资源。开启后特效资源在后台加载，不阻塞主线程，适合较大的特效；加载期间设置的属性会被缓存，特效就绪后按最后一次设置统一生效。注意：特效创建后、资源就绪前的极短时段内，只有可见性、音量、播放速率、强制循环与自定义颜色（基础颜色/颜色强度/融合系数）这些渲染属性会被自动应用，缩放、是否静音等在此时段内修改可能被忽略，建议等特效就绪后再设置这些属性（该时段是资源路径解析阶段，与是否开启本开关无关）。
ForceLoopBoolfalse开启后强制特效循环播放；关闭时不额外干预，按特效资源自带的播放方式执行（资源本身是循环的仍会循环）。对 efx 与 sfx 特效均生效。运行期由 true 改为 false 不会恢复资源原始 loop，已播放完毕的实例改本字段无效。

关联类型 ​

函数 (14) ​

SetRate ​

签名：SetRate(rate: Float) -> void

设置特效播放速率，范围 [0.1, 50]，越界会被截断，等价于写入 PlayRate。

参数类型说明
rateFloat速率

返回值 void

示例代码

调整已配置特效播放速率

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

local effect = world:FindFirstChild("MyEffect", true)
if effect ~= nil and effect:IsA("EffectUnit") then
    effect:SetRate(2)
end

SetScale ​

签名：SetScale(scale: Vector3) -> void

设置特效缩放，等价于直写 Scale 属性。注意：父跟随模式（Parent 为 BasePart/Attachment 子类）下与 SetPosition/SetRotation 一样被静默忽略，该模式下请直写 Scale 属性。

参数类型说明
scaleVector3缩放

返回值 void

示例代码

调整已配置特效缩放

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

local effect = world:FindFirstChild("MyEffect", true)
if effect ~= nil and effect:IsA("EffectUnit") then
    effect:SetScale(Vector3.New(1.5, 1.5, 1.5))
end

SetVisible ​

签名：SetVisible(visible: Bool) -> void

设置特效可见性，等价于写入 Visible。

参数类型说明
visibleBool可见性

返回值 void

示例代码

切换已配置特效可见性

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

local effect = world:FindFirstChild("MyEffect", true)
if effect ~= nil and effect:IsA("EffectUnit") then
    effect:SetVisible(true)
end

SetRotation ​

签名：SetRotation(rotate: Quaternion) -> void

设置特效旋转。父跟随模式下直接返回，不修改任何数据。

参数类型说明
rotateQuaternion旋转

返回值 void

示例代码

调整已配置特效旋转

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

local effect = world:FindFirstChild("MyEffect", true)
if effect ~= nil and effect:IsA("EffectUnit") then
    effect:SetRotation(Quaternion.New(0, 0, 0, 1))
end

SetPosition ​

签名：SetPosition(position: Vector3) -> void

设置特效位置。父跟随模式（Parent 为 BasePart/Attachment 子类）下直接返回，不修改任何数据（拦截判定只看 Parent，与是否设置绑定无关）；绑定状态下本值语义为挂点局部偏移。

参数类型说明
positionVector3位置

返回值 void

示例代码

调整已配置特效位置

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

local effect = world:FindFirstChild("MyEffect", true)
if effect ~= nil and effect:IsA("EffectUnit") then
    effect:SetPosition(Vector3.New(0, 5, 0))
end

RemoveSound ​

签名：RemoveSound() -> void

关闭特效音效，等价于将 Volume 置为 0。

返回值 void

示例代码

移除已配置特效声音

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

local effect = world:FindFirstChild("MyEffect", true)
if effect ~= nil and effect:IsA("EffectUnit") then
    effect:RemoveSound()
end

SetColor ​

签名：SetColor(color: Color, strength: Int, blendFactor: Float) -> void

一次性设置特效颜色、颜色强度与融合系数，等价于同时写入 DiffuseColor、ColorStrength、BlendFactor。仅 efx 类特效支持，且需要 EnableColor 为 true。

参数类型说明
colorColor颜色
strengthInt强度
blendFactorFloat混合比例

返回值 void

示例代码

设置特效颜色（Color 类型）

lua
-- @runtime client
local World = game:GetService('World')
local effect = World:FindFirstChild('MyEffect', true)
if effect ~= nil and effect:IsA('EffectUnit') then
    local color = Color.New(255, 0, 0, 255)  -- 红色，Color 类型
    effect:SetColor(color, 100, 0.5)  -- strength=100, blendFactor=0.5
end

SetBindData ​

签名：SetBindData(otherUnit: SpaceUnit, socket: String, offset: Vector3, bindType: EffectBindType) -> void

把特效起点绑定到目标单位的挂点。绑定优先于 Parent 跟随：绑定生效期间父跟随自动关闭，Position 被改写为 offset，特效由引擎按挂点驱动（不回写本字段）。unit 为空或尚未入场景时跳过（是跳过，不是解绑）；解绑请把 EffectBindData 赋为空。bindType 必须包含位移绑定。

⚙ 当前运行包的挂点绑定表现依赖特效资源和有效 socket；实测存在调用后仍停在固定位置的情况。绑定不可用时优先改用编辑器预配置 Parent/Attachment 跟随。

参数类型说明
otherUnitSpaceUnit单位预制
socketString挂点
offsetVector3位置偏移
bindTypeEffectBindType绑定类型

返回值 void

示例代码

当前版本使用 Parent 跟随作为绑定替代

lua
-- @runtime client
local World = game:GetService('World')
local targetUnit = World:FindFirstChild('MyTargetUnit', true)
local effect = World:FindFirstChild('MyEffect', true)
if effect ~= nil and effect:IsA('EffectUnit') and targetUnit ~= nil then
    -- SetBindData 当前可能无法持续跟随；先使用已配置的父子关系
    effect.Parent = targetUnit
    effect:SetVisible(true)
end

StartposAttach ​

签名：StartposAttach(otherUnit: SpaceUnit, socket: String, offset: Vector3, bindType: EffectBindType) -> void

设置连线特效起点，语义与 SetBindData 完全一致。

参数类型说明
otherUnitSpaceUnit单位预制
socketString挂点
offsetVector3位置偏移
bindTypeEffectBindType绑定类型

返回值 void

示例代码

绑定已配置特效起点到单位

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

local effect = world:FindFirstChild("MyEffect", true)
local target = world:FindFirstChild("MyTargetUnit", true)
if effect ~= nil and effect:IsA("EffectUnit") and target ~= nil and target:IsA("SpaceUnit") then
    effect:StartposAttach(target, "Origin", Vector3.New(0, 2, 0), Enums.EffectBindType.ALL)
end

EndposAttach ​

签名：EndposAttach(otherUnit: SpaceUnit, socket: String, offset: Vector3) -> void

设置连线特效终点挂点。目标单位为空或尚未入场景时跳过绑定。

参数类型说明
otherUnitSpaceUnit单位预制
socketString挂点
offsetVector3位置偏移

返回值 void

示例代码

绑定已配置特效终点到单位

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

local effect = world:FindFirstChild("MyEffect", true)
local target = world:FindFirstChild("MyTargetUnit", true)
if effect ~= nil and effect:IsA("EffectUnit") and target ~= nil and target:IsA("SpaceUnit") then
    effect:EndposAttach(target, "Origin", Vector3.New(0, 2, 0))
end

SetDuration ​

签名：SetDuration(duration: Float) -> void

设置特效持续时间，等价于写入 Duration：小于等于 0 表示不自动销毁自身，并取消已有计时器；大于 0 会重排到期销毁计时。

⚙ SetDuration 等价于写入 Duration，不会重新选择特效资源。duration 小于等于 0 时不自动销毁自身，并取消已有计时器；大于 0 时安排到期自动销毁，运行期修改重排计时器仅在客户端生效。

参数类型说明
durationFloat时长

返回值 void

示例代码

调整已配置特效的持续时长

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

local effect = world:FindFirstChild("MyEffect", true)
if effect ~= nil and effect:IsA("EffectUnit") then
    effect:SetDuration(3)
    effect:SetVisible(true)
end

MoveTo ​

签名：MoveTo(targetPos: Vector3, speed: Float, callBack: Function) -> void

设置特效位移并触发移动。父跟随模式下直接返回，不修改任何数据；targetPos 为空或 speed <= 0 时也不生效。

参数类型说明
targetPosVector3目标位置
speedFloat线速度(米/秒)
callBackFunction结束回调

返回值 void

示例代码

移动已配置特效到目标位置

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

local effect = world:FindFirstChild("MyEffect", true)
if effect ~= nil and effect:IsA("EffectUnit") then
    effect:MoveTo(Vector3.New(0, 5, 0), 3, function()
        print("特效移动结束")
    end)
end

SetMute ​

签名：SetMute() -> void

将特效音效静音，等价于写入 IsMute。

返回值 void

示例代码

静音已配置特效

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

local effect = world:FindFirstChild("MyEffect", true)
if effect ~= nil and effect:IsA("EffectUnit") then
    effect:SetMute()
end

Restart ​

签名：Restart() -> void

重播特效。一次性特效播完后会被引擎移出场景，重播时自动重新入场并补推起点/终点绑定。

返回值 void

示例代码

重播场景中已配置的特效

lua
-- @runtime client
-- 获取 World 服务：场景中的 Unit 实例都挂载在它下面
local World = game:GetService("World")
-- 按名称查找编辑器里已配置好的 EffectUnit（true 表示递归查找子节点）
local effectUnit = World:FindFirstChild("MyEffect", true)
if effectUnit == nil or not effectUnit:IsA("EffectUnit") then
    -- 未找到目标实例时提前返回，避免后续调用报错
    print("场景中未找到名为 MyEffect 的 EffectUnit")
    return
end
-- 先确保特效处于可见状态，否则重播后也看不到效果
effectUnit:SetVisible(true)
-- 调用 Restart 从头重播该特效（无参数、无返回值）
effectUnit:Restart()
-- 输出执行结果，方便确认重播流程已走完
print("特效重播完成")