API
Return to top
Effect
编辑

场景 / Effect

Effect Class
​

特效

通常用于游戏场景中的效果表现，如火焰，水流，武器拖尾等，当编辑器细节面板勾选自动启用时，运行游戏会自动播放特效。

如需精确控制特效的播放与停止，请使用 play 和 stop 方法。不同特效有不同的生命周期，部分特效可通过细节面板中参数调节。

使用示例:创建一个名为"EffectExample"的脚本，放置在对象栏中，打开脚本，输入以下代码保存，运行游戏，你将在场景中看到粒子特效炸裂的效果。代码如下：
ts
@Component
export default class EffectExample extends Script {

    private readonly effect = {
        assetID: "145884",
        object: null as mw.Effect,
    };

    protected onStart(): void {
        this.createEffect();
    }

    @RemoteFunction(Client)
    public async createEffect(): Promise<void> {
        const success = await mw.AssetUtil.asyncDownloadAsset(this.effect.assetID);
            if (success) {
                // 下载完毕创建特效
                this.effect.object = await mw.GameObject.asyncSpawn(this.effect.assetID) as mw.Effect;

                // 设置特效transform
                const transform = new mw.Transform(new mw.Vector(500, 0, 0), new mw.Rotation(0, 0, 0), new mw.Vector(1, 1, 1));
                this.effect.object.localTransform = transform;

                // 播放特效
                this.effect.object.play();
                // 设置特效参数Life标量值
                this.effect.object.setFloat("LifeTime", 10);
                // 设置特效参数Speed向量值
                this.effect.object.setVector("Speed", new mw.Vector(0,0,150));
                // 设置特效参数Color颜色值
                this.effect.object.setColor("Color", new mw.LinearColor(1,0,0,1));
            }
    }
}
@Component
export default class EffectExample extends Script {

    private readonly effect = {
        assetID: "145884",
        object: null as mw.Effect,
    };

    protected onStart(): void {
        this.createEffect();
    }

    @RemoteFunction(Client)
    public async createEffect(): Promise<void> {
        const success = await mw.AssetUtil.asyncDownloadAsset(this.effect.assetID);
            if (success) {
                // 下载完毕创建特效
                this.effect.object = await mw.GameObject.asyncSpawn(this.effect.assetID) as mw.Effect;

                // 设置特效transform
                const transform = new mw.Transform(new mw.Vector(500, 0, 0), new mw.Rotation(0, 0, 0), new mw.Vector(1, 1, 1));
                this.effect.object.localTransform = transform;

                // 播放特效
                this.effect.object.play();
                // 设置特效参数Life标量值
                this.effect.object.setFloat("LifeTime", 10);
                // 设置特效参数Speed向量值
                this.effect.object.setVector("Speed", new mw.Vector(0,0,150));
                // 设置特效参数Color颜色值
                this.effect.object.setColor("Color", new mw.LinearColor(1,0,0,1));
            }
    }
}

Hierarchy ​

Table of contents ​

Properties
​

onFinish: MulticastDelegate<() => void>
特效播放完毕事件
click

Properties
​

onBeforeDestroyDelegate: MulticastDelegate<() => void>
物体销毁前事件回调
onCustomPropertyChange: Readonly<MulticastDelegate<(path: string, value: unknown, oldValue: unknown) => void>> other
监听自定义属性同步事件
onDestroyDelegate: MulticastDelegate<() => void>
物体销毁后事件回调

Accessors
​

duration(): number client
获取特效循环次数，仅对非永久循环特效有效
loopCount(): number client
获取特效循环次数，仅对非永久循环特效有效
timeLength(): number client
获取特效单次播放时长(s)
click

Accessors
​

assetId(): string
获取当前物体使用资源的GUID
gameObjectId(): string
获取物体的唯一标识（唯一标识一个对象的字符串）。
isDestroyed(): boolean
当前物体是否被销毁
isReady(): boolean
当前物体状态
localTransform(): Transform
当前物体本地变换
name(): string
返回当前物体名称
netStatus(): NetStatus
获取当前物体同步状态
parent(): GameObject
获取当前父物体
prefabAssetId(): string
返回当前物体使用的预制体资源ID，如果当前物体不是预制体，则返回空
sceneCaptureTag(): string
获取当前物体的捕捉标签
tag(): string
获取当前物体的标签
worldTransform(): Transform
当前物体世界变换

Methods
​

