EffectService

概览

字段	值
Kind	Service · 服务 Service
Realm	common

继承关系

• Unit（4 属性 / 25 函数 / 6 事件）
  • [EffectService]（1 函数）

> Service 继承 Unit 仅表示运行时类型关系；作者可用 API 以当前 Service 页面显式列出的成员为准，不自动包含 Unit 的创建、层级或销毁能力。

特效服务是面向客户端本地表现的全局服务，其公开能力集中在 PlayLocalEffect 一个函数上。该函数按给定的位置、旋转与缩放播放一个本地特效，并可选地控制特效的保留时长、是否循环以及是否异步加载，调用后会返回一个句柄供后续引用。特效资源通过统一的资源标识字符串指定，因此调用方无需关心特效的内部结构即可完成播放。

适用场景

典型场景是角色释放技能、拾取物品或界面交互反馈需要即时视觉表现时，由客户端脚本调用该服务在指定世界坐标与朝向处播放本地特效。由于播放仅对当前客户端生效，它适合承担无需服务端广播的一次性表现需求。

使用要点

先通过 game:GetService("EffectService") 获取服务实例，并在调用前确认实例是否可用；随后调用 PlayLocalEffect，依次传入特效资源标识、Vector3 类型的位置、Quaternion 类型的旋转与 Vector3 类型的缩放，再按需追加保留时长、是否循环、是否异步加载等可选参数。特效标识只能使用 official://effect/{路径} 或 custom://{资产编号} 两种形式，其它写法不被接受。

注意事项

最新 Meta 已公开 EffectService，但 2026-08-12 当前编辑器运行包中 game:GetService("EffectService") 仍返回 nil；这是运行时服务导出尚未对齐 Meta。示例会先检查服务是否可用，服务未导出时安全退出。服务可用后，PlayLocalEffect 的 effectId 只接受 official://effect/{path} 或 custom://{asset_id}，不接受裸数字、裸路径、official://preset/... 或其他 scheme。返回的 EffectHandle 当前只作为引用，公开契约没有 Stop、Destroy 或属性控制方法；不要编造句柄控制 API。

代码示例

播放本地特效

-- @runtime client
local effectService = game:GetService('EffectService')
if effectService == nil then
    print('EffectService 当前运行包尚未导出')
    return
end
local effectId = 'official://effect/2039'
local position = Vector3.New(0, 3, 0)
local rotation = Quaternion.Identity()
local scale = Vector3.New(1, 1, 1)
local handle = effectService:PlayLocalEffect(effectId, position, rotation, scale, 2.0, false, false)
print('特效句柄:', handle)

关联类型

• Unit

函数 (1)

PlayLocalEffect

签名：PlayLocalEffect(effectId: String, position: Vector3, rotation: Quaternion, scale: Vector3, keepTime?: Float, loop?: Bool, isAsync?: Bool) -> Any (EffectHandle（特效句柄引用）)

PlayLocalEffect 是 EffectService 上用于播放本地特效的接口：传入特效标识 effectId，以及位置 position、旋转 rotation、缩放 scale 三个空间参数，即可在对应空间位置上播放该特效；还可选地通过 keepTime、loop、isAsync 控制特效表现方式。调用后会返回一个特效句柄引用（EffectHandle），可用于后续对该次播放的引用与操作。

⚙ 该接口仅在客户端生效；调用前需确认当前运行包已导出 EffectService。effectId 必须使用 official://effect/{path} 或 custom://{asset_id}。

参数	类型	说明
effectId	String	特效资源 URI（仅 official://effect/{path} 或 custom://{asset_id}）
position	Vector3	世界坐标位置（默认 0,0,0）
rotation	Quaternion	旋转（默认单位四元数）
scale	Vector3	缩放（默认 1,1,1）
keepTime?	Float	自动销毁延时秒（默认 -1 不自动销毁）
loop?	Bool	是否循环（默认 false）
isAsync?	Bool	是否异步加载（默认 false 同步，true 时不阻塞主线程）

返回值 Any (EffectHandle（特效句柄引用）)

示例代码

播放本地特效

-- @runtime client
local effectService = game:GetService('EffectService')
if effectService == nil then
    print('EffectService 当前运行包尚未导出')
    return
end
local handle = effectService:PlayLocalEffect(
    'official://effect/2039',
    Vector3.New(0, 3, 0),
    Quaternion.Identity(),
    Vector3.New(1, 1, 1),
    2.0,
    false,
    false
)
print('特效句柄:', handle)