工坊手册

主题

EffectUnit ​

特效单位。EffectId 是特效资源标识。变换字段有特殊规则：Parent 为 BasePart/Attachment 子类时进入父跟随模式，Position/Rotation 由 Parent 驱动且不会被回写更新（读到的可能是旧值），...

概览 ​

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

继承自 Unit；可通过 World:CreateUnit("EffectUnit", ...) 创建；返回单个单位

函数 ​

SetRate ​

签名：SetRate(rate: Float)

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

参数类型说明
rateFloat速率

调整已配置特效播放速率

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)

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

参数类型说明
scaleVector3缩放

调整已配置特效缩放

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)

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

参数类型说明
visibleBool可见性

切换已配置特效可见性

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)

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

参数类型说明
rotateQuaternion旋转

调整已配置特效旋转

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)

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

参数类型说明
positionVector3位置

调整已配置特效位置

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()

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

移除已配置特效声音

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)

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

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

设置特效颜色（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)

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

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

StartposAttach ​

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

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

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

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

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)

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

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

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

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)

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

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

参数类型说明
durationFloat时长

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

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)

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

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

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

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()

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

静音已配置特效

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()

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

重播场景中已配置的特效

lua
-- @runtime client
local world = game:GetService('World')
local effect = world:FindFirstChild('MyEffect', true)
if effect == nil or not effect:IsA('EffectUnit') then return end
effect:Restart()

属性 ​

名称类型默认值说明
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，已播放完毕的实例改本字段无效。