forceStop(): void
强制停止特效，所有粒子全部销毁
play(onSuccess?: () => void): void
播放特效
setColor(parameterName: string, value: LinearColor): void client
设置特效颜色参数值
setColorRandom(parameterName: string, maxValue: LinearColor, minValue: LinearColor): void client
设置特效颜色参数随机
setCullDistance(inCullDistance: number): void client
与玩家之间超出此距离的对象将被剪裁，最终的裁剪距离会和画质等级有关；修改此属性≤0时，裁剪距离会根据对象尺寸自动调整(自动启用CullDistanceVolume功能)
setFloat(parameterName: string, value: number): void client
设置特效标量参数值
setFloatRandom(parameterName: string, maxValue: number, minValue: number): void client
设置特效标量参数随机
setVector(parameterName: string, value: Vector): void client
设置特效向量参数值
setVectorRandom(parameterName: string, maxValue: Vector, minValue: Vector): void client
设置特效向量参数范围随机，在一定范围内取向量的随机值
stop(): void
停止特效，不影响已经生成的粒子
click

Methods
​

addComponent<T: extends Script<T>>(constructor: (...args: unknown[]) => T: extends Script<T>, bInReplicates?: boolean): T: extends Script<T>
添加一个脚本组件
asyncGetChildByName(name: string): Promise<GameObject>
异步根据名称查找子物体
asyncReady(): Promise<GameObject>
物体准备好后返回
clone(gameObjectInfo?: GameObjectInfo): GameObject
复制对象
destroy(): void
删除对象
getBoundingBox(nonColliding?: boolean, includeFromChild?: boolean, outer?: Vector): Vector
获取物体包围盒大小
getBounds(onlyCollidingComponents: boolean, originOuter: Vector, boxExtentOuter: Vector, includeFromChild?: boolean): void
获取物体边界
getChildByGameObjectId(gameObjectId: string): GameObject
根据 gameObjectId 查找子物体
getChildByName(name: string): GameObject
根据名称查找子物体
getChildByPath(path: string): GameObject
根据路径查找子物体
getChildren(): GameObject[]
获取子物体
getChildrenByName(name: string): GameObject[]
通过名字查找所有的子物体
getComponent<T: extends Script<T>>(constructor?: (...args: unknown[]) => T: extends Script<T>): T: extends Script<T>
获取指定类型的组件
getComponentPropertys<T: extends Script<T>>(constructor: (...args: unknown[]) => T: extends Script<T>): Map<string, IPropertyOptions>
获取脚本组件属性
getComponents<T: extends Script<T>>(constructor?: (...args: unknown[]) => T: extends Script<T>): T: extends Script<T>[]
获取指定类型的所有组件
getCustomProperties(): string[]
获取自定义属性名字数组，返回对象所有自定义属性。
getCustomProperty<T: extends CustomPropertyType>(propertyName: string): T: extends CustomPropertyType
获取自定义属性的值，服务器客户端均可调用，客户端调用需注意属性同步的延迟。
getCustomPropertyChangeDelegate(property): Readonly<MulticastDelegate<(path: string, value: unknown, oldValue: unknown) => void>> client
获取给定自定义属性修改时触发的事件代理。双端对象在服务器修改自定义属性后，双端均会触发事件并执行绑定函数。
getVisibility(): boolean
获取物体是否被显示
moveBy(velocity: Vector, isLocal?: boolean): void other
按给定的速度矢量随时间平滑地移动对象
moveTo(targetPosition: Vector, time: number, isLocal?: boolean, onComplete?: () => void): void other
在指定时间内从当前位置平滑移动至目标位置
rotateBy(rotation: Quaternion Rotation, multiplier: number, isLocal?: boolean): void other
按给定的旋转量随时间平滑地旋转对象
rotateTo(targetRotation: Quaternion Rotation, time: number, isLocal?: boolean, onComplete?: () => void): void other
在指定时间内从当前旋转平滑变化至目标旋转
scaleBy(scale: Vector, isLocal?: boolean): void other
按每秒给定的缩放矢量随时间平滑缩放对象
scaleTo(targetScale: Vector, time: number, isLocal?: boolean, onComplete?: () => void): void other
在指定时间内从当前缩放平滑变化至目标缩放
setAbsolute(absolutePosition?: boolean, absoluteRotation?: boolean, absoluteScale?: boolean): void
设置物体localTransform是相对于父物体或者世界
setCustomProperty(propertyName: string, value: undefined CustomPropertyType): void server
设置自定义属性的值，双端对象需在服务器调用。当设置的属性不存在时会新增自定义属性。
setVisibility(status: boolean PropertyStatus, propagateToChildren?: boolean): void
设置物体是否被显示
stopMove(): void other
中断moveTo()、moveBy()的进一步移动
stopRotate(): void other
中断从rotateTo()或rotateBy()的进一步旋转
stopScale(): void other
中断从ScaleTo()或ScaleBy()的进一步缩放
asyncFindGameObjectById(gameObjectId: string): Promise<GameObject>
通过 gameObjectId 异步查找 GameObject
asyncGetGameObjectByPath(path: string): Promise<GameObject>
通过路径异步查找物体
asyncSpawn<T: extends GameObject<T>>(assetId: string, gameObjectInfo?: GameObjectInfo): Promise<T: extends GameObject<T>>
异步构造一个物体，创建时请尽量把信息通过 gameObjectInfo 传入以达到性能最优化。
bulkPivotTo(gameObjects: GameObject[], transforms: Transform[]): void
批量设置位置
findGameObjectById(gameObjectId: string): GameObject
通过 gameObjectId 查找物体
findGameObjectByName(name: string): GameObject
通过名字查找物体
findGameObjectsByName(name: string): GameObject[]
通过名字查找物体
findGameObjectsByTag(tag: string): GameObject[]
通过自定义标签获取物体
getGameObjectByPath(path: string): GameObject
通过路径查找物体
spawn<T: extends GameObject<T>>(assetId: string, gameObjectInfo?: GameObjectInfo): T: extends GameObject<T>
构造一个物体，创建时请尽量把信息通过 gameObjectInfo 传入以达到性能最优化。

Properties ​

onFinish
​

• onFinish: MulticastDelegate<() => void>

特效播放完毕事件

Accessors ​

duration
​

• get duration(): number client

• set duration(NewDuration): void client

获取特效循环次数，仅对非永久循环特效有效

Returns ​

number循环的次数

设置特效持续时间，仅对循环特效有效

Parameters ​

NewDuration number播放的时间

loopCount
​

• get loopCount(): number client

• set loopCount(NewLoopCount): void client

获取特效循环次数，仅对非永久循环特效有效

Returns ​

number循环的次数

设置特效循环次数，仅对非永久循环特效有效

Parameters ​

NewLoopCount number循环的次数

timeLength
​

• get timeLength(): number client

获取特效单次播放时长(s)

Returns ​

number特效单次播放时长

Methods ​

forceStop
​

• forceStop(): void

强制停止特效，所有粒子全部销毁

play
​

• play(onSuccess?): void

播放特效

Parameters ​

onSuccess? () => void特效播放完成后回调 default: null

setColor
​

• setColor(parameterName, value): void client

设置特效颜色参数值

Parameters ​

parameterName string参数名 range: 想要设置的颜色参数值对应的字段
value LinearColor颜色变量

特效颜色参数为特效选中之后右侧属性面板“特效参数控制”中的"color"字段。

存在一个特效可以设置多个颜色属性的情况，如："color01"、"color02"。

setColorRandom
​

• setColorRandom(parameterName, maxValue, minValue): void client

设置特效颜色参数随机

Parameters ​

parameterName string参数名 range: 想要设置的颜色参数值对应的字段
maxValue LinearColor颜色变量最大值
minValue LinearColor颜色变量最小值

特效颜色参数为特效选中之后右侧属性面板“特效参数控制”中的"color"字段。

setCullDistance
​

• setCullDistance(inCullDistance): void client

与玩家之间超出此距离的对象将被剪裁，最终的裁剪距离会和画质等级有关；修改此属性≤0时，裁剪距离会根据对象尺寸自动调整(自动启用CullDistanceVolume功能)

Parameters ​

inCullDistance number裁剪距离 range: 建议 (2000, 4000) type: 浮点数

Precautions

最终的裁剪距离会和画质等级有关

setFloat
​

• setFloat(parameterName, value): void client

设置特效标量参数值

Parameters ​

parameterName string参数名 range: 想要设置的特效标量参数名字长度
value number标量值 range: 不做限制 type: 浮点数

setFloatRandom
​

• setFloatRandom(parameterName, maxValue, minValue): void client

设置特效标量参数随机

Parameters ​

parameterName string参数名 range: 想要设置的特效标量参数名字长度
maxValue number标量最大值 range: 不做限制 type: 浮点数
minValue number标量最小值 range: 不做限制 type: 浮点数

setVector
​

• setVector(parameterName, value): void client

设置特效向量参数值

Parameters ​

parameterName string参数名 range: 想要设置的特效标量参数名字长度
value Vector向量值

setVectorRandom
​

• setVectorRandom(parameterName, maxValue, minValue): void client

设置特效向量参数范围随机，在一定范围内取向量的随机值

Parameters ​

parameterName string参数名 range: 合理即可 range: 想要设置的特效标量参数名字长度
maxValue Vector向量最大值
minValue Vector向量最小值

stop
​

• stop(): void

停止特效，不影响已经生成的粒